ollie/doc/usage.md

# Usage

## Server

### Start and stop

```sh
olliesrv                # start the server (foreground)
# Stop by sending SIGTERM or via the supervisor (e.g. rc-service ollie stop)
```

### TCP listener

To also accept connections over TCP (e.g. for remote access):

```sh
olliesrv -tcp :9564
```

### Debug logging

Log level is controlled by `OLLIE_LOG` (default: `warn`). Set to `debug` for verbose output:

```sh
OLLIE_LOG=debug olliesrv
```

Valid levels: `debug`, `info`, `warn`, `error`.

---

## `o` — Terminal CLI

`o` is a multi-call shell script that wraps the 9P namespace into a human-friendly interface.
Installed to `~/bin/o` by `just install-data`.

### Quick start

```sh
eval $(o env myproject default)   # set session + agent context
o prompt                           # interactive prompt REPL
```

In another terminal:

```sh
eval $(o env myproject default)
o read chat    # stream chat output
```

<table align="center" width="90%">
  <tr>
    <td width="50%" align="center">
      <a href="img/ollie-ui-composition.png"><img src="img/ollie-ui-composition.png" alt="Screenshot of o tui: two tmux panes showing chat output and prompt input, with agent state in the status bar" width="95%"></a>
      <br><em>o tui — tmux + shell commands</em>
    </td>
    <td width="50%" align="center">
      <a href="img/ollie-acme.png"><img src="img/ollie-acme.png" alt="Screenshot of ollie running in the acme text editor: multiple windows showing session tree, chat, and prompts" width="95%"></a>
      <br><em>acme — Plan 9 editor</em>
    </td>
  </tr>
</table>

### Commands

| Command | Description |
|---|---|
| `o prompt` | Interactive multi-line prompt REPL |
| `o read [-l] <path>` | Read a file (-l: loop, re-read after each return) |
| `o write <path> [data]` | Write to any file |
| `o ls [path]` | List namespace entries |
| `o ctl <cmd> [args]` | Send control command (rdwr: gets response) |
| `o generate <prompt>` | One-shot generation (no session needed) |
| `o complete <json>` | Code completion |
| `o route <task>` | Route task to best model |
| `o tui` | Launch tmux TUI |
| `o env [session] [agent]` | Print export statements for context |

### Context

Context is set via `$session` and `$agent` environment variables:

```sh
eval $(o env myproject default)   # export session=myproject agent=default

# Now every o command addresses the right agent automatically:
o ctl model        # → shows current model
o read -l statewait
```

### Path resolution

Paths are slash-delimited 9P namespace paths. The `o` CLI resolves them based
on context:

| Path type | Example | Resolves to |
|---|---|---|
| Root-level | `o read models` | `models` (no context needed) |
| Agent file | `o read state` | `session/$session/agent/$agent/state` |
| Session file | `o read env` | `session/$session/env` |
| Full path | `o read session/foo/agent/bar/chat` | Used as-is |

Root-level paths (`session/`, `agents`, `models`, `help`, `ctl`, `tools`) and
absolute paths (starting with `session/`) bypass context resolution entirely.
Agent-level files (`chat`, `state`, `prompt`, `statewait`, `cfg`, `plan`,
`log`, `cost`, `offset`, `context`, `systemprompt`) require both `$session`
and `$agent`. Session-level files (`env`, `ctl`, `id`, `name`, `paused`)
require only `$session`.

### Prompt REPL

`o prompt` is an interactive multi-line REPL with readline editing:

```
$ o prompt
[myproject/default]
Type . on a blank line to send, Ctrl+D to exit.
Slash commands: /stop /compact /kill /clear /model /backend /cwd /help

> write a fibonacci function in python
  and include a test case
  .
```

Type your prompt across multiple lines, then send with `.` on its own line.
Slash commands control the agent without sending a prompt:

| Command | Description |
|---|---|
| `/stop` | Interrupt running agent |
| `/compact` | Compact context window |
| `/kill` | Kill the session (exits REPL) |
| `/clear` | Clear history |
| `/model X` | Switch model |
| `/backend X` | Switch backend |
| `/cwd X` | Change working directory |
| `/quit` or `/q` | Kill the tmux TUI |
| `/help` | List commands |

### One-shot generation

No session or agent needed — `o generate` sends a prompt and returns a response:

```sh
o generate "explain monads in one sentence"
cat error.log | o generate   # pipe content as the prompt
echo "write a haiku about filesystems" | o generate | wc -w
```

Chain multiple steps:

```sh
echo "list 5 blog post ideas" | o generate | head -3 | o generate
```

---

## `o tui` — tmux Terminal UI

`o tui` composes `o read chat` and `o prompt` into a single tmux layout — two shell
commands in two panes, with agent state in the tmux status bar:

<p align="center">
  <a href="img/ollie-tui.png"><img src="img/ollie-tui.png" alt="Screenshot of the o tui tmux layout: chat pane on top, prompt REPL on bottom, agent state in status bar" width="75%"></a>
</p>

### Usage

```sh
eval $(o env myproject default)
o tui
```

1. Requires `$session` and `$agent` to be set.
2. Creates a tmux session named `o-<session>`.
3. Two panes:
   - **Pane 0** (top, 80%): `o read chat` — streams filtered chat output (markers stripped server-side).
   - **Pane 1** (bottom, 20%): `o prompt` — multi-line REPL (`/` prefix runs ctl commands).
4. A background loop reads `statewait` and updates the tmux status bar instantly.
5. Focuses the prompt pane and attaches.

No polling. Each read blocks until data arrives. The status bar updates on every
state transition via `statewait` — zero CPU when idle.

### tmux tips

- `Ctrl+b ;` — toggle between last two panes (fast prompt ↔ tail switch)
- `Ctrl+b z` — zoom any pane to full screen
- `Ctrl+b [` — scroll mode (arrow keys, `q` to exit)
- `Ctrl+b d` — detach (session keeps running, reattach with `tmux attach -t o-<session>`)

---

## Other front-ends

- **[ellie](ellie.md)** — Emacs session tree, chat, multi-agent
- **KDE** — plasmoid, standalone GUI, Kate plugin, KRunner

For technical details (generation parameters, sandboxing, multi-agent workflows,
tool discovery, and the raw 9P filesystem), see [doc/whitepaper.md](whitepaper.md).