ollie/doc/help.md

ollie

An AI agent exposed as a filesystem. Mount it, then use shell tools.

Quick start

olliesrv start                                       # start the 9P server
echo "cwd=$PWD" > ~/mnt/ollie/s/new              # create a session
ls ~/mnt/ollie/s/                                    # find the session ID
echo "hello" > ~/mnt/ollie/s/<id>/prompt             # send a prompt
cat ~/mnt/ollie/s/<id>/chat                          # read the conversation
tail -f ~/mnt/ollie/s/<id>/chat                      # follow live output

Filesystem

ollie/
  a/              agent configs (r/w)        ls, cat, cp, mv, rm
  backends        available backends (ro)    cat
  help            this file (ro)             cat
  m/              memories (r/w)             ls, cat, edit
  p/              prompt templates (ro)      ls, cat
  s/              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" >
    ls            list sessions (x)          exec s/ls
    kill          kill session (x)           exec s/kill <id>
    sh            interactive shell (x)      exec s/sh [-new|-resume] [-backend B] [-model M]
    b             batch session (x)          exec s/b [flags] [prompt...]
    bfg           foreground query (x)       exec s/bfg [flags] [prompt...]
    bbg           background query (x)       exec s/bbg [flags] [prompt...]
    cleanup       kill idle sessions (x)     exec s/cleanup
    <id>/         session directory          rm -r to kill; mv to rename
      cfg         session config (r/w)       cat: KV (state, backend, model, agent, cwd, params); write KV to change
      chat        conversation log (r/w; write to save transcript to tr/)
      context     rendered context window (ro)
      cost        estimated cost (ro)
      ctl         control (w)                stop, kill, clear, compact, rn <name>
      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)
      plan        plan scratchpad (r/w)
      prompt      submit prompt (w)
      prompt.prev previous prompt (ro)
      statewait   blocks until state changes (ro)
      systemprompt rendered system prompt (ro)
      tail        tail helper (x)
      usage       token counts (ro)
      t/          tool scripts (r/w)         ls, cat, edit, chmod
        idx       tool index (ro)            cat
  sk/             skills (r/w)               ls, cat, edit
    idx           skill index (ro)           cat
    <name>.md     skill content (r/w)
  tr/             transcripts (ro)           ls, cat
    <YYYYMMddTHHmmss>-chat.md  saved transcripts
  u/              utility scripts (x)        ls, exec
  x/              system scripts (x)         ls, exec
  tmp/            scratch space (r/w)        ls, cat, edit, rm

Session management

echo "cwd=/path backend=ollama model=qwen3:8b" > ~/mnt/ollie/s/new
mv ~/mnt/ollie/s/<id> ~/mnt/ollie/s/my-name         # rename
rm -r ~/mnt/ollie/s/<id>                             # kill
echo stop > ~/mnt/ollie/s/<id>/ctl                   # interrupt current turn

Switching backend/model/agent

cat ~/mnt/ollie/backends                             # list backends
cat ~/mnt/ollie/s/<id>/models                        # list models for current backend
echo backend=ollama > ~/mnt/ollie/s/<id>/cfg
echo model=qwen3:8b > ~/mnt/ollie/s/<id>/cfg
echo agent=myagent > ~/mnt/ollie/s/<id>/cfg

Writes to cfg are rejected while the agent is running.

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)
OLLIE_TRANSCRIPT_PATH   transcript directory (default: ~/.config/ollie/transcript)

OLLIE_OLLAMA_URL        base URL for ollama (default: http://localhost:11434)
OLLIE_OPENAI_URL        base URL for openai-compatible backends
OLLIE_OPENAI_KEY        API key (openai, openrouter)
OLLIE_ANTHROPIC_KEY     API key (anthropic)
OLLIE_COPILOT_TOKEN     bearer token (copilot)
OLLIE_KIRO_TOKEN        bearer token or sqlite:// path (kiro)

Set defaults in ~/.config/ollie/env (KEY=VALUE, one per line).