ollie

A Go library for building agentic systems. Provides sandboxed tool execution, a common LLM backend interface, dynamic tool/skill registries, and a session lifecycle framework.

Architecture

graph TD
    agent --> tools
    agent --> backend
    agent --> log
    agent --> paths

    execute --> tools
    execute --> skills
    execute --> detach
    execute --> sandbox
    execute --> paths

    tools --> paths
    elevate -.->|socket| execute

Packages

agent/       Core interface, agent loop, compaction, hooks, session persistence, config loading
backend/     Backend interface + LLM providers (Anthropic, OpenAI, Ollama, Gemini, Copilot, CodeWhisperer)
tools/       Server/Dispatcher interfaces, tool registry, discovery, schema parsing
execute/     Sandboxed shell execution, promoted tool dispatch, skill dispatch, remote SSH execution
detach/      Background process management (ring buffer, signal)
skills/      Skill metadata parsing and per-session registry
elevate/     Elevation broker (privilege escalation daemon, policy management)
sandbox/     Landrun sandbox configuration and command wrapping
env/         Session environment helpers
log/         Structured logger
paths/       XDG path resolution

Primitives

agent.Core — the central interface for a running agent session:

• Submit — send a prompt, stream events via the bus
• Interrupt — cancel the current turn
• Inject — append a user interruption to the next tool result
• Queue/PopQueue — buffered prompt FIFO
• Bus — session event bus (pubsub)
• State — current state: idle, thinking, or calling: <tool>
• Reply — assistant text from the last completed turn
• WaitChange — block until a field changes (state, usage, ctxsz, cwd)
• Detach/ListDetached/SignalDetached/GetDetachedOutput — background process management

backend.Backend — the LLM interface: ChatStream, Models, ContextLength, Name, Model/SetModel, DefaultModel.

tools.Server — interface for a tool provider: ListTools, CallTool. The primary implementation is execute.Server (local) with execute.RemoteServer for SSH-transparent execution.

tools.Dispatcher — routes tool calls to the correct server by name. Built via NewDispatcher or NewDispatcherFunc.

tools.Registry — per-session dynamic tool loading. Discovers tool scripts from OLLIE_TOOLS_PATH, parses their schemas and metadata, and promotes them to native callable functions on demand.

Install

No build step — ollie-core is a library.

Configuration

Agent config: ~/.config/ollie/agents/<name>.json

{
  "prompt": "agent-coding.md",
  "backend": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "hooks": {
    "preTurn": ["$OLLIE/x/prime tools-file"]
  },
  "maxSteps": 50,
  "reasoning": 10000
}

Hook values accept a string or array of strings. Commands run in order; stdout is appended to context. Exit code 2 blocks the action; other non-zero is a warning.

Sandbox config: ~/.config/ollie/sandbox/<name>.yaml

Controls landrun sandboxing for shell. See file header for documentation.

Tools

One built-in tool via execute.Server:

shell — run a bash command in a sandbox. Accepts cmd, timeout (default 30s, 0 for unlimited), sandbox (profile name), elevated (bypass sandbox via elevation broker).

Named tool scripts from OLLIE_TOOLS_PATH are promoted to native callable functions via tools.Registry. Each script declares its schema and metadata in header comments (ollie:prompt, args_json:, ollie:tier, ollie:parallel read).

Skills

Skills are domain-specific knowledge modules in OLLIE_SKILLS_PATH (default: ~/.config/ollie/skills/). Each is a directory containing a SKILL.md with YAML front-matter (name, description). Loaded into session context on demand via skill_load.

Session lifecycle

The 9P server (olliesrv) is the session manager. It instantiates the execute server, elevation broker, and tool/skill registries at daemon level. Sessions are created, queried, and controlled via the 9P filesystem — all agent interaction uses the ollie-9p client internally.

NewAgentCore handles per-session state: message history, tool call routing, compaction, and hooks. Core.Close() tears down resources when a session is killed.

License

GPLv3