5.1 KiB

Raw Blame History

ollie

What happens if agent primitives are exposed as an ordinary filesystem? How much can be subtracted from AI agent implementations without reducing their usefulness? These are some of the motivating questions behind ollie.

The core system provides a public library of AI agent primitives.
The 9p filesystem server (Go) creates a virtual filesystem exposing the important state and behaviors as ordinary files and operations.
A reference TUI implementation proves that it is possible to build a functioning and user-friendly terminal front-end using only the Go standard library.
And, just because I like my Emacs friends, a reference Emacs interface front-end implementation.

Project Structure

core/:
tui/:
9p/:
el/:

Getting Started

Clone with submodules:

git clone --recurse-submodules https://github.com/lneely/ollie.git

Or after cloning:

git submodule update --init --recursive

Building

Build everything from the monorepo root:

mk

Or build specific components:

mk core    # Build core library
mk tui     # Build terminal UI
mk 9p      # Build 9p filesystem server

For Emacs Lisp, copy el/ollie.el into your own Emacs configuration directory, and:

(require 'ollie)

Configuration

Environment: `~/.config/ollie/env`

OLLIE_BACKEND=openai           # ollama | openai | openrouter | anthropic | copilot | kiro (default: ollama)
OLLIE_OLLAMA_URL=              # base URL for Ollama (default: http://localhost:11434)
OLLIE_OPENAI_URL=https://openrouter.ai/api
OLLIE_OPENAI_KEY=sk-or-...
OLLIE_ANTHROPIC_KEY=sk-ant-...
OLLIE_COPILOT_TOKEN=...
OLLIE_KIRO_TOKEN=...           # bearer token or sqlite:// path (auto-detected from Kiro CLI if unset)
OLLIE_MODEL=qwen/qwen3-235b-a22b
OLLIE_TOOLS_PATH=~/.config/ollie/tools    # directory for execute_tool scripts
OLLIE_MEMORY_PATH=~/.config/ollie/memory  # directory for memory files (ollie/m)

Shell environment variables take precedence over the env file.

Development

Update all submodules to latest:

git submodule update --remote

Observed Benefits

Filesystem as interface — if you know how to operate a filesystem, you know how to operate ollie. Any tool that reads and writes files — ed, vim, Python, cat, a shell script — is already a fully capable ollie client. No SDK, no API, no protocol to learn.

Simple front-ends — A TUI reads chat, writes prompt, polls state. There is no protocol to implement.

Crash resiliency — Memory (m/) and plans (pl/) are written to persistent storage outside the session. If a session crashes or is killed mid-task, neither is lost — a fresh session picks up where the previous one left off.

Code execution tool — Anthropic describes code execution as "a foundational primitive for building high-performance agents." ollie takes that literally: execute_code is the base layer, and execute_tool and execute_pipe build directly on top of it. New capabilities are added by dropping a script into t/ and a skill in sk/ — the tools provide the capability, and the skill tells the agent when and how to use them.

Radical transparency — The rendered system prompt for any session is readable at s/{id}/systemprompt — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it live in p/; the agent can read its own instructions but cannot modify them.

Discoverability — ls s/{id}/ shows every control surface. cat t/idx and cat sk/idx list available tools and skills. cat help explains the rest.

Composability — Agents can be composed by piping reply into another session's prompt. Tools can be composed via execute_pipe, chaining execute_code and execute_tool steps the same way Unix pipes chain programs.

Passive memory — Every session's chat history accumulates at s/{id}/chat, searchable with grep. An agent doesn't need to actively decide what to remember. This extends across sessions: an agent can search another session's chat for answers that have already been worked through.

Sub-agents — An agent can spin up new sessions by writing to s/new, prime each one with a prompt, and collect results by reading their reply or having them write back to the parent's prompt or enqueue. Coordination is not yet fully resolved, but the basic fan-out pattern works today.

Credits

Many sources of inspiration:

Plan 9 from Bell Labs — for an interesting system
@9fans — for the Plan 9 port
Suckless — for articulating good software development principles
@simonfxr — for a solid agent baseline to "borrow" from, and other nifty ideas
@aws — for a solid open-source agent implementation

License

GPLv3

5.1 KiB Raw Blame History