lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc/ellie.md: consolidate Emacs docs, update references

This commit is contained in:
Ollie Agent 2026-08-04 20:00:38 +02:00
parent 32461e84f0
commit a0ec7130a7
5 changed files with 143 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -403,7 +403,7 @@ full variant specification.
| Capability | How | | 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 | | **Terminal TUI** | `o tui` — tmux + two shell commands, no widgets |
| **Remote execution** | Set `remote=user@host` in session config | | **Remote execution** | Set `remote=user@host` in session config |
| **Multi-agent** | `subagent_spawn` from within a session, or shell scripts | | **Multi-agent** | `subagent_spawn` from within a session, or shell scripts |

103
contrib/elisp/README.md
View File

@ -1,103 +1,8 @@
# ellie # 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. The source is `ellie.el` in this directory.
## 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

118
contrib/elisp/el/README.md
View File

@ -1,118 +1,8 @@
# ellie # 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 source is `ellie.el` in this directory.
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

133
doc/ellie.md Normal file
View File

@ -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)

2
doc/usage.md
View File

@ -300,6 +300,6 @@ Key files per agent:
## Alternative front-ends ## 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 - **KDE** — plasmoid, standalone GUI, Kate plugin, KRunner, system tray
- **Web** — built-in HTTP server (see `olliesrv -web`) - **Web** — built-in HTTP server (see `olliesrv -web`)