octomind

Website · Docs · Tap Registry · Benchmarks · Issues

Octomind is an open-source coding agent harness. It gives any LLM the tools to work in a repository — read and edit files, run shells, search code, delegate to sub-agents — through MCP, and runs the result as an interactive CLI, a stdin pipe, a daemon, a WebSocket server, or an ACP agent in your editor. Most agents stop and ask a human before each risky step, which works at a keyboard and blocks everything in CI. Octomind writes that policy down as TOML guardrails and adds a supervising model that plans and checks the work, so the same session can run with nobody watching. On 25 tasks taken from merged pull requests it solved 24; OpenCode solved 19 with the same model at about twice the cost (benchmarks).

How It Works

One diagram, the whole turn: what is assembled before the model sees the request, the tool loop, how a turn is allowed to end, and what carries over to the next session.

• What the model sees is built once per user message, not per tool round: AGENTS.md, the skills whose rules match the prompt (standard SKILL.md folders), the tool bundles those skills need (they start their own MCP servers on demand), and the few past lessons that match. Skills · Learning
• Compression folds older turns into a summary that cites content-addressed blocks; the raw messages stay in a per-session archive and the recall tool brings any block back verbatim as a normal tool result, so history is never rewritten and the prompt cache survives. Compression
• Guards, hooks, validators are deterministic and live in .agents/guardrails.toml plus scripts; they run before any model opinion. The optional intent check ([supervisor.authorizer], off by default) adds one supervisor-model look after the guards and blocks a call only when it independently conflicts with what you asked for. Guardrails
• The supervisor is a second model ([supervisor.model]): it keeps the plan and reminds the model of the goal each turn, cuts oversized tool results down to the lines the task needs (copied, never retyped), and refuses a self-reported "done" until the evidence checks out. The loop check is a fixed heuristic: when the model repeats itself or stalls it gets one nudge, never a takeover. Supervisor
• The decision model ([decision]) is optional: a classifier that answers typed yes/no questions with a probability instead of prose. When set, the supervisor sends its cheap questions there — which lessons to recall, which skill to activate, which lines to keep, whether a completion claim holds — and keeps chat calls for writing. Calibrated decisions
• Learning extracts lessons after /done or at exit, in your own words, into files under learning/<project>/<role>/; later sessions recall the ones that match. With [supervisor.learning.evolution] enabled, recurring lessons become skill and guardrail candidates that run in shadow first, then an A/B trial against a control arm, and go active only when they beat it. Learning

Why Octomind?

Built for the work that keeps going after you leave:

• Policy as code, not approval popups. Deterministic guardrails — pre-call guards, post-result hooks, post-turn validators — live in TOML and scripts, so they work in CI, daemons, and scheduled runs.
• Measured, not claimed. All four agents ran stock on the same tasks with the same judge. Per-case table, artifacts, and a reproduction guide are in the benchmarks.
• Ready-made specialists. octomind run developer pulls a packaged agent (prompt, model, MCP servers, tool permissions) from a tap. It starts developer:chief, the orchestrator of the developer domain (a domain is the part of a tag before the :; its orchestrator is the agent named chief). octomind run developer:general starts one exact agent, the generalist that does the work itself. Publish your own with one repo.
• Sessions that stay sharp. Adaptive compression keeps long tasks moving without forgetting the task or your last few messages.
• Learns the project as you work. Corrections and rules you state become lessons, quoted from your own words and scoped to the project and role, and come back in later sessions. Turn on evolution and recurring lessons compile into skill and guardrail candidates, trialled against a control and kept only when they help.
• Any model, any budget. Use Octomind Cloud or your own key (OpenRouter, Anthropic, OpenAI, DeepSeek, Ollama, and more), pick a model per role, and cap spend per request and per session. Over budget, a terminal session asks y/N; a non-interactive run stops with exit code 75.
• One config. Models, tools, roles, guardrails, budgets: all TOML, no framework code.

# Interactive
octomind run developer

# Non-interactive — CI, scripts, automation
echo "Explain the auth module" | octomind run developer --format plain

# Daemon — keep it alive, talk to it from another terminal
echo "watch the build" | octomind run --name watcher --daemon --format jsonl
octomind send --name watcher "run the test suite"

Quick Start

1. Install (macOS, Linux):

curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/muvon/octomind/master/install.ps1 | iex

On macOS, you can also install with Homebrew:

brew install muvon/tap/octomind

2. Choose where models come from. Start octomind once in a terminal:

octomind

Before it writes a config, the first interactive run asks where to get models:

• Octomind hub (recommended): one browser sign-in, auto picks a model for each job, paid with credits you buy.
• Your own provider: OpenRouter, OpenAI, Anthropic, DeepSeek, Ollama, and every other provider octomind supports. Octomind asks for the key with hidden input, saves it to its own .env (readable only by you), and lists the provider's models to pick from. One model can serve the main agent, the supervisor, and compression, or you can pick each.
• Skip: keep the shipped defaults (octohub:auto).

Run octomind configure to change this later. Scripts, piped input, and --format runs never see the screen; they use the default config.

3. Run a specialist in your project:

cd ~/your/project
octomind run developer

You're now in a session with the developer domain's lead agent. It reads your code and runs commands itself, and hands code changes to the domain's specialists. The interface is a plain line prompt with markdown rendering — no TUI to learn, so it works over SSH, in tmux, and in CI logs. The first time you run a specialist, it may install its tools and ask for credentials.

developer:chief comes from the default tap muvon/tap, not your local config. Plain octomind run starts the config's default role, assistant:concierge. A name without a :, such as octomind run developer, starts that domain's orchestrator (developer:chief), unless your config defines a role with that name; the local role wins.

Try the recorded bug-fix demo: two failing tests, an agent fix, and an independent test rerun.

Benchmarks

Measured on octobench against 25 tasks harvested from merged pull requests across Python, PHP, Rust, C++, and JavaScript. Each agent works in the pre-fix repo; held-out tests from the merged fix decide pass or fail. These are the published July 30, 2026 results, not a measurement of this checkout.