ollie

Ollie is an AI agent runtime. A small Go core handles the agent loop, tool dispatch, sandboxing, and multi-backend routing; frontends (terminal, acme, Emacs, KDE, browser) and orchestration (shell scripts, multi-agent workflows, cron) are external. The core is deliberately minimal — capabilities come from composing small pieces rather than building a monolithic framework.

Repository layout

Monorepo with Git submodules. Each submodule has its own Go module (except el which is Elisp and kde which is C++/Qt).

Directory	Language	Description
core/	Go	Core library: agent loop, backends, tools, config, sandbox
9p/	Go	9P filesystem server (olliesrv)
dbus/	Go	D-Bus session manager daemon (ollied)
acme/	Go	Plan 9 acme editor frontend
httpgw/	Go	HTTP-to-9P gateway (ollie-httpgw)
webui/	TypeScript	Preact SPA browser frontend
kde/	C++/Qt6	KDE integration: plasmoid, standalone GUI, Kate plugin, KRunner, tray
el/	Elisp	Emacs frontend (ellie.el)
agents/	JSON	Agent config files (loaded at runtime)
prompts/	Markdown	System prompt templates
tools/	Python/Bash	Tool scripts (file_read, lsp_, memory_, etc.)
scripts/	Shell	User-facing CLI scripts: session management, utilities, plumbing
sandbox/	YAML	Landlock sandbox config
doc/	Markdown	Architecture docs, usage guide
contrib/	Mixed	Community scripts
experiments/	Mixed	Trial notes

Features

Sessions

• Create / kill / rename / list — full lifecycle management of concurrent agent sessions
• Prompt submission with FIFO queue — prompts are queued and processed in order; multiple clients can submit without conflicts
• State observation — each session exposes its current state (idle, thinking, calling: <tool>) with a blocking-wait primitive for efficient polling
• Chat streaming — stream model output in real time via file tail or D-Bus signal
• Session persistence — active sessions survive server restarts; state is checkpointed to ~/.local/share/ollie/sessions/
• Plan / scratchpad — per-session markdown checklist that survives context compaction and is visible to peer agents
• Environment inspection — read the effective environment variables for any session

Agent loop

• Streaming tool calls — the core runs a turn loop: prompt the model, parse tool calls, dispatch them (in parallel where safe), feed results back, repeat until done
• Automatic context compaction — long conversations are summarized transparently when approaching the context limit
• System prompt templating — prompts are rendered from markdown templates with variable substitution; inspect the fully rendered prompt at any time

Backends

• Multi-backend routing — Ollama (local), OpenAI-compatible, Anthropic, GitHub Copilot, Kiro; switch backends per-session or let the tier router pick automatically
• Model listing and switching — enumerate available models from any backend; switch models mid-session
• 24-hour model cache — model lists are cached at the backend level to avoid repeated API calls

Tools and sandboxing

• Sandboxed execution — every tool call runs inside a Landlock sandbox with per-profile filesystem access rules
• Extensible tools — tools are executable scripts with header metadata; add one by dropping a file in a directory
• Elevation — commands that need to escape the sandbox can request elevation through a streaming protocol (frame-based, over unix socket)

Agents

• Agent definitions — JSON configs that set personality, tools, backend preferences, and constraints
• List and switch — enumerate available agents and assign one to any session

Multi-agent

• Peer communication — bidirectional links between sessions; peers can submit prompts to each other
• Orchestrator/worker patterns — subagent delegation, parallel fan-out, coordinated through session primitives
• Domain skills — teach the agent your project’s conventions with a markdown file; loaded on demand

Background processes

• Detach — start a long-running command and immediately background it; the agent continues working
• Monitor — list running processes, read their output (64KB ring buffer), check status
• Signal and dismiss — send TERM/KILL to a detached process; remove finished processes from the list

Code completion

• Stateless completion endpoint — write a JSON request (language, code, position), read back completions; works from any editor or script

Frontends

• Terminal — interactive CLI (b, bfg, sh)
• Plan 9 acme — editor integration for acme
• Emacs — ellie.el package
• KDE — plasmoid, standalone GUI, Kate plugin, KRunner, system tray
• Web UI — Preact SPA served by the HTTP gateway

Configuration

• Per-session config — backend, model, agent, generation parameters; all readable and writable at runtime
• Tier routing — worker/expert model tiers per backend for automatic cost/capability optimization

---

9P: everything is a file

The 9P filesystem server (olliesrv) exposes the entire agent runtime as a synthetic filesystem. This is not a convenience wrapper — it is the primary interface, and it provides architectural benefits that no RPC or REST API can match.

