README
¶
octo-agent
A functionality-first AI agent, distributed as a single Go binary. Speaks two native API protocols — Anthropic Messages and OpenAI Chat Completions — and works against any compatible third party (DeepSeek, Kimi, Bailian, OpenRouter, vLLM, …). Aims for three equal interfaces: CLI, Web, and IM.
Status
Pre-1.0. CLI is functional today; Web UI and IM bridges land in later milestones — see
dev-docs/go-rewrite-roadmap.md.
Install
Prebuilt binary (no Go toolchain needed). Grab the archive for your OS/arch
from the latest release,
unpack it, and put octo on your PATH:
# macOS (Apple Silicon) example — swap the asset name for your platform
curl -sSL https://github.com/Leihb/octo-agent/releases/latest/download/octo_<version>_darwin_arm64.tar.gz | tar xz
sudo mv octo /usr/local/bin/
octo version
Archives ship for linux / darwin / windows on amd64 + arm64; checksums.txt
in each release verifies the download.
From Go:
go install github.com/Leihb/octo-agent/cmd/octo@latest
From source:
git clone https://github.com/Leihb/octo-agent.git
cd octo-agent
make build # produces ./octo
Quick start
export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY=...
# One-time setup: save your default provider/model (skip the export above next time)
octo config
# Single-shot
octo chat "Explain ring buffers in 100 words"
# Interactive REPL (multi-turn, session auto-saved)
octo chat
# Resume a previous session
octo chat --list-sessions
octo chat -c <session-id>
# Streaming on by default; turn off with --stream=false
octo chat --stream=false "..."
# OpenAI / DeepSeek / Bailian (OpenAI-compatible)
octo chat --provider openai --model gpt-4o-mini "..."
# Anthropic-compatible third parties (DeepSeek, Kimi, etc.)
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic \
octo chat --model deepseek-chat "..."
# The interactive REPL is a full agent out of the box — built-in tools
# (shell, read/edit files, search), MCP servers, and skills are all on by
# default. Risky actions still prompt for approval (interactive permission).
octo chat
# Plain chat with no tools / MCP / skills
octo chat --no-tools
# Sandbox the tool commands: confine the terminal tool to the project dir + tmp, no network
octo chat --sandbox
# Generate a .octorules guide for this repo
octo init
# List discovered skills
octo chat --list-skills
Configuration
Octo composes its system prompt from several optional layers (later overrides earlier):
~/.octo/soul.md— agent identity & behavior, an openclaw/hermes-style persona.~/.octo/user.md— who you are; a profile injected into every session.~/.octo/octorules.md— your global, cross-project rules and preferences..octorules— per-repo conventions, committed with the project. Generate one withocto init(or/initin the REPL).--system "..."— a one-off override for a single run.
The identity and rule files support @include path/to/fragment.md to pull in shared content.
Defaults (octo config)
octo config saves your default provider, model, and (optionally) base URL to ~/.octo/config.json, so a bare octo chat works without re-typing --provider/--model every time:
octo config # interactive wizard
octo config show # print the effective settings + where each comes from
octo config path # print the file location
Precedence is CLI flag > env var > ~/.octo/config.json > built-in default. API keys are read from ANTHROPIC_API_KEY / OPENAI_API_KEY first; the wizard can store one in the file (mode 0600), but the env var is recommended.
Skills
Skills are reusable instruction sets in Claude Code's SKILL.md format, discovered from:
~/.octo/skills/<name>/SKILL.md— user-level, across all projects..octo/skills/<name>/SKILL.md— project-level (takes precedence over user-level).
The format is identical to Claude Code's, so you can symlink ~/.claude/skills to ~/.octo/skills and reuse what you already have. Each SKILL.md is YAML frontmatter plus a markdown body:
---
name: review
description: Review the current diff for correctness and style
---
Walk the diff hunk by hunk and flag correctness bugs first, then style.
At session start Octo lists each skill's name and description in the system prompt; the model loads a skill's full instructions on demand (via the skill tool) when a task matches. You can also trigger one explicitly — octo chat --list-skills to see what's discovered, then /skills to list and /<name> (e.g. /review) to run one in the REPL.
Sandboxing
--sandbox confines the terminal tool to the project directory plus temp, with no network, enforced by the OS (macOS Seatbelt, Linux Landlock + seccomp). It's off by default and fails closed when the OS mechanism is unavailable.
octo chat --sandbox # confine, deny network
octo chat --sandbox --sandbox-allow-net # allow network
octo chat --sandbox --sandbox-write ./build # extra writable dir (repeatable)
octo chat --sandbox --sandbox-read /opt/data # extra readable dir (repeatable)
What's implemented
| Area | Status | Description |
|---|---|---|
| Core CLI | done | Single-turn + interactive REPL, streaming, session persistence (~/.octo/sessions/), /cost /save /sessions |
| Providers | done | Anthropic Messages + OpenAI Chat Completions, plus any compatible third party |
| Tools | done | terminal (+ background), file read/write/edit, glob, grep, web fetch/search |
| Agentic loop | done | Multi-step tool calling, permission gating, history compaction, graceful Ctrl-C |
| Memory & config | done | ~/.octo/octorules.md, .octorules, octo init, @include |
| Skills | done | Claude Code-compatible SKILL.md loader (--list-skills, /skills, /<name>) |
| Sandbox | done | OS-enforced --sandbox (macOS / Linux) |
| Web UI / IM bridges | planned | See dev-docs/go-rewrite-roadmap.md |
Architecture
Layered, one-directional dependency graph:
cmd/octo/ CLI entry (chat, REPL, sessions, slash commands)
↓
internal/agent/ History, sessions, content blocks, Sender interface,
Agent.Turn / TurnStream / Run (tool-calling loop)
↓
internal/provider/ Provider interface + concrete implementations
├─ anthropic/ x-api-key, system top-level, content[].text
└─ openai/ Bearer auth, system in messages[0]
↓
internal/tools/ ToolExecutor implementations — terminal (+ background),
file read/write/edit, glob, grep, web fetch/search, skill
internal/skills/ SKILL.md discovery + system-prompt manifest
Each provider implements both buffered (Send) and streaming (SendStream) variants. The agent layer mirrors with Sender / StreamingSender / ToolSender / ToolStreamingSender — interfaces are added incrementally so non-streaming providers still work.
Development
make build # ./octo
make test # go test -race ./...
make vet # go vet ./...
make fmt-check # gofmt -l . must be empty
See CLAUDE.md for the project guide intended for AI coding agents working in this repo, and CONTRIBUTING.md for the human PR workflow.
License
MIT. See LICENSE.txt.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mswe-eval
command
Command mswe-eval runs the octo side of the Multi-SWE-bench evaluation: it drives octo over a slice of Go instances to produce patches, then hands them to the official Python+Docker judge.
|
Command mswe-eval runs the octo side of the Multi-SWE-bench evaluation: it drives octo over a slice of Go instances to produce patches, then hands them to the official Python+Docker judge. |
|
octo
command
Command octo is the Go implementation of the Octo AI agent.
|
Command octo is the Go implementation of the Octo AI agent. |
|
tui-preview
command
tui-preview renders a sample of every TUI card to stdout so the maintainer can eyeball them on a real terminal.
|
tui-preview renders a sample of every TUI card to stdout so the maintainer can eyeball them on a real terminal. |
|
internal
|
|
|
agent
Package agent implements the Octo agent core: messages, history, and the run loop that ties an LLM provider to user input.
|
Package agent implements the Octo agent core: messages, history, and the run loop that ties an LLM provider to user input. |
|
config
Package config holds the user's persisted CLI defaults at ~/.octo/config.json — the provider/model/base-URL a fresh `octo chat` should use without re-typing flags or re-exporting env vars every session.
|
Package config holds the user's persisted CLI defaults at ~/.octo/config.json — the provider/model/base-URL a fresh `octo chat` should use without re-typing flags or re-exporting env vars every session. |
|
hooks
Package hooks implements C9 Phase 3 turn-boundary hooks.
|
Package hooks implements C9 Phase 3 turn-boundary hooks. |
|
mcp
Package mcp implements a Model Context Protocol client for octo.
|
Package mcp implements a Model Context Protocol client for octo. |
|
memory
Package memory implements octo's cross-session auto-memory (C9): typed, one-file-per-fact storage under ~/.octo/memory, a MEMORY.md index, and an injection renderer.
|
Package memory implements octo's cross-session auto-memory (C9): typed, one-file-per-fact storage under ~/.octo/memory, a MEMORY.md index, and an injection renderer. |
|
mswe
Package mswe holds the pure, testable pieces of the Multi-SWE-bench eval harness: dataset parsing, prediction writing, fix-patch scoping, harness config generation, and report parsing.
|
Package mswe holds the pure, testable pieces of the Multi-SWE-bench eval harness: dataset parsing, prediction writing, fix-patch scoping, harness config generation, and report parsing. |
|
permission
Package permission gates tool calls through a rule-driven decision engine.
|
Package permission gates tool calls through a rule-driven decision engine. |
|
prompt
Package prompt assembles the agent's system prompt from layered sources.
|
Package prompt assembles the agent's system prompt from layered sources. |
|
provider
Package provider defines the contract every LLM backend implements.
|
Package provider defines the contract every LLM backend implements. |
|
provider/anthropic
Package anthropic implements the provider.Provider interface against Anthropic's native Messages API (POST /v1/messages).
|
Package anthropic implements the provider.Provider interface against Anthropic's native Messages API (POST /v1/messages). |
|
provider/openai
Package openai implements provider.Provider against OpenAI's Chat Completions API (POST /v1/chat/completions).
|
Package openai implements provider.Provider against OpenAI's Chat Completions API (POST /v1/chat/completions). |
|
provider/retry
Package retry adds bounded exponential-backoff retries to provider HTTP calls for transient failures — request timeouts, rate limits (429), the 5xx family, Anthropic's 529 "overloaded", and transient network errors — while honoring a server-supplied Retry-After header.
|
Package retry adds bounded exponential-backoff retries to provider HTTP calls for transient failures — request timeouts, rate limits (429), the 5xx family, Anthropic's 529 "overloaded", and transient network errors — while honoring a server-supplied Retry-After header. |
|
sandbox
Package sandbox confines an arbitrary shell command to an OS-enforced filesystem and network boundary — defense-in-depth beneath the permission engine (internal/permission), which only gates command strings.
|
Package sandbox confines an arbitrary shell command to an OS-enforced filesystem and network boundary — defense-in-depth beneath the permission engine (internal/permission), which only gates command strings. |
|
skills
Package skills discovers Claude Code-compatible skills from disk and exposes them to the agent in two layers: a one-line manifest injected into the session-start system prompt (see RenderManifest), and full SKILL.md bodies loaded on demand through the `skill` tool.
|
Package skills discovers Claude Code-compatible skills from disk and exposes them to the agent in two layers: a one-line manifest injected into the session-start system prompt (see RenderManifest), and full SKILL.md bodies loaded on demand through the `skill` tool. |
|
taskgraph
Package taskgraph implements octo's autonomous task orchestration data layer (M11).
|
Package taskgraph implements octo's autonomous task orchestration data layer (M11). |
|
tasks
Package tasks implements a session-scoped task tracker.
|
Package tasks implements a session-scoped task tracker. |
|
tools
Package tools provides built-in tool implementations for the octo agentic loop.
|
Package tools provides built-in tool implementations for the octo agentic loop. |
|
tui
Package tui renders agent tool events as visual cards for the terminal REPL.
|
Package tui renders agent tool events as visual cards for the terminal REPL. |
|
version
Package version holds the build-time version metadata for the octo binary.
|
Package version holds the build-time version metadata for the octo binary. |