ollie/doc/usage.md

Usage

Server

Start and stop

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

olliesrv -tcp :9564

Debug logging

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

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

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

In another terminal:

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

o tui — tmux + shell commands

acme — Plan 9 editor

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 tui	Launch tmux TUI
o env [session] [agent]	Print export statements for context

Context

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

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:

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:

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:

Usage

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 — 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.