# ollie

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" | 9p write session/new         # create a session
9p ls session/                                 # find the session ID
echo "hello" | 9p write session/<id>/agent/0/prompt  # send a prompt
9p read session/<id>/agent/0/chat              # read the conversation
```

## Filesystem

```
ollie/
  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
    <id>/
      plan        plan scratchpad (r/w)         9p read plan; echo text | 9p write plan
      env         session environment (ro)      9p read env
      agent/
        <aid>/
          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
          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
          plan        plan scratchpad (r/w)     9p read plan; echo text | 9p write plan
          prompt      submit prompt (w)         echo text | 9p write prompt
          prompt.prev previous prompt (ro)      9p read prompt.prev
          react       send reaction (w)         echo emoji | 9p write react
          reactions   reaction history (ro)     9p read reactions
          state       agent state (ro)          9p read state
          statewait   blocks until change (ro)  9p read statewait
          systemprompt rendered system prompt (ro) 9p read systemprompt
          tail        tail helper (x)           9p exec tail
          tools       tool registry (r/w)       echo name | 9p write tools; 9p read tools
          toolsrv.loaded loaded tools (ro)      9p read toolsrv.loaded
          toolsrv.rev  registry revision (ro)   9p read toolsrv.rev
          usage       token counts (ro)         9p read usage
          proc/       detached processes (dir)  9p ls proc/
  tools           tool prompt lookup (r/w)      echo name | 9p rdwr tools
  elevate/        elevation broker (dir)
    policy        elevation policy (r/w)
    pending       pending requests (r/w)
```

## Request-response files

`complete`, `generate`, `route`, and `tools` work the same way: write a query, read the result.

```sh
echo 'file_edit' | 9p rdwr tools
echo 'implement login' | 9p rdwr route
```

## Session management

```sh
echo "cwd=/path backend=ollama model=qwen3:8b" | 9p write session/new
9p rm session/<id>                                # kill
echo stop | 9p write session/<id>/agent/0/ctl     # interrupt
```

## Switching backend/model/agent

```sh
9p read backends                                  # list backends
9p read session/<id>/agent/0/models               # list models
echo backend=ollama | 9p write session/<id>/agent/0/cfg
echo model=qwen3:8b | 9p write session/<id>/agent/0/cfg
echo agent=myagent | 9p write session/<id>/agent/0/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_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_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).