Octomind

Website · Docs · Tap Registry · Benchmarks · Issues

Octomind is a CLI-first AI coding agent runtime. It gives an LLM real access to your repo — reading and writing files, running shells, searching code, delegating to sub-agents — through MCP tools. The same session engine works interactively, piped through stdin, as a background daemon, over WebSocket, or as an ACP sub-agent inside another agent's stack.

# Interactive
octomind run developer:general

# Piped — CI, scripts, automation
echo "Explain the auth module" | octomind run developer:general --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"

Why Octomind?

Most coding agents assume a human is watching the screen. Octomind is 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.
• Proven on real PRs. It solved 24 of 25 held-out tasks at lower cost than the closest competitor. See the benchmarks.
• Ready-made specialists. octomind run developer:general pulls a packaged agent (prompt, model, MCP servers, tool permissions) from a tap. Publish your own with one repo.
• Sessions that stay sharp. Adaptive compression keeps long tasks moving while retaining task knowledge and the live exchange.
• 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.
• One config. Models, tools, roles, guardrails, budgets: all TOML, no framework code.

Quick Start

1. Install (macOS, Linux; Windows via Git Bash or MSYS2):

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

On macOS, you can also install with Homebrew:

brew install muvon/tap/octomind

2. Get model access. The fastest path is Octomind Cloud, which includes models and needs no configuration:

octomind login

Prefer your own provider key? Skip login and export one (also OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY), then follow Model access to point the config at it:

export OPENROUTER_API_KEY="your_key"

3. Run a specialist in your project:

cd ~/your/project
octomind run developer:general

You're now in a session with an agent that can read your code, run commands, and edit files. 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:general comes from the default tap muvon/tap, not your local config. Plain octomind run starts the config's default role, assistant:concierge.

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.

• The harness matters. opencode used the same model and endpoint; octomind solved 24 vs 19 at roughly half the cost. Octomind ran with a staged tap and a binary override including the unfinished-handback pre-gate, so this measures the complete setup, not individual features.
• Worst-case pricing, still ahead. glm-5.2 ran without prompt caching while Opus billed ~97% of context re-reads at cache rates — and octomind still led on solves, cost, and wall time.
• Reproducible. Per-case table, artifacts, and reproduction guide: BENCHMARK.md. Background: blog post.

Guardrails: Policy as Code

Drop a .agents/guardrails.toml in your repo. The runtime enforces it deterministically, with no code to compile and no plugin to install.

# Pre-call deny — block a class of calls before they execute
[[guard]]
match   = "shell(command=^rm\\s+-rf?)"
message = "rm -rf blocked."

# Conditional rule — only fires after the agent ran git status this session
[[guard]]
match   = "shell(command=git push)"
when    = ["+shell(command=git status)"]
message = "Review changes before pushing."

Hook and validator script examples: Guardrails guide.

Five Ways to Run It

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

Need machine-readable results? Pass --schema schema.json to constrain the final response to a JSON Schema (requires a model with structured-output support). See Structured output.

Features

Specialists

octomind run developer:general    # general dev, language skills auto-activate
octomind run doctor:blood         # blood-test interpretation specialist
octomind run lawyer:sg            # legal specialist

Running a specialist fetches its manifest from the tap registry, installs any required binaries, resolves credentials, starts the right MCP servers, and then opens the session.

Build and register your own:

octomind tap init yourteam/octomind-tap   # scaffold, validate, git-init, and register locally
octomind tap yourteam/octomind-tap        # on another machine, after publishing to GitHub

Installation

The install script detects your OS and architecture (Linux and macOS on x86_64/aarch64; Windows on x86_64/aarch64 via Git Bash or MSYS2) and installs to ~/.local/bin/. Pass --install-dir <DIR> or set OCTOMIND_INSTALL_DIR to override.

Command not found? Add the install directory to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Building from source requires protoc; see Building from source for per-OS prerequisites.

Verify:

octomind --version
octomind config      # generate the default config
octomind run         # start your first session

Shell completions: octomind completion <bash|zsh|fish|elvish|powershell>.

Model access

Octomind Cloud — octomind login (device-code sign-in, like gh auth login) stores a gateway key locally. The default config already uses octohub:auto. Learn more.

Bring your own key — set the provider's environment variable (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, …) and point the model tables at it. The supervisor and compression profiles also default to octohub:auto, so update all three:

[model]
name = "openrouter:google/gemini-2.5-flash"

[supervisor.model]
name = "openrouter:google/gemini-2.5-flash"

[compression.model]
name = "openrouter:google/gemini-2.5-flash"

Provider details and per-role overrides: Providers & models.

Configuration

Config lives at ~/.local/share/octomind/config/config.toml on macOS and Linux, and under %LOCALAPPDATA%/octomind/config/ on Windows. Set OCTOMIND_DATA_DIR to override the data root.

octomind config --show       # view current config
octomind config --validate   # validate config

Override any value for a single run with -c:

octomind run -c supervisor.enabled=false

Full reference: Configuration reference · Environment variables.

Session commands

Full list: Session commands.

Telemetry

Octomind reports anonymous usage: which commands, tools, and models are used, plus timings, token counts, and error kinds. It never sends your code, prompts, file paths, tool arguments, or environment values. Opt out in any of three ways:

export DO_NOT_TRACK=1          # the cross-tool standard, honoured first
export OCTOMIND_TELEMETRY=0    # for subsequent commands in this shell
# or set `telemetry = false` in config.toml

Exact field list: Telemetry.

Documentation

Full index: doc/README.md · Hosted: octomind.run/docs.

Contributing

The most impactful contribution isn't code — it's specialist agents. A cardiologist publishing doctor:medications. A tax attorney publishing lawyer:us. A security researcher publishing security:owasp. One TOML file, and everyone facing that problem gets a specialist-grade AI.

• How to write a tap agent
• Open issues

Code contributions are welcome too. Set up the hooks and run the gate before you push:

pip install pre-commit && pre-commit install
make dev    # fmt + clippy + test

Commits follow Conventional Commits. Full guide, architecture overview, and code conventions: CONTRIBUTING.md · internals: Architecture.

License

Apache License 2.0 — see LICENSE.