From a0ec7130a7f4c34b6a20c264cf99d9266ee96aa3 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 4 Aug 2026 20:00:38 +0200 Subject: [PATCH] doc/ellie.md: consolidate Emacs docs, update references --- README.md | 2 +- contrib/elisp/README.md | 103 ++-------------------------- contrib/elisp/el/README.md | 118 ++------------------------------ doc/ellie.md | 133 +++++++++++++++++++++++++++++++++++++ doc/usage.md | 2 +- 5 files changed, 143 insertions(+), 215 deletions(-) create mode 100644 doc/ellie.md diff --git a/README.md b/README.md index afe2030..6ec83ad 100644 --- a/README.md +++ b/README.md @@ -403,7 +403,7 @@ full variant specification. | Capability | How | |---|---| -| **Run an agent** | `olliesrv` → any frontend (ellie, KDE, acme, `o tui`) | +| **Run an agent** | `olliesrv` → any frontend ([ellie](doc/ellie.md), KDE, acme, `o tui`) | | **Terminal TUI** | `o tui` — tmux + two shell commands, no widgets | | **Remote execution** | Set `remote=user@host` in session config | | **Multi-agent** | `subagent_spawn` from within a session, or shell scripts | diff --git a/contrib/elisp/README.md b/contrib/elisp/README.md index da1fd0f..c9078bf 100644 --- a/contrib/elisp/README.md +++ b/contrib/elisp/README.md @@ -1,103 +1,8 @@ # ellie -An [ollie](../README.md) front-end, via [ollie-9p](../9p/), for our emacs friends. Provides a chat buffer, prompt composition, interrupt handling, and session management. The agent core, backends, and tools are handled by the ollie-9p server. +ellie is an [ollie](https://ollie.lneely.de) front-end for Emacs. -## Background +Documentation has moved to **[doc/ellie.md](../../doc/ellie.md)** — see there +for installation, usage, session tree, and keybindings. -ellie talks to ollie through the `ollie-9p` CLI tool, which speaks the 9P protocol directly over a Unix socket. No FUSE mount required. - -## Prerequisites - -[olliesrv](../9p/) must be running: - -```sh -olliesrv -``` - -## Installation - -Add `ellie.el` to your load path: - -```elisp -(add-to-list 'load-path "/path/to/ellie") -(require 'ellie) -``` - -Or with `use-package`: - -```elisp -(use-package ellie - :load-path "/path/to/ellie") -``` - -Optionally set default session options: - -```elisp -(setq ellie-default-session-opts '(("backend" . "ollama") ("model" . "qwen3:8b"))) -``` - -## Usage - -| Command | Description | -|---------|-------------| -| `M-x ellie` | Open chat; attach to last session for `default-directory`, or create a new one | -| `M-x ellie-new-and-open` | Force-create a new session and open chat | -| `M-x ellie-attach-and-open` | Attach to an existing session by ID | - -## UI - -In the `*ellie*` buffer: - -| Key | Action | -|-----|--------| -| `RET` | Open input window and compose a prompt | -| `C-c C-q` | Open input window and compose a queued prompt | -| `C-c C-c` | Interrupt the running turn | -| `C-c C-k` | Kill the current session | -| `C-c C-r` | Rename the current session | -| `C-c C-n` / `n` | New session | -| `C-c C-a` | Attach to a different session | -| `C-c C-p` | Show the rendered system prompt | -| `g` | Force-refresh the chat log | - -In the `*ellie-input*` window: - -| Key | Action | -|-----|--------| -| `C-c C-c` | Submit | -| `C-c C-k` | Cancel | - -The input window accepts multi-line prompts. Queued prompts are held until the current turn finishes. - -The mode line shows the active session ID and current state (`idle` or the running state name). - -## Code Completion - -`ellie-complete-at-point` requests a code completion via `ollie-9p rdwr complete`. - -### Configuration - -| Variable | Env var | Description | -|----------|---------|-------------| -| `ellie-complete-backend` | `OLLIE_COMPLETE_BACKEND` | Backend for completion (required) | -| `ellie-complete-model` | `OLLIE_COMPLETE_MODEL` | Model for completion (required) | -| `ellie-complete-prefix-max` | — | Max chars of context before point (default: 4000) | -| `ellie-complete-suffix-max` | — | Max chars of context after point (default: 1000) | - -Example: - -```elisp -(setq ellie-complete-backend "ollama") -(setq ellie-complete-model "qwen3:4b") -``` - -Or via environment / `~/.config/ollie/env`: - -``` -OLLIE_COMPLETE_BACKEND=ollama -OLLIE_COMPLETE_MODEL=qwen3:4b -``` - -## License - -GPLv3 \ No newline at end of file +The source is `ellie.el` in this directory. \ No newline at end of file diff --git a/contrib/elisp/el/README.md b/contrib/elisp/el/README.md index 4c93297..c9078bf 100644 --- a/contrib/elisp/el/README.md +++ b/contrib/elisp/el/README.md @@ -1,118 +1,8 @@ # ellie -An [ollie](../README.md) front-end, via [ollie-9p](../9p/), for our emacs friends. Provides a chat buffer, prompt composition, interrupt handling, and session management. The agent core, backends, and tools are handled by the ollie-9p server. +ellie is an [ollie](https://ollie.lneely.de) front-end for Emacs. -## Background +Documentation has moved to **[doc/ellie.md](../../doc/ellie.md)** — see there +for installation, usage, session tree, and keybindings. -The ollie-9p filesystem proved that a full interactive client could be built using nothing but plain file I/O. ellie applies this in a different environment, using standard Emacs file operations with no knowledge of ollie's internals and no dependencies beyond Emacs itself. - -The answer is yes. The implementation uses only built-in Emacs file operations: `write-region` to submit prompts, a half-second timer to tail the chat log by comparing file sizes, and `insert-file-contents` to read new content into a buffer. The ollie-9p filesystem is the entire API surface. - -## Prerequisites - -[olliesrv](../9p/) must be running and mounted before use: - -```sh -olliesrv -``` - -By default the server mounts at `~/mnt/ollie`. Set `OLLIE` to use a different path. - -## Installation - -Add `ellie.el` to your load path: - -```elisp -(add-to-list 'load-path "/path/to/ellie") -(require 'ellie) -``` - -Or with `use-package`: - -```elisp -(use-package ellie - :load-path "/path/to/ellie") -``` - -Optionally set a mount path and default session options: - -```elisp -(setq ollie-mount-directory "/custom/mount") -(setq ollie-default-session-opts '(("backend" . "ollama") ("model" . "qwen3:8b"))) -``` - -## Usage - -| Command | Description | -|---------|-------------| -| `M-x ellie` | Open chat; attach to last session for `default-directory`, or create a new one | -| `M-x ellie-new-and-open` | Force-create a new session and open chat | -| `M-x ellie-attach-and-open` | Attach to an existing session by ID | - -## UI - -In the `*ellie*` buffer: - -| Key | Action | -|-----|--------| -| `RET` | Open input window and compose a prompt | -| `C-c C-q` | Open input window and compose a queued prompt | -| `C-c C-c` | Interrupt the running turn | -| `C-c C-k` | Kill the current session | -| `C-c C-r` | Rename the current session | -| `C-c C-n` / `n` | New session | -| `C-c C-a` | Attach to a different session | -| `C-c C-d` | Open the ollie mount in Dired | -| `C-c C-p` | Show the rendered system prompt | -| `g` | Force-refresh the chat log | - -In the `*ellie-input*` window: - -| Key | Action | -|-----|--------| -| `C-c C-c` | Submit | -| `C-c C-k` | Cancel | - -The input window accepts multi-line prompts. Queued prompts are held until the current turn finishes. - -The mode line shows the active session ID and current state (`idle` or the running state name). - -## Code Completion - -`ellie-complete` provides ghost-text code completion via the `/complete` endpoint on ollie-9p (using `9p rdwr` on the namespace). Press `M-/` to request a completion at point; the result appears as gray italic ghost text. - -| Key | Action | -|-----|--------| -| `M-/` | Request completion at point (or for selected region) | -| `TAB` / `RET` | Accept the suggestion | -| Any other key | Dismiss | -| `M-/` (while ghost visible) | Request a new completion (retries preserve region) | - -With an active region, the completion replaces the selected text. Without a region, it inserts at point. - -### Configuration - -| Variable | Env var | Description | -|----------|---------|-------------| -| `ellie-complete-backend` | `OLLIE_COMPLETE_BACKEND` | Backend for completion (required) | -| `ellie-complete-model` | `OLLIE_COMPLETE_MODEL` | Model for completion (required) | -| `ellie-complete-prefix-max` | — | Max chars of context before point (default: 4000) | -| `ellie-complete-suffix-max` | — | Max chars of context after point (default: 1000) | - -Example: - -```elisp -(setq ellie-complete-backend "ollama") -(setq ellie-complete-model "qwen3:4b") -``` - -Or via environment / `~/.config/ollie/env`: - -``` -OLLIE_COMPLETE_BACKEND=ollama -OLLIE_COMPLETE_MODEL=qwen3:4b -``` - -## License - -GPLv3 \ No newline at end of file +The source is `ellie.el` in this directory. \ No newline at end of file diff --git a/doc/ellie.md b/doc/ellie.md new file mode 100644 index 0000000..262ddc3 --- /dev/null +++ b/doc/ellie.md @@ -0,0 +1,133 @@ +# ellie — Emacs front-end for ollie + +ellie talks to an ollie session through the `ollie-9p` CLI tool, which speaks +the 9P protocol directly over a Unix socket. No FUSE mount required. The +ollie-9p filesystem is the entire API surface — ellie uses nothing but +plain file I/O. + +## Prerequisites + +[olliesrv](../README.md) must be running: + +```sh +olliesrv +``` + +## Installation + +Add `ellie.el` to your load path: + +```elisp +(add-to-list 'load-path "/path/to/ellie/contrib/elisp") +(require 'ellie) +``` + +Or with `use-package`: + +```elisp +(use-package ellie + :load-path "/path/to/ellie/contrib/elisp") +``` + +Optionally set default session options: + +```elisp +(setq ellie-default-session-opts '(("backend" . "ollama") ("model" . "qwen3:8b"))) +``` + +## Quick start + +``` +M-x ellie +``` + +Opens the session tree (`*ellie-sessions*`), attached to the last-known +session for your working directory if it still exists. + +## Session tree + +The tree shows all sessions organized by active/inactive state: + +``` +▼ Active + ▼ myproject (2) + default [idle] + reviewer [idle] + ▼ scratch (1) + 0 [calling: file_read] +▶ Inactive +``` + +| Key | Action | +|-----|--------| +| `RET` | Expand/collapse header or session; select agent | +| `e` | Toggle expand/collapse | +| `n` | New session | +| `N` | New agent (prompts for profile, cwd) | +| `c` | Open chat buffer for selected agent | +| `g` | Refresh tree | +| `C-c C-c` | Send prompt to selected agent | +| `C-c C-q` | Queue prompt for selected agent | +| `C-c C-s` | Stop running agent | +| `C-c C-k` | Kill session or agent at point | +| `C-c C-p` | Show system prompt | +| `q` | Quit tree | + +Sessions are addressed by name (`session/{sname}`). Agents within a session +are addressed by their auto-generated ID (`session/{sname}/agent/{aname}`). +The tree discovers both automatically. + +## Chat buffer + +Once an agent is selected, `c` opens the chat buffer (`*ellie*`): + +| Key | Action | +|-----|--------| +| `RET` | Open input window to compose a prompt | +| `C-c C-q` | Open input window to compose a queued prompt | +| `C-c C-c` | Interrupt the running turn | +| `C-c C-s` | Stop agent | +| `C-c C-k` | Kill the current session | +| `C-c C-n` | New session | +| `C-c C-a` | Attach to a different session | +| `C-c C-p` | Show the rendered system prompt | +| `g` | Force-refresh the chat log | +| `q` | Return to session tree | + +The input window (`*ellie-input*`): + +| Key | Action | +|-----|--------| +| `C-c C-c` | Submit prompt | +| `C-c C-k` | Cancel | + +Queued prompts are held until the current turn finishes. The mode line shows +`ellie:session/agent` and the current state. + +## Creating sessions and agents + +Sessions are created by writing `key=value` pairs to `session/new`. The +`ellie-new-session` command does this for you, injecting `cwd` from +`default-directory`. + +Agents are created by writing to `session/{sname}/agent/new`. The +`ellie-new-agent` command prompts for an agent profile and working directory. + +You can also create sessions and agents directly from dired — navigate to +`session/` (or use `C-c C-d` if you have a mount), open `new`, write +`key=value` lines, and save. + +## Architecture + +The chat log is append-only. ellie polls it on a half-second timer, comparing +file sizes. New content is appended to the buffer and ANSI color codes are +rendered. State is read from `session/{sname}/agent/{aname}/state`. + +Everything goes through `ollie-9p` — there is no emacs-specific daemon, no +IPC protocol, no external processes beyond the CLI tool. + +## Reference + +- README: [/README.md](../README.md) +- Usage guide: [/doc/usage.md](usage.md) +- Technical whitepaper: [/doc/whitepaper.md](whitepaper.md) \ No newline at end of file diff --git a/doc/usage.md b/doc/usage.md index 0e0cfb0..78a0245 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -300,6 +300,6 @@ Key files per agent: ## Alternative front-ends -- **[ellie](../el/)** — Emacs front-end (`ellie.el`) +- **[ellie](ellie.md)** — Emacs front-end (session tree, chat, multi-agent) - **KDE** — plasmoid, standalone GUI, Kate plugin, KRunner, system tray - **Web** — built-in HTTP server (see `olliesrv -web`) \ No newline at end of file