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
    session --> agent
    session --> backend
    session --> toolsrv
    session --> paths

    agent --> backend
    agent --> toolsrv
    agent --> paths

    toolsrv --> detach
    toolsrv --> sandbox
    toolsrv --> skills
    toolsrv --> paths

    tools --> toolsrv
    sandbox --> paths
    env --> paths

    elevate -.->|unix socket| toolsrv

Packages

session/     Session lifecycle: creation, persistence, environment, event bus
agent/       Agent runtime: turn loop, compaction, hooks, commands, history, cost, FIFO, prompts
backend/     Backend interface + LLM providers (Anthropic, OpenAI, Ollama, Copilot, Kiro)
toolsrv/     Tool server: registry, discovery, schema, shell execution, remote SSH, streaming
tools/       Built-in tool definitions (shell, skill, tool promotion)
detach/      Background process management (ring buffer, signal)
skills/      Skill metadata parsing and per-session registry
elevate/     Elevation broker (privilege escalation daemon, policy)
sandbox/     Landrun sandbox configuration and command wrapping
env/         Session environment helpers
log/         Structured logger
paths/       XDG path resolution

Core concepts

session.Session — the public interface. A session is the runtime environment that hosts an agent. It provides identity, working directory, event bus, environment, and lifecycle management.

session.Agent — the reasoning entity within a session. Owns the conversation history, LLM backend, tools, hooks, and system prompt. Swappable via /agent command.

session.harness (unexported) — implements Session. Wires the agent to the session environment and drives turn execution.

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

tools.Server — interface for a tool provider: ListTools, CallTool. Implementations: execute.Server (local) and execute.RemoteServer (SSH).

tools.Registry — per-session dynamic tool loading. Discovers scripts from OLLIE_TOOLS_PATH, parses schemas, promotes 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.

session.New() creates a session with its agent. The session drives turn execution, manages compaction, and handles lifecycle events. Close() tears down resources when a session is killed.

License

GPLv3