Why a filesystem?

Every session is a directory. Every operation is a read or write. There is no client library, no SDK, no protocol buffer — echo, cat, tail, and rm are the API.

# Create a session
echo "name=worker" > /mnt/ollie/s/new

# Submit a prompt
echo "fix the bug in main.go" > /mnt/ollie/s/worker/prompt

# Stream the response
tail -f /mnt/ollie/s/worker/chat

# Check state
cat /mnt/ollie/s/worker/state

# Kill a background process
echo "signal 12345 TERM" > /mnt/ollie/s/worker/ctl

# Get completions
echo '{"language":"go","code":"func he"}' > /mnt/ollie/s/worker/complete
cat /mnt/ollie/s/worker/complete

Network transparency

9P is a network protocol. Mount the agent filesystem from any machine on the network:

9pfuse 'tcp!server:5640' /mnt/ollie

No SSH tunneling, no port forwarding for individual endpoints, no API gateway. One mount and every session, every tool, every config value is accessible as if local.

Container and headless deployment

The 9P server embeds the core library directly — no D-Bus, no display server, no desktop dependencies. It runs anywhere a Go binary runs: containers, cloud VMs, CI runners, embedded systems.

Shell composability

Because operations are file I/O, they compose with the entire Unix toolkit:

# Fan out a prompt to all sessions
for s in /mnt/ollie/s/*/prompt; do echo "run tests" > "$s"; done

# Wait for all agents to finish
for s in /mnt/ollie/s/*/statewait; do cat "$s" > /dev/null; done

# Grep all agent plans
grep -r "TODO" /mnt/ollie/s/*/plan

# Monitor costs
paste /mnt/ollie/s/*/cost

Pipe agents into awk. Filter with grep. Schedule with cron. Orchestrate with a 10-line shell script instead of a framework.

Multiplexing

Multiple clients — terminals, editors, scripts, other agents — can mount the same server simultaneously. Each gets an independent view through 9P’s per-fid state model. No connection pools, no session affinity, no WebSocket juggling.

Plan 9 patterns

The design follows Plan 9 conventions directly:

• /net/dns pattern — the /complete file is stateless per-fid: write a request, read back the result, like a DNS lookup
• ctl files — control operations (stop, kill, rename, compact) are writes to a control file, not method calls
• Blocking reads — statewait blocks until state changes, replacing event subscriptions with a simple cat

Getting started

Clone with submodules:

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

Or after cloning:

git submodule update --init --recursive

Build and install everything from the monorepo root:

mk

Or build specific components:

mk core    # Core library
mk 9p      # 9P filesystem server
mk httpgw  # HTTP gateway
mk webui   # Web UI (requires Node.js + npm)
mk dbus    # D-Bus daemon
mk data    # Install agents/prompts/tools/skills to ~/.config/ollie/
mk scripts # Install CLI scripts

For KDE, build from kde/ with CMake. For Emacs, copy el/ellie.el into your config and (require 'ellie).

See doc/USAGE.md for usage instructions.

Configuration

Environment: ~/.config/ollie/env

OLLIE_BACKEND=openai           # ollama | openai | 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 tool scripts ({tool} steps)
OLLIE_MEMORY_PATH=~/.config/ollie/memory  # directory for memory files (ollie/m)
OLLIE_ELEVATE_SOCKET=${XDG_RUNTIME_DIR}/ollie/elevate.sock  # socket path for x/elevate adapter
OLLIE_COMPLETE_BACKEND=ollama             # backend for u/complete (required)
OLLIE_COMPLETE_MODEL=qwen3:latest         # model for u/complete (required)
OLLIE_ENABLED_BACKENDS=openrouter,kiro  # backends available for routing (comma-separated)

# Per-backend tier models for t/route
OLLIE_TIER_WORKER_openrouter=mistralai/devstral-small
OLLIE_TIER_EXPERT_openrouter=anthropic/claude-sonnet-4-20250514
OLLIE_TIER_WORKER_kiro=claude-haiku-4-20250514
OLLIE_TIER_EXPERT_kiro=claude-sonnet-4-20250514
OLLIE_TIER_WORKER_anthropic=claude-haiku-4-20250514
OLLIE_TIER_EXPERT_anthropic=claude-sonnet-4-20250514
OLLIE_TIER_WORKER_ollama=qwen3:8b
OLLIE_TIER_EXPERT_ollama=qwen3:32b

Shell environment variables take precedence over the env file.

Development

Update all submodules to latest:

git submodule update --remote

Each submodule has its own Go module with independent tests (go test ./...). See individual submodule READMEs for component-specific build and test instructions.

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