# ollie

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

## Quick start

```sh
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
    idx           memory index (ro)          cat
  p/              prompt templates (ro)      ls, cat
  b/              batch jobs (ephemeral)      ls
    idx           job index (ro)             cat: id state cwd agent, one per line
    new           create job (r/w)           cat: KV template; write spec to submit
    <id>/         job directory              rm -r to cancel and remove
      spec        original job spec (ro)
      state       job state (ro)             running | done | failed: <reason>
      statewait   blocking state change (ro)
      result      assistant reply (ro)
      usage       token counts (ro)
      ctxsz       context size (ro)
  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]
    job           batch job (x)              exec s/job [-bg] [-parallel N] [-keep] [prompt...]
    q             foreground query (x)       exec s/q [flags] [prompt...]
    sched         background job (x)         exec s/sched [flags] [prompt...]; prints b/ path
    <id>/         session directory          rm -r to kill; mv to rename
      agent       active agent (r/w)
      backend     active backend (r/w)
      chat        conversation log (r/w; write to save transcript to tr/)
      offset      byte offset of chat after last user prompt; tail -c +$((offset+1)) gives model response (ro)
      ctl         control (w)                stop, kill, clear, compact, rn <name>
      ctxsz       context size (ro)
      ctxszwait   blocks until ctxsz changes (ro)
      cwd         working directory (r/w)
      cwdwait     blocks until cwd changes (ro)
      fifo.in     queue a prompt (w)
      fifo.out    pop queued prompt (ro)
      model       active model (r/w)
      models      available models (ro)
      prompt      submit prompt (w)
      state       agent state (ro)           idle | thinking | calling: <tool>
      statewait   blocks until state changes (ro)
      systemprompt rendered system prompt (ro)
      usage       token counts (ro)
      usagewait   blocks until usage changes (ro)
  sk/             skills (r/w)               ls, cat, edit
    idx           skill index (ro)           cat
    <name>.md     skill content (r/w)
  t/              tool scripts (r/w)         ls, cat, edit, chmod
    idx           tool index (ro)            cat
  tr/             transcripts (ro)           ls, cat
    <YYYYMMddTHHmmss>-chat.md  saved transcripts
```

## Session management

```sh
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

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

Writes to backend, model, and agent 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).