octo-agent

octo isn't another agent framework you have to "raise." Projects like OpenClaw or Hermes often need environment tuning, rule writing, and skill configuration before the agent runs smoothly. octo sits closer to Codex or WorkBuddy: download and use, user-friendly, while keeping model choice, data ownership, and the runtime firmly in your hands.

curl -fsSL https://octo-agent.dev/install.sh | sh     # single binary — no Node / Ruby / Python
octo "Add a --json flag to 'octo config show' and run the tests"   # one prompt → full agentic loop

📱 On your phone: download the Android app (built with every release), then scan the QR in Settings → Mobile to connect — setup guide.

octo is built around that positioning:

• Works out of the box: shell, file read/write/edit, search, MCP servers, skills, and sub-agents are all on by default — one message after install is enough for it to actually do work.
• Model choice stays yours: any OpenAI / Anthropic protocol-compatible endpoint is supported natively; no vendor lock-in.
• Data stays on your machine: self-hosted, zero telemetry — no analytics, no crash reporting, no usage pings, no CDN. Exactly one request is made without you asking: a version check against GitHub, carrying no data. Set update_check: false and octo makes none at all — what leaves the machine is then only the model API calls you configured and the tool calls you asked for.
• Everywhere you are: the same binary serves eight entry points — TUI, CLI, web, desktop, IM, editor extensions, and mobile.
• Safe defaults: catastrophic commands are hard-coded denies, and deletes and overwrites are backed up to a recycle bin first — the agent won't edit itself dead and won't go rogue on your data.

If you already have reliable access to a Codex or Claude subscription, keep using it — they remain the best agent harnesses on the planet. Otherwise, octo is worth a serious look.

• A single ~40 MB Go binary: one command to download, copy to any server, and run. No Node / Python / Ruby dependency tree; no npm mirror, node-gyp build failure, or version conflict headaches.
• No cache degradation: prompt caching is tuned per provider; measured hit rates for Kimi, DeepSeek, and Qwen are all 99%+, keeping your token bill predictable.
• Eight interfaces: TUI, CLI, Web UI, desktop app, IM bridge, VS Code, Obsidian, and mobile — few other agent projects cover this many entry points at once.
• Zero telemetry: no IP, device model, model choice, or usage behavior is collected — no telemetry hooks at all. The Web UI ships every asset it needs — icons are bundled, text uses system fonts — so opening it touches no CDN. The only thing octo asks the network about itself is whether a newer release exists, and that is one config switch away from silent.
• Desktop installer around 100 MB: compare that to Codex desktop and WorkBuddy, which often weigh in around 1 GB. A thin agent harness shouldn't need that much space.
• Stable and safe: self-protection, graceful restarts, and a recycle-bin safety net (see Core Features).

Any one of these points might be covered by some other product. But only octo combines out-of-the-box usability, native multi-model support, eight interfaces, a single binary, zero telemetry, a small footprint, high stability, and strong safety.

octo (single binary)
  -> TUI                  interactive terminal session
  -> CLI                  octo "prompt" or piped stdin: one headless agentic turn, then exit — script it from cron, CI, or your own programs
  -> Web UI               octo serve local dashboard
  -> Desktop app          native window + system tray on macOS / Windows / Linux
  -> IM bridge            WeChat iLink, Feishu, DingTalk, WeCom, Discord, Telegram
  -> VS Code extension    open-octo/octo-vscode
  -> Obsidian plugin      open-octo/octo-obsidian
  -> Mobile               iOS + Android developer preview

Stable (1.0) already covers TUI, CLI, Web UI, Desktop, IM bridge, and the VS Code / Obsidian extensions. The eighth — a mobile app (iOS + Android) — is implemented and in developer preview: connecting straight to your own octo serve over your LAN, Tailscale or any tunnel. Android: download the APK from each release; iOS builds from source (see mobile/). App-store builds are next.

Built-in tools (shell, file read/write/edit, search), MCP servers, skills, and sub-agents are on by default. No environment tuning, rule writing, or skill configuration first — one message after install is enough for it to actually do work.

DeepSeek, Kimi, Qwen, Anthropic, OpenAI, or any OpenAI / Anthropic-compatible endpoint — octo supports them natively. Prompt caching is tuned per provider, with hit rates of 99%+. Unlike setups that front Claude Code with a third-party model and see cache hit rates collapse from misconfiguration, octo keeps your token bill predictable.

• The terminal tool refuses any kill / pkill / killall aimed at octo's own process, including detours like kill $(pgrep octo).
• restart_server is hard-wired to ask permission first — a browser modal on the web, an explicit reply on IM. Even after approval, the restart is graceful: the current turn drains so your reply reaches you before the supervisor respawns the server and clients reconnect.
• Every delete is validated. Catastrophic commands like rm -rf / and rm -rf ~ are hard-coded denies that custom permission rules cannot override. Ordinary file deletes and write_file / edit_file overwrites are first backed up to a recycle bin (default 14 days / 10 GiB), so nothing is ever truly gone.
• On top of that, opt into OS-enforced sandboxing (macOS Seatbelt / Linux Landlock) when you want it.

