octomind

Documentation · Tap Registry · Website

Octomind is an open-source AI agent client: the model calls MCP tools to do real work — read and write files, run shells, search code, delegate to sub-agents. Most agent CLIs are chat interfaces that happen to run in a terminal. Octomind is a runtime that happens to have one: the same session runs interactively, piped through stdin, as a background daemon, over WebSocket, or as an ACP sub-agent inside another agent's stack. Models, tools, roles, guardrails, budgets — all of it is TOML, no framework code.

# Interactive
octomind run developer:general

# Piped — CI, scripts, automation
echo "Explain the auth module" | octomind run developer:general --format plain

# Daemon — long-running, inject messages from anywhere
echo "watch the build" | octomind run --name watcher --daemon --format jsonl
octomind send --name watcher "run the test suite"

Table of Contents

• Quick Start
• Benchmarks — Real PRs, Held-Out Tests
• Why Octomind?
• One Binary, Five Surfaces
• Guardrails — Policy as Code
• Cost as a Control Plane
• Sessions That Stay Sharp at Hour 4
• Intent-Driven Context
• Specialists & Taps
• Built-in MCP Tools
• Power Users — Roles, Workflows, Layers
• Installation
• Configuration
• Architecture
• Contributing
• Documentation
• License

Quick Start

# Install (macOS & Linux) — single Rust binary, no runtime dependencies
curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash

# Sign in — models included, no API keys to manage
octomind login

# Start with a specialist — no setup required
octomind run developer:general

        Octomind v0.40.2
        Role: developer · Model: octohub:auto
        ~/your/project
> _

You're in a session with an agent that can read your code, run commands, edit files, and grow capabilities as needed. Plain-line interface with markdown rendering and shell completions — no TUI to learn, works over SSH, in tmux, in CI logs.

octomind login connects you to Octomind Cloud — a subscription that includes model access through the octohub gateway, so there's nothing to configure. Prefer your own keys? Skip login entirely and bring any provider: OpenRouter, Anthropic, OpenAI, DeepSeek, Ollama, and more. Cloud is the baseline; BYOK is always a first-class path.

developer:general (and lawyer:sg, doctor:blood, …) come from the built-in default tap muvon/tap, not your local config. The config's own default tag is assistant:concierge, so plain octomind run starts that. The banner above is illustrative (the real one renders a pixel icon to the left of the text block).

Other installs: cargo install octomind (Rust 1.95+) or build from source.

Benchmarks — Real PRs, Held-Out Tests

We benchmark on octobench: 25 tasks harvested from pull requests merged in 2026 — mostly after model training cutoffs — across python, php, rust, c++, and js. Each agent works in the pre-fix repo; the merged fix's own maintainer-written tests (which the agent never sees) decide pass or fail. Four agents, stock single-agent invocations, no tuning:

• The harness is the leverage. opencode ran the same model on the same endpoint at the same prices — a pure harness A/B. octomind solved 24 vs 19, at half the cost: context discipline plus supervision on exactly the deep-root-cause tasks where unsupervised agents declare victory too early.
• Worst-case pricing, still ahead. glm-5.2 ran without prompt caching (every token at list price) while Opus billed ~97% of context re-reads at 1/10 cache rates — and octomind still led on solves, cost, and wall time.
• Reproducible. Full per-case table, run artifacts, and reproduction guide: BENCHMARK.md @ 8aa3968. The story behind the benchmark: blog post.

Why Octomind?

Agent CLIs in 2026 all do interactive chat well. The gaps open up the moment you leave the keyboard:

• Autonomy needs policy, not popups. Other CLIs make the human the safety layer — every dangerous call waits for an approval click. That breaks in CI, daemons, and scheduled runs. Octomind enforces deterministic guardrails from a TOML file instead. See Guardrails.
• Config wars. No central registry. Skills here, MCP servers there, agent configs nowhere. The community calls it "solidarity in frustration." Octomind ships a tap registry: each agent is one TOML file in a Git repo, octomind run category:variant and it works.
• Generic AI hallucinates in expert domains. ChatGPT writes wrong drug dosages. Lawyers cite cases that don't exist. Multi-agent specialization is now the default architecture for serious work — Octomind runs packaged specialists, one command each.
• One generic assistant for every task. Rust debugging, blood-test interpretation, contract review — same prompt, same tools. Drift compounds.
• Sessions break at hour 4. Naive truncation drops the decisions you need. Quality collapses. You restart. Octomind's compaction is cache-aware and structurally preserving. See Sessions.
• Bills surprise you. Cursor users posting $7K daily overages. No per-task budget, no kill switch. Octomind enforces hard spending caps — before the bill, not after. See Cost.
• Context is preloaded and bloated. Most harnesses load every tool and skill up front. Octomind activates skills and capabilities on intent. See Intent-Driven Context.

One Binary, Five Surfaces

The same session engine, exposed however your workflow needs it:

# ACP — drop into any multi-agent system as a sub-agent
octomind acp developer:general

# Non-interactive — the message is read from stdin (pipe it in), output as plain text
echo "Explain the auth module" | octomind run developer:general --format plain

# Structured JSONL output for pipelines
echo "List TODO items" | octomind run developer:general --format jsonl

# Daemon — keep a session alive and inject messages into it from anywhere
echo "first task" | octomind run --name watcher --daemon --format jsonl
octomind send --name watcher "now run the test suite"

# Structured output — constrain replies to a JSON Schema (structured-output models only)
echo "List TODO items as JSON" | octomind run developer:general --format jsonl --schema todos.schema.json

octomind run has no message argument — wh