ollie-core/README.md

ollie

A Go library for building agentic systems. Provides a sandboxed shell tool, a common LLM backend interface, and a skill system for domain-specific capabilities.

Primitives

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

• 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
• IsRunning — whether a turn is in progress
• AgentName/BackendName/ModelName — active identifiers
• Usage/Cost/CtxSz — token counts, cost, context size
• ListModels — available models from the backend
• CWD/SetCWD — working directory for tool execution
• SetSessionID — rename the session
• SystemPrompt — fully rendered system prompt
• Context — current message history as sent to the backend
• GenerationParams/SetGenerationParams — sampling parameters
• CompactionModel/SetCompactionModel — model override for compaction
• SetEnv — inject session-scoped env var into subprocesses
• WaitChange — block until a field changes (state, usage, ctxsz, cwd)
• ToolCallCount — monotonic tool call counter
• SaveSession — persist session state to disk
• Detach/ListDetached/SignalDetached/GetDetachedOutput — background process management
• Close — release resources

agent.Session — the conversation turn accumulator. Tracks message history, token usage, context compaction, and session persistence. Supports compact (summarize-and-truncate) and PreCompactionSnapshot.

agent.AgentEnv — wires together a backend, tool dispatcher, config, and hooks into the environment passed to NewAgentCore. Built via BuildAgentEnv.

agent.Hooks — lifecycle callbacks (agentSpawn, preTurn, postTurn, preCompact, postCompact, turnError) executed as shell commands with a JSON payload. Run via Hooks.Run.

backend.Backend — the LLM interface: ChatStream, Models, ContextLength, Name, Model/SetModel, DefaultModel. Implementations: Ollama, OpenAI-compatible (including OpenRouter), Anthropic, Copilot, Kiro/CodeWhisperer, Gemini.

tools.Server — interface for a tool provider: ListTools, CallTool, Close. The only built-in implementation is execute.Server. Custom servers implement this interface directly.

tools.Dispatcher — routes tool calls to the correct server by name. Built via NewDispatcher or NewDispatcherFunc (from a map of Decl factories). Supports AddServer, GetServer, ListTools, Dispatch.

Packages

pkg/agent/           — Core interface, agent loop, session management
pkg/backend/         — Backend interface + implementations (Ollama, OpenAI, Anthropic, Copilot, Kiro, Gemini)
pkg/config/          — Config struct and loader
pkg/env/             — Environment variable loading (env file + shell)
pkg/log/             — Structured logging
pkg/paths/           — Config and data directory resolution
pkg/skills/          — Skill file discovery and loading
pkg/tools/           — Server and Dispatcher interfaces; tool definitions
pkg/tools/execute/   — execute.Server: shell

Install

mk

No build step — ollie-core is a library.

Configuration

Config file: ~/.config/ollie/config.json

{
  "hooks": {
    "agentSpawn": [
      "bd prime 2>/dev/null || true"
    ],
    "preTurn": [
      "$OLLIE/x/prime tools-file",
      "$OLLIE/x/prime tools-reasoning",
      "$OLLIE/x/prime tools-memory",
      "$OLLIE/x/prime tools-subagent"
    ],
    "postTurn": ["true"]
  }
}

Hook values accept a string or an array of strings. Commands run in order; each command's stdout is appended to the system prompt context. Exit code 2 blocks the triggering action; any other non-zero exit is a non-blocking warning.

System prompt

The base system prompt is embedded in the ollie binary (system_prompt.md in the 9p submodule) and loaded by Go at session creation via BuildAgentEnv. Tool-specific prompts are injected via preTurn hooks using the prime script ($OLLIE/x/prime <name>), which reads a file from p/ and writes it to stdout with environment variable substitution. The fully assembled result is readable at s/<id>/systemprompt.

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

Controls landrun sandboxing for shell. Created automatically with defaults on first run. See the file header for documentation.

Tools

One built-in tool via execute.Server:

shell — run a bash command in a sandbox. Accepts cmd (string), timeout (default 30s, 0 for no timeout), sandbox (profile name), elevated (bypass sandbox). Use elevated: true to escape the sandbox, or timeout: 0 to run indefinitely (detachable).

Named tool scripts from OLLIE_TOOLS_PATH are promoted to native callable functions via the tool registry — no wrapper needed.

Session lifecycle

NewAgentCore creates /tmp/ollie/{sessionID} when a session starts. Core.Close() removes it. Callers must call Close() when tearing down a session — olliesrv does this in killSession and on server shutdown.

Additional capabilities (file I/O, memory, reasoning, task management, sub-agents, browser automation) are implemented as tool scripts in OLLIE_TOOLS_PATH, promoted to native callable functions via the tool registry. Default tools: file_read, file_write, file_edit, file_glob, file_grep, memory_remember, memory_recall, reasoning_think, browser_screencap, subagent_spawn.

Each tool server exports a Decl function that returns a func() tools.Server factory. execute.Decl(cwd) accepts a working directory used as cmd.Dir for sandboxed commands and for {CWD} expansion in the sandbox config; pass "" to fall back to os.Getwd(). Frontends register servers by passing Decl results to tools.NewDispatcherFunc. Adding a new tool means implementing tools.Server, exporting a Decl function, and registering it — no frontend changes required.

Skills

Skills are domain-specific knowledge files served from the ollie 9P mount (sk/ directory).

# Discover
ls ${OLLIE:-$HOME/mnt/ollie}/sk/
grep -li <keyword> ${OLLIE:-$HOME/mnt/ollie}/sk/*.md

# Load
cat ${OLLIE:-$HOME/mnt/ollie}/sk/<name>.md

Skills are sourced from OLLIE_SKILLS_PATH (default: ~/.config/ollie/skills/). The sk/ directory in the mount exposes them as flat <name>.md files.

License

GPLv3