The SKILL.md format is compatible with Claude Code — symlink ~/.claude/skills and reuse what you have.

stdio + HTTP transports, OAuth, and Tool Search for large tool sets.

Cross-session memory, parallel sub-agents, and multi-agent workflow orchestration.

Go-native CDP record / replay / self-heal.

Hook octo up to your chat apps and put it to work from WeChat, Feishu, or Telegram.

• Linux / macOS — curl -fsSL https://octo-agent.dev/install.sh | sh
• Windows — irm https://octo-agent.dev/install.ps1 | iex
• Restricted networks — if github.com is unreachable, use the download mirror (installs and octo upgrade also fall back to it automatically): curl -fsSL https://dl.octo-agent.dev/install.sh | sh (Windows: irm https://dl.octo-agent.dev/install.ps1 | iex)
• Desktop app — grab the installer from the latest release: octo-setup.pkg (macOS), octo-setup.exe (Windows), Octo-x86_64.AppImage (Linux)
• Go — go install github.com/open-octo/octo-agent/cmd/octo@latest

Upgrade any time with octo upgrade. Platform details — Gatekeeper / SmartScreen warnings, uninstall, building from source — are in the install guide. The installers aren't code-signed yet; the full policy and how to verify releases by hash are in SECURITY.md.

octo serve -d              # start the local server (Web UI + IM bridge)

Open http://127.0.0.1:8088 and the setup panel walks you through it: pick a language, connect a model, then a short chat that learns your name, the assistant's personality, and how you want it to behave. Loopback needs no access key. The desktop app is the same server with a native window — run it instead and skip straight to the browser step.

Prefer the terminal? Same agent, no extra setup once a provider is connected:

octo "explain this repo"   # headless one-shot: prompt → agentic tool loop → exit
octo                       # interactive TUI in a terminal; octo -c resumes a session
octo config                # provider setup without touching the browser

Next steps: quickstart · choose a provider · CLI reference.

1. Install with one command: curl -fsSL https://octo-agent.dev/install.sh | sh.
2. Start the server — octo serve -d — or launch the desktop app, which is the same server.
3. Open http://127.0.0.1:8088 and follow the setup: language, model, then the onboarding chat that writes who the assistant is and who you are.
4. Give it a real task from the composer — one that needs shell, files or the web, not just an answer.
5. Run octo "explain this repo" for a headless one-shot, or octo for the terminal TUI — same agent, same config.
6. Configure an IM channel and keep the conversation going from WeChat / Feishu / Telegram.
7. Add skills, MCP servers, and sub-agents as you need them.

┌────────────────────────────────┐
│        Eight interfaces        │
│    TUI · CLI · Web UI · IM     │
│  Desktop · VS Code · Obsidian  │
│             Mobile             │
└───────────────┬────────────────┘
                │
┌───────────────▼────────────────┐
│         App bootstrap          │
│ provider wiring · permission   │
│ gate · sub-agent spawner       │
└───────────────┬────────────────┘
                │
┌───────────────▼────────────────┐
│           Agent core           │
│ tool loop · history · session  │
│ persistence                    │
└───────────────┬────────────────┘
                │
┌───────────────▼────────────────┐
│        Provider adapters       │
│ Anthropic / OpenAI protocols   │
│ and compatible endpoints       │
└───────────────┬────────────────┘
                │
┌───────────────▼────────────────┐
│             Tools              │
│ shell · files · search · MCP · │
│ skills · browser automation    │
└────────────────────────────────┘

For the layered design, provider protocols, and how to extend it, see the architecture docs.

The full documentation lives at octo-agent.dev/docs:

• Skills — Claude Code-compatible SKILL.md; symlink ~/.claude/skills and reuse what you have
• Sandboxing & recycle bin — OS-enforced confinement (Seatbelt / Landlock), plus a file-level trash that backs up agent deletes and overwrites
• MCP servers — stdio + HTTP, OAuth, and Tool Search for large tool sets
• Memory · Sub-agents · Workflows — persistence and multi-agent orchestration
• Browser automation — CDP record / replay / self-heal
• IM channels — hook octo up to your chat apps
• Configuration · Permissions · Tools
• Architecture — the layered design, provider protocols, and how to extend it

• Bugs / feature requests — GitHub Issues
• WeChat group (Chinese-speaking users) — scan the QR code below, add the personal account, and mention octo to be invited into the group:

make build         # ./octo
make test          # go test -race ./...

Project conventions live in CLAUDE.md and .octorules; the PR workflow in CONTRIBUTING.md.

octo has shipped 1.0 stable — TUI, CLI, Web UI, desktop, IM bridge, and editor extensions are all safe to rely on; mobile is in developer preview. What you can build on is declared in COMPATIBILITY.md; the security boundary in SECURITY.md.

octo stands on the shoulders of two projects and doesn't pretend otherwise: Claude Code, whose agent loop, tool set, SKILL.md format, and harness behavior shaped octo's internal design; and OpenClacky, which inspired much of the UI and interaction design. Any bugs or bad decisions are octo's own.

Thanks to everyone who has contributed to octo:

The full record lives in the contributors graph.

MIT. See LICENSE.txt.