# ollie

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

Works well with [anvillm](https://github.com/lneely/anvillm), which provides a skill system, tool scripts, and multi-agent infrastructure.

The reference frontend is [ollie-tui](https://github.com/lneely/ollie-tui), a terminal UI built on top of this library.

## Packages

```
pkg/agent/           — Core interface, agent loop, session management
pkg/backend/         — Backend interface + implementations (Ollama, OpenAI, Anthropic, Copilot, Kiro)
pkg/config/          — Config struct and loader
pkg/mcp/             — MCP client
pkg/tools/           — Server and Dispatcher interfaces; tool definitions
pkg/tools/execute/   — execute.Server: execute_code, execute_tool, execute_pipe
pkg/tools/reasoning/ — reasoning.Server: reasoning_think, reasoning_plan
```

## Install

```
mk
```

No build step — ollie-core is a library.

## Configuration

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

```json
{
  "mcpServers": {
    "my-server": {
      "command": "my-mcp-server",
      "args": [],
      "env": {
        "API_TOKEN": "${API_TOKEN}"
      }
    }
  },
  "hooks": {
    "agentSpawn": "notify-send ollie started",
    "userPromptSubmit": "",
    "stop": ""
  }
}
```

MCP server `env` values support `${VAR}` expansion from the parent environment.

### Sandbox config: `~/.config/ollie/sandbox.yaml`

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

## Tools

Five built-in tools across two servers:

- `execute_code` — run inline shell code in a sandbox
- `execute_tool` — run a named tool script from `OLLIE_TOOLS_PATH` (default: `~/.config/ollie/tools`)
- `execute_pipe` — chain steps as a pipeline
- `reasoning_think` — externalize intermediate reasoning
- `reasoning_plan` — decompose a goal into ordered steps; persists to task backend if available, otherwise queued via fallback backend or in-context only

## 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.

File operations go through `execute_code` using standard shell tools (`cat`, `grep`, `sed`, `ed`, `ssam` if plan9port is available, etc.).

MCP server tools are discovered at startup and available alongside the built-ins.

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).

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

# Load
cat ${OLLIE_9MOUNT:-$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.

## Integrations

**[9beads-mcp](https://github.com/lneely/9beads-mcp)** provides task persistence using **[9beads](https://github.com/lneely/9beads)** — enabling the agent to track, list, and manage tasks across sessions.

## License

GPLv3