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. The same runtime supports several entry points: 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; send from another terminal on the same machine
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; taps install their own tool 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 — first use may install tools and request credentials
octomind run developer:general

        Octomind v0.50.1
        Role: developer:general · 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 merged pull requests across python, php, rust, c++, and js. 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 the current checkout:

• The harness matters. opencode used the same model and endpoint. octomind solved 24 vs 19 at roughly half the cost. Octomind used a staged tap and a binary override with the unfinished-handback pre-gate; this measures the complete setup, not individual features.
• 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?

The runtime gives you controls for the work that continues after you leave the keyboard:

• Autonomy needs policy. Enforce pre-call rules and feed script failures back to the agent with Guardrails.
• Share a working setup. A tap packages agent instructions, dependencies, and tool access. Start a specialist with octomind run developer:general.
• Choose a specialist. Use different roles for debugging, research, or review, with their own instructions, model overrides, and tools.
• Keep long tasks moving. Compression reduces accumulated context while retaining task knowledge and the live exchange.
• Track spending. Configure request and session thresholds and inspect costs with /info. See Cost.
• Load context on demand. Skills and capabilities can activate from your input.

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 alive; run send in another terminal on the same machine
echo "first task" | octomind run --name watcher --daemon --format jsonl
octomind send --name watcher "now run the test suite"

# Structured output — create the schema first (requires a supporting model)
cat > todos.schema.json <<'JSON'
{
  "type": "object",
  "properties": {"items": {"type": "array", "items": {"type": "string"}}},
  "required": ["items"],
  "additionalProperties": false
}
JSON
echo "List TODO items as JSON" | octomind run developer:general --format jsonl --schema todos.schema.json

octomind run has no message argument: its positional argument is a role or tap tag. Piped stdin runs non-interactively, defaulting to plain; --format plain or --format jsonl selects the output format. At a terminal, --format without piped input errors unless you also use --daemon. Without --format, a terminal starts an interactive session.