# ollie

An AI agent exposed as a 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/<id>/prompt             # send a prompt
cat ~/mnt/ollie/session/<id>/chat                          # read the conversation
tail -f ~/mnt/ollie/session/<id>/chat                      # follow live output
```

## 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
  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 (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)
      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: <tool>
      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
    <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
```

## Request-response files

`complete`, `generate`, `route`, and `tools` work the same way: open r/w, 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>&-
```

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/<id> ~/mnt/ollie/session/my-name         # rename
rm -r ~/mnt/ollie/session/<id>                             # kill
echo stop > ~/mnt/ollie/session/<id>/ctl                   # interrupt current turn
```

## Switching backend/model/agent

```sh
cat ~/mnt/ollie/backends                             # list backends
cat ~/mnt/ollie/session/<id>/models                        # list models for current backend
echo backend=ollama > ~/mnt/ollie/session/<id>/cfg
echo model=qwen3:8b > ~/mnt/ollie/session/<id>/cfg
echo agent=myagent > ~/mnt/ollie/session/<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)

OLLIE_ENABLED_BACKENDS  backends available for routing (comma-separated)
OLLIE_ROUTE_BACKEND     backend for /route classifier (default: ollama)
OLLIE_ROUTE_MODEL       model for /route classifier (default: qwen3:8b)
```

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