137 lines
3.7 KiB
Markdown
137 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
<p align="center">
|
|
<a href="img/ellie.png"><img src="img/ellie.png" alt="ellie Emacs interface showing the Ollie session tree and chat window" width="75%"></a>
|
|
</p>
|
|
|
|
## 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` / `SPC` | 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` / `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` | Close chat (stop stream, bury buffer) |
|
|
|
|
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) |