ollie/doc/architecture-ide.md

Editor Integration

Ollie exposes editor integration through the 9P namespace. Acme and Kate are examples of clients, not separate Ollie workflows.

An integration reads editor state, writes a prompt to an agent, and reads the result. It does not embed the agent loop, prompt assembly, backend selection, tool execution, or session store.

editor or IDE
  ├─ file, selection, cursor, project, or diff
  └─ 9P client → agent/.../prompt
                    ├─ chat / chat.raw
                    ├─ statewait
                    └─ ctl

Integration pattern

This is a concrete pattern for extending an editor. It is not a required interface. People can add as much or as little integration as their editor and workflow warrant.

1. Read the current file, project root, selection, cursor, or diff.
2. Ensure olliesrv is running.
3. Select or create an agent with cwd set to the project root.
4. Construct a prompt containing the operation and source context.
5. Write it to session/{sname}/agent/{aname}/prompt.

Use ollie-9p, the o wrapper, or a native 9P client library. A native plugin is optional. The integration can stop after writing the prompt; the user can observe and control the agent through ollie-gui, a terminal, or another 9P client tiled beside the editor.

selection=$(...)  # editor-specific
file=$(...)

printf 'Read %s and explain this code:\n\n```\n%s\n```\n' \
  "$file" "$selection" |
  o project/agent prompt

Prompt and edit pattern

A useful prompt and edit pattern is:

• State whether the operation is read-only or mutating.
• Include the source path and project working directory.
• Treat selections as context, not instructions or authoritative source.
• Require repository inspection before edits.
• Require formatting and relevant tests or diagnostics after edits.

The editor does not need to display agent output or reload files itself. Use the existing editor behavior for changed files and a separate Ollie client for chat, state, and control.

Operation	9P integration
Explain file or selection	Write a read-only prompt; read chat.
Fix, refactor, document, or add tests	Write a mutating prompt; read statewait; reload the buffer.
Review a diff	Send the diff as fenced diff context.
Inline completion	Send a bounded prefix/suffix request to root generate.
Agent control	Write a command to ctl.

Companion and observer agents

A companion agent receives direct prompts while the coder works. An observer agent receives diffs or editor state through feed.

feed is change-detecting. A write stores the value and signals waiters. A blocking read returns only when the value differs from the reader’s previous value. The agent feed consumer submits new values as prompts.

o project/observer ctl agent observer
while :; do
    git diff HEAD -- | o project/observer write feed
    sleep 5
done

Automation level is a client policy:

• Manual queries minimize automation and token use.
• Selection actions provide human-triggered focused operations.
• Companion agents provide interactive assistance.
• Observers trigger review on state changes.
• Cursor completion uses bounded one-shot generation.
• External scripts or task systems can trigger agents and collect results.

Trigger frequency, context size, model, and step limits determine latency, token use, process cost, and energy use. They do not change the 9P integration boundary.

Examples

Acme and Kate are two clients that implement the pattern above. The examples below describe their current behavior; they are not requirements or a canonical feature set.

Acme

The Acme scripts use Acme’s own 9P namespace to obtain the window filename and selection, then use the o wrapper to write a prompt to the project agent. They are ordinary shell scripts.

Setup:

export PATH="$PATH:/path/to/ollie/data/scripts/acme"
eval "$(o env mysession myagent)"

Add commands to an Acme window tag:

OllieHere AskFile Explain Fix Refactor Document AddTests SendVerbatim

A selection command performs three operations:

echo 'addr=dot' | 9p write acme/$winid/ctl
selection=$(9p read acme/$winid/xdata)
echo "$prompt" | o "$OLLIE_SESSION/$OLLIE_AGENT" prompt

Explain constructs a read-only prompt containing the filename and selected code. Fix, Refactor, Document, and AddTests construct mutating prompts that tell the agent to inspect the repository, make a focused change, and run relevant verification. SendVerbatim sends a fenced selection as context without treating it as instructions. AskFile sends the current filename without requiring a selection. OllieHere selects or creates the project agent.

OllieHere is idempotent. It prints the project agent path, for example:

OllieHere: acme/6c460de7

The path can be passed to win, which runs an ordinary command inside an embedded Acme terminal window:

win o acme/6c460de7 read chat
win o acme/6c460de7 prompt

OllieHere prints the session/agent path. win starts the command line in Acme. The remainder is the command and its arguments; win runs it and exits when the command exits. The first command displays the agent chat stream in the embedded terminal. The second runs the prompt REPL there. These are ordinary terminal commands, not special Acme UI components.

Kate

The Kate plugin implements the same pattern natively. It obtains the active document and selection through KTextEditor, ensures a project agent, and writes directly to the agent’s prompt file through libollie9p.

Its context-menu actions are concrete examples:

Action	Prompt input
Ask about file	Active document path.
Explain this	Selection, or the current line when no selection exists, plus the file path.
Fix this	Selection and source location.
Refactor this	Selection and source location.
Add tests for this	Selection and source location.
Document this	Selection and source location.
Send verbatim	Selection in a language-tagged code fence.
Review Diff	Git++’s current diff, or the active diff document.
Start Session	Ensures the agent and updates its project working directory.

Kate also provides an optional one-shot completion path. It sends a bounded prefix and suffix around the cursor to the root generate operation and displays the returned code as ghost text. This is separate from the project agent’s prompt stream.

The Kate implementation is a native plugin, but the integration boundary is unchanged: obtain editor context and write a 9P prompt. The plugin does not provide an integrated chat or prompt window; select the corresponding Kate session in the KDE GUI and use its chat stream to interact with the agent. If preferred, run o kate/{session} tui in Kate’s integrated terminal to use the TUI.

Summary

An editor integration is a 9P client:

editor context → agent/.../prompt → Ollie agent → files/chat/state

Read context from the editor, select an agent for the project, construct a prompt, and write it to prompt. The Kate plugin does not provide an integrated chat or prompt window; use the KDE GUI or TUI as the agent interaction surface.

A shell command is sufficient when the editor exposes the needed context and command execution. Otherwise, use its extension or plugin mechanism. Vim, Emacs, Acme, Kate, and other editors can use the same pattern through whatever integration mechanism they provide. The editor need only provide context and a way to issue a 9P request.