Ollie 🐙

Ollie is an AI agent runtime built around a 9P virtual filesystem. The runtime service, olliesrv, exposes sessions, agents, prompts, state, history, tools, and control operations as files. Frontends remain thin clients of that interface.

flowchart TB
    B["olliesrv<br/>9P namespace · session lifecycle · agent runtime<br/>prompt + history · backend dispatch"]

    S1["Session A (toolsrv)<br/>host + cwd"]
    S2["Session B (toolsrv)<br/>host + cwd"]
    S3["Session C (toolsrv)<br/>host + cwd"]
    SX["(...)"]

    B --- S1
    B --- S2
    B --- S3
    B --- SX

    A1["Agent 1"]
    A2["Agent 2"]
    A3["Agent 3"]
    A4["Agent 4"]
    A5["Agent 5"]
    A6["Agent 6"]
    AN["Agent N"]
    AX["(...)"]

    S1 --- A1
    S1 --- A2
    S2 --- A3
    S2 --- A4
    S3 --- A5
    S3 --- A6
    SX --- AN
    SX --- AX

    classDef brain fill:#d66b3d,stroke:#642b1c,color:#fff,stroke-width:4px;
    classDef session fill:#e7c65c,stroke:#67551b,color:#211b08;
    classDef agent fill:#c7d4eb,stroke:#354a70,color:#172033;

    class B brain;
    class S1,S2,S3,SX session;
    class A1,A2,A3,A4,A5,A6,AN,AX agent;

Runtime model

• olliesrv owns the in-memory 9P tree and session collection.
• Each session owns one or more agents. Agents maintain configuration, state, prompts, chat history, rendered context, usage, and cost.
• The agent loop sends context to the configured provider, dispatches tool calls, updates history, and repeats until completion or cancellation.
• Child agents are ordinary agents created through the session namespace and communicate through prompt/result files.

The 9P namespace is the API:

session/
├── new                 create a session by writing key=value arguments
├── idx                 tab-separated session index
└── {session}/
    ├── goal            session goal text (triggers workflow on write)
    ├── goalstatus      goal status (running/complete/blocked)
    ├── goalwait        blocks until goal status changes
    ├── env             session environment
    └── agent/
        ├── new         create agent by writing key=value
        ├── idx         tab-separated agent index
        └── {agent}/
            ├── plan        persistent Markdown checklist
            ├── cfg         configuration
            ├── ctl         control commands
            ├── state       current state
            ├── statewait   block until state changes
            ├── prompt      submit a prompt
            ├── chat        conversation history
            ├── context     rendered model context
            ├── systemprompt rendered system prompt
            ├── tools       tool discovery and loading
            ├── usage       token statistics
            ├── cost        cost estimate
            └── proc/       detached process output

Providers, tools, and security

Provider backends are the model-facing boundary; the agent loop is independent of vendor APIs. Tools are external executable programs served by the separate toolsrv 9P process. Their metadata is discovered and loaded lazily, so the model sees only the capabilities needed for a task.

Tool execution uses the configured Landlock/landrun sandbox. Operations requiring an approved escape use the bypass namespace and broker, which applies policy and approval controls rather than providing an unrestricted escape.

Persistent memory is provided by OptMem through memory_recall and memory_remember; Ollie does not maintain a second memory-file format. History management renders context, tracks usage and cost, caps oversized tool output, and compacts older material when necessary.

Frontends

Shell scripts, Acme, KDE components, and other clients create sessions, write prompts, and read files such as chat, statewait, context, and feed. They do not embed provider, tool, or agent-loop logic.

See doc/architecture-ide.md for integrating Ollie with an editor or IDE.

See doc/architecture.md for component boundaries and doc/evolution.md for the design history. See doc/usage.md for setup.

Build

make

The top-level Makefile builds the Go services and tools, then delegates KDE/Qt compatibility to kde/CMakeLists.txt. CMake detects KF6 first and falls back to KF5; use make kde-kf5 to force the KF5/Qt5 build.

Why an Octopus?

• Octopuses are intelligent
• Ollie has tentacles
• Ollie starts with "o"
• Ollie-ollie-octopus!