diff --git a/doc/help.md b/doc/help.md index 087680b..f107b02 100644 --- a/doc/help.md +++ b/doc/help.md @@ -1,104 +1,100 @@ # ollie -An AI agent exposed as a filesystem. Mount it, then use shell tools. +An AI agent exposed as a 9P filesystem. Mount it, then use shell tools. ## Quick start ```sh olliesrv # start the 9P server -echo "cwd=$PWD" > ~/mnt/ollie/session/new # create a session -ls ~/mnt/ollie/session/ # find the session ID -echo "hello" > ~/mnt/ollie/session//prompt # send a prompt -cat ~/mnt/ollie/session//chat # read the conversation -tail -f ~/mnt/ollie/session//chat # follow live output +echo "cwd=$PWD" | 9p write session/new # create a session +9p ls session/ # find the session ID +echo "hello" | 9p write session//prompt # send a prompt +9p read session//chat # read the conversation ``` ## Filesystem ``` ollie/ - agents available agent names (ro) cat - backends available backends (ro) cat - complete code completion (r/w) write JSON, read result - ctl server control (w) echo invalidate > - generate one-shot generation (r/w) write prompt, read result - help this file (ro) cat - models available models (ro) cat: backend\tmodel per line - route task routing (r/w) write task, read backend=X model=Y - session/ sessions ls - idx session index (ro) cat: id state cwd backend model, one per line - new create session (r/w) cat: KV template; echo "cwd=/path" > - / session directory rm -r to kill; mv to rename - cfg session config (r/w) cat: KV (backend, model, agent, cwd, params); write KV to change - chat conversation log (ro) - context rendered context window (ro) - cost estimated cost (ro) - ctl control (w) stop, kill, clear, compact, rn - ctxsz context size (ro) - env session environment (ro) - fifo.in queue a prompt (w) - fifo.out pop queued prompt (ro) - models available models (ro) - offset byte offset after last user prompt (ro) - peer/ peer links (r/w) touch to add, rm to remove, write to send prompt - plan plan scratchpad (r/w) - proc/ detached processes ls - prompt submit prompt (w) - prompt.prev previous prompt (ro) - state agent state (ro) cat: idle, thinking, calling: - statewait blocks until state changes (ro) - systemprompt rendered system prompt (ro) - tail tail helper (x) - usage token counts (ro) - t/ tool scripts (rx) ls, cat - idx tool index (ro) cat - tools tool prompt lookup (r/w) write name, read documentation - sk/ skills (r/w) ls, cat, edit - idx skill index (ro) cat - .md skill content (r/w) - u/ utility scripts (x) ls, exec - x/ system scripts (x) ls, exec - tmp/ scratch space (r/w) ls, cat, edit, rm + agents available agent names (ro) 9p read agents + backends available backends (ro) 9p read backends + complete code completion (r/w) echo JSON | 9p rdwr complete + ctl server control (w) echo invalidate | 9p write ctl + generate one-shot generation (r/w) echo prompt | 9p rdwr generate + help this file (ro) 9p read help + models available models (ro) 9p read models + route task routing (r/w) echo task | 9p rdwr route + session/ sessions (dir) + idx session index (ro) 9p read session/idx + new create session (r/w) echo "cwd=/path" | 9p write session/new + / + cfg session config (r/w) 9p read cfg; echo key=val | 9p write cfg + chat conversation log (ro) 9p read chat + context rendered context (ro) 9p read context + cost estimated cost (ro) 9p read cost + ctl control (w) echo stop | 9p write ctl + ctxsz context size (ro) 9p read ctxsz + env session environment (ro) 9p read env + fifo.in queue a prompt (w) echo prompt | 9p write fifo.in + fifo.out pop queued prompt (ro) 9p read fifo.out + models available models (ro) 9p read models + offset byte after last prompt (ro) 9p read offset + peer/ peer links (dir) 9p create peer/; 9p rm peer/ + plan plan scratchpad (r/w) 9p read plan; echo text | 9p write plan + proc/ detached processes (dir) 9p ls proc/ + prompt submit prompt (w) echo text | 9p write prompt + prompt.prev previous prompt (ro) 9p read prompt.prev + state agent state (ro) 9p read state + statewait blocks until change (ro) 9p read statewait + systemprompt rendered system prompt (ro) 9p read systemprompt + usage token counts (ro) 9p read usage + t/ tool scripts (dir) 9p ls t/ + idx tool index (ro) 9p read t/idx + tools tool prompt lookup (r/w) echo name | 9p rdwr tools ``` ## Request-response files -`complete`, `generate`, `route`, and `tools` work the same way: open r/w, write a query, read the result. +`complete`, `generate`, `route`, and `tools` work the same way: write a query, read the result. ```sh -exec 3<>~/mnt/ollie/tools; echo 'file_edit' >&3; cat <&3; exec 3>&- -exec 3<>~/mnt/ollie/route; echo 'implement login' >&3; cat <&3; exec 3>&- +echo 'file_edit' | 9p rdwr tools +echo 'implement login' | 9p rdwr route ``` -Or with `9p rdwr`: `echo 'file_edit' | 9p rdwr ollie/tools` - ## Session management ```sh -echo "cwd=/path backend=ollama model=qwen3:8b" > ~/mnt/ollie/session/new -mv ~/mnt/ollie/session/ ~/mnt/ollie/session/my-name # rename -rm -r ~/mnt/ollie/session/ # kill -echo stop > ~/mnt/ollie/session//ctl # interrupt current turn +echo "cwd=/path backend=ollama model=qwen3:8b" | 9p write session/new +9p rm session/ # kill +echo stop | 9p write session//ctl # interrupt ``` ## Switching backend/model/agent ```sh -cat ~/mnt/ollie/backends # list backends -cat ~/mnt/ollie/session//models # list models for current backend -echo backend=ollama > ~/mnt/ollie/session//cfg -echo model=qwen3:8b > ~/mnt/ollie/session//cfg -echo agent=myagent > ~/mnt/ollie/session//cfg +9p read backends # list backends +9p read session//models # list models +echo backend=ollama | 9p write session//cfg +echo model=qwen3:8b | 9p write session//cfg +echo agent=myagent | 9p write session//cfg ``` Writes to cfg are rejected while the agent is running. +## Agent directory (`session/{id}/agent/{aid}/`) + +Each session has at least one agent. The agent directory lives at +`session/{id}/agent/{aid}/` and contains the same files as the session +directory above (`chat`, `prompt`, `state`, `statewait`, `cfg`, `ctl`, +`offset`, `usage`, `cost`, `ctxsz`, `systemprompt`, `prompt.prev`, +`context`, `fifo.in`, `fifo.out`, `plan`, `proc/`, `t/`, `tools`). + ## Environment ``` OLLIE_BACKEND ollama | openai | openrouter | anthropic | copilot | kiro OLLIE_MODEL default model name -OLLIE mount path (default: ~/mnt/ollie) OLLIE_TOOLS_PATH tool scripts directory (default: ~/.config/ollie/tools) OLLIE_SKILLS_PATH skills directory (default: ~/.config/ollie/skills) OLLIE_MEMORY_PATH memory directory (default: ~/.config/ollie/memory)