3.9 KiB

Raw Blame History

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.

Read the current file, project root, selection, cursor, or diff.
Ensure olliesrv is running.
Select or create an agent with cwd set to the project root.
Construct a prompt containing the operation and source context.
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 uses shell commands and the editor’s 9P namespace. Kate uses a native plugin with project selection, context actions, diff review, and completion. Other editors and IDEs can use commands, plugins, key bindings, or automation APIs with the same 9P operations.

See architecture-9p.md for the namespace, architecture-kde.md for the KDE client, and architecture-core.md for agents and sessions.

3.9 KiB Raw Blame History Unescape Escape