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. All three interfaces are live: the CLI (an interactive TUI in a terminal, a headless agentic one-shot everywhere else), a local web server (
octo serve), and an IM bridge (octo channel, WeChat iLink). On top of the agent loop there are skills, MCP clients, OS-level sandboxing, persistent memory, sub-agents, and a task graph for autonomous multi-step goals.
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
# Headless one-shot (claude -p style): one prompt → full agentic tool loop → exit.
# Built-in tools (shell, read/edit files, search), MCP servers, and skills are
# all on by default, so a single message can actually do work.
octo chat "Add a --json flag to 'octo config show' and run the tests"
# The prompt can also come from a pipe or a file — handy for scripts / CI:
echo "Summarise what changed in the last commit" | octo chat
octo chat --prompt-file ./task.md
# Interactive multi-turn: run octo in a terminal with no message to get the TUI
# (rich tool cards, session auto-saved). Resume a previous session with -c.
octo chat
octo chat --list-sessions
octo chat -c <session-id>
# Streaming on by default; --stream=false buffers and prints only the final
# reply text (clean for capturing into a file).
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 "..."
# 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
# Web server + dashboard (binds localhost by default)
octo serve --addr 127.0.0.1:8080
# IM bridge (WeChat iLink): scan-to-login, then run the daemon
octo channel login
octo channel start
# Autonomous multi-step goal: plan into a subtask DAG and run it
octo goal start "Add a --json flag to octo config show"
octo goal status <id>
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 TUI).--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 TUI.
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 | Headless agentic one-shot (claude -p style) + interactive TUI, 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) |
| MCP client | done | mcp.json stdio + Streamable HTTP servers, tools/resources/prompts, device-flow OAuth |
| Memory | done | Persistent cross-session memory under ~/.octo/memory/, auto extract/consolidate |
| Sub-agents | done | launch_agent fan-out, async + resumable (send_message, agent_status, kill_agent) |
| Task graph | done | octo goal — plan a goal into a subtask DAG, run it via sub-agents, resume after crash |
| Web server | done | octo serve — REST + SSE, embedded dashboard UI (bind localhost) |
| IM bridge | done | octo channel — WeChat iLink adapter (QR login, per-user sessions, slash commands) |
Architecture
Layered, one-directional dependency graph:
cmd/octo/ CLI entry (chat one-shot + TUI, serve, channel, goal, mcp, 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
internal/permission/ allow/deny/ask rule engine gating every tool call
internal/mcp/ MCP client (stdio + HTTP, OAuth)
internal/server/ octo serve — HTTP REST + SSE + embedded dashboard
internal/channel/ IM bridge — adapter interface + WeChat iLink adapter
internal/taskgraph/ octo goal — subtask DAG planner + scheduler
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. |
|
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. |
|
channel
Package channel provides IM platform bridging for octo-agent.
|
Package channel provides IM platform bridging for octo-agent. |
|
channel/adapters/weixin
Package weixin implements the Weixin (微信) iLink adapter.
|
Package weixin implements the Weixin (微信) iLink adapter. |
|
channel/adapters/weixin/ilink
Package ilink implements the WeChat iLink Bot HTTP protocol.
|
Package ilink implements the WeChat iLink Bot HTTP protocol. |
|
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 memory as plain markdown files the agent manages with its own file tools — the Claude Code model.
|
Package memory implements octo's cross-session memory as plain markdown files the agent manages with its own file tools — the Claude Code model. |
|
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. |
|
server
Package server provides the HTTP server for octo's REST API and Web UI.
|
Package server provides the HTTP server for octo's REST API and Web UI. |
|
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. |
|
tools/rgembed
Package rgembed provides a bundled ripgrep (rg) binary for the current platform.
|
Package rgembed provides a bundled ripgrep (rg) binary for the current platform. |
|
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. |
Click to show internal directories.
Click to hide internal directories.