13 KiB

Raw Blame History

Coding Integrations

Ollie gives coders the same agent through two editor styles:

Acme: small shell scripts placed in the window tag. They read the current file or selection through Acme's 9P namespace and submit a focused prompt through the o client.
Kate: a native KDE plugin. It adds context-menu actions, project-agent selection, diff review, and optional ghost-text completion. It talks to Ollie through the shared 9P client library.

Neither editor implements agent logic. Both select an agent, provide source context, write to its prompt file, and let the agent use the repository tools and normal verification workflow.

Shared workflow

editor selection/file
        │
        ├─ Acme: 9p read acme/$winid/{tag,xdata}
        └─ Kate: KTextEditor document/selection API
                         │
                         ▼
              project-scoped Ollie agent
                         │
                         └─ write session/.../prompt
                                      │
                                      ▼
                         agent edits or reports via 9P

The Acme helper acme-ollie-ensure and the Kate plugin both associate work with the project directory. Acme walks to the Git repository root and hashes that path into an agent name. Kate selects or creates an agent for the current project and updates its working directory. This keeps files from one checkout on one agent while separating projects.

Acme commands

The scripts live in data/scripts/acme/. Add that directory to PATH, then add the command names to an Acme window tag. Commands requiring context use the current window ID, read the window tag for the filename, select dot, and read xdata for the selection.

Command	Input	Behavior	Mutates files?
`OllieHere`	Current window/project	Ensures the `acme` session and project agent exist, then prints `OLLIE_SESSION` and `OLLIE_AGENT`.	No
`AskFile`	Current file	Asks for a read-only implementation-oriented explanation of the complete file, including purpose, data flow, dependencies, and tests.	No
`Explain`	Selection	Requests a concise read-only explanation of the selected code, its inputs/outputs, risks, and edge cases.	No
`SendVerbatim`	Selection	Sends the selection as user-provided fenced context and waits for a later request. It explicitly tells the agent not to treat the selection as instructions.	No
`Fix`	Selection	Asks the agent to inspect the real file, make the smallest safe fix, format it, and run relevant tests or diagnostics.	Yes
`Refactor`	Selection	Asks for one focused behavior-preserving refactor without unrelated rewrites, followed by verification.	Yes
`Document`	Selection	Adds documentation comments to selected declarations without changing executable or unrelated code.	Yes
`AddTests`	Selection	Reads the source, existing tests, and project conventions, then adds focused tests and runs the relevant test command.	Yes

The scripts deliberately include the filename and selected text but instruct the agent to read the actual repository before editing. A selection is context, not authoritative source. AskFile, Explain, and SendVerbatim are read-only prompts; Fix, Refactor, Document, and AddTests are editing prompts with explicit verification requirements.

Acme setup

export PATH="$PATH:/path/to/ollie/data/scripts/acme"
# In an Acme tag:
OllieHere AskFile Explain Fix Refactor Document AddTests SendVerbatim

OllieHere is optional because every command calls acme-ollie-ensure itself. The helper creates the acme session and a project-root agent when needed. It prints shell assignments for callers that want to inspect or reuse the selected context:

eval "$(acme-ollie-ensure)"
echo "$OLLIE_SESSION/$OLLIE_AGENT"

Kate equivalents

Kate exposes similar actions through the document context menu. The plugin connects directly to 9P using libollie9p rather than spawning a shell script for every request.

Acme command	Kate action	Current behavior
`OllieHere`	Ollie: Start Session	Ensures an agent, associates it with the current project, and updates its `cwd`. Kate performs this automatically when an action needs an agent.
`AskFile`	Ollie: Ask about file	Sends `Describe and explain this file: <path>` for the active document.
`Explain`	Ollie: Explain this	Sends the selection and file path for explanation. If there is no selection, it explains the current line.
`SendVerbatim`	Ollie: Send verbatim	Sends the selected text in a language-tagged fence derived from Kate's highlighting mode.
`Fix`	Ollie: Fix this	Sends the selected code and source location with a fix request.
`Refactor`	Ollie: Refactor this	Sends the selected code and source location with a refactor request.
`AddTests`	Ollie: Add tests for this	Sends the selected code with a request to write tests.
`Document`	Ollie: Document this	Sends the selected code with a request for documentation comments.
—	Ollie: Review Diff	Reviews the current diff from Git++ when available, otherwise the active diff document.

The Kate actions are intentionally parallel rather than identical. Acme scripts contain detailed task-specific safety and verification instructions. Kate currently sends shorter action prompts for selection operations. The agent is still responsible for reading repository context, making edits, and verifying them.

Kate-only completion support

Kate also provides automatic ghost-text completion. When enabled, the plugin:

Collects the text before and after the cursor.
Limits the prefix to 12,000 characters and the suffix to 1,000 characters.
Adds the file path and working directory.
Calls the root generate 9P operation through ollie-9p rdwr generate.
Requests raw insertable code with no explanation or markdown fences.
Displays the result as inline ghost text and a continuation overlay.
Lets the user accept, dismiss, or cycle through completion history.

The completion request can use plugin-configured backend and model overrides. It is separate from the agent session prompt path: it is a one-shot generation request, not a turn queued into the project agent.

Observer and companion patterns

An editor integration does not need to be an active operator. Ollie can assist along a spectrum of automation, context, token use, and environmental cost:

Manual query: ask about a file or selection only when needed. Lowest automation and token use.
Selection actions: explain, fix, refactor, document, or add tests from an editor action. The coder chooses each operation.
Companion agent: keep a project agent available for prompts, chat, plans, and controls while the coder works. It is interactive but not continuously triggered.
Observer agent: feed a second, usually read-only agent the current diff or editor state. It wakes only when the feed changes and reports bugs, missed error handling, security issues, or other requested concerns.
Completion assistant: request bounded one-shot generation at the cursor. Kate’s ghost text is an example; it does not add every completion to the agent’s conversation history.
Automated workflow: let scripts or external task systems trigger agents, collect statewait, and route results. This has the highest automation and potentially the highest token and process cost.

Companion and observer wiring

Every agent has a change-detecting feed file. Writing new content stores it and signals waiters. A blocking read returns only when the content differs from the reader’s previous value. The agent’s feed consumer submits each new value as a prompt, so a companion or observer can be driven by editor state or git diff without polling the model continuously.

# Human coding session plus read-only observer
o myproj/obs new /path/to/repo
o myproj/obs ctl agent observer
while :; do
    git diff HEAD -- | o myproj/obs write feed
    sleep 5
done

A more event-driven driver can wait for the coder to finish a turn:

while :; do
    o myproj/coder read statewait >/dev/null
    git diff HEAD -- | o myproj/obs write feed
done

The observer does not need write access to the repository. It receives the diff as context, can inspect the checkout using read-only tools, and reports through chat. A companion can instead share the normal project agent and receive direct prompts.

Choosing the level of assistance

The right pattern depends on more than convenience:

Pattern	Automation	Typical cost	Good fit
Manual query	Low	Low	Occasional explanation or second opinion.
Selection action	Low	Low–medium	Focused edits with human initiation.
Companion	Medium	Medium	Interactive pair programming.
Observer	Medium–high	Medium–high	Continuous review while code changes.
Cursor completion	High frequency	Variable	Local, bounded implementation suggestions.
Automated workflow	High	High or bounded by policy	Repeatable checks, external task graphs, or CI-like work.

Token use is a design parameter. Send focused selections instead of whole repositories, trigger observers on meaningful changes instead of every keystroke, use read-only profiles for review, and apply explicit step or model limits when automation is not worth the cost. The same choices reduce latency, process churn, and energy use. Lower automation is not a failure mode; it is often the responsible choice for simple work or expensive models.

These patterns are integrations over sessions, feed, statewait, chat, tools, and 9P. Ollie does not need a separate observer runtime, companion subsystem, or automation scheduler. Ollie does not require a native plugin. Any editor that can run a command, read and write files, or open a Unix socket can use Ollie through the 9P namespace.

The general integration pattern is:

Identify the editor’s current file, project root, selection, cursor position, or diff.
Ensure olliesrv is running and choose an agent whose cwd is the project root.
Build a short, explicit prompt containing the operation and source context.
Write the prompt to session/{sname}/agent/{aname}/prompt.
Read chat, statewait, or chat.raw for progress and results.
Refresh the editor buffer or show the response according to the user’s request.

editor command/action
        │
        ├─ current file, selection, project, diff
        │
        └─ 9P client → agent/.../prompt
                         │
                         ├─ chat / chat.raw
                         └─ statewait

A minimal shell integration can use the o client:

selection=$(...)                         # obtain from the editor
file=$(...)
project=$(...)

printf 'name=%s\ncwd=%s\n' "$project" "$project" \
  | ollie-9p write session/my-editor/agent/new

printf 'Read %s. Explain this selected code:\n\n```\n%s\n```\n' \
  "$file" "$selection" \
  | o my-editor/my-agent prompt

For an editor with a plugin API, use its native document and selection APIs, then call ollie-9p, the o wrapper, or a 9P client library. Native integrations should preserve the same boundaries as the Acme scripts and Kate plugin:

Keep prompts explicit about whether the operation is read-only or may edit files.
Include the source path and project working directory.
Treat selections as context, not instructions or authoritative repository state.
Ask the agent to inspect the real files before editing.
Request formatting and relevant tests or diagnostics after changes.
Use statewait or streaming chat instead of polling when the client supports blocking reads.
Never maintain a second session or agent store in the editor.

Operation patterns

Editor capability	Ollie operation
Explain selection	Read selection, write a read-only prompt, display `chat`.
Fix or refactor selection	Include path and selection, write an editing prompt, monitor `statewait`, then reload the buffer.
Add tests or documentation	Use a task-specific prompt and require repository inspection and verification.
Ask about the current file	Send the path and request a read-only whole-file inspection.
Review a diff	Obtain the editor/VCS diff and send it as fenced `diff` context.
Inline completion	Use root `generate` with a bounded prefix/suffix request; this is separate from the agent turn path.
Agent controls	Write commands to the agent `ctl` file.

The editor can use any language or integration mechanism. The only Ollie-specific dependency is the 9P namespace documented in architecture-9p.md. The agent, tools, prompt assembly, backend selection, and persistent state remain in Ollie rather than in the editor integration.

Use Acme when you want small, inspectable shell commands that fit naturally into tags, pipes, and the Acme 9P namespace. Use Kate when you want persistent project selection, native context menus, diff review, syntax-aware completion, and a GUI workflow.

Both integrations remain thin clients. They do not duplicate session state, prompt assembly, tool execution, or backend configuration. See architecture-9p.md for the namespace and architecture-kde.md for the KDE build and plugin layout.

13 KiB Raw Blame History Unescape Escape