Pipe it, schedule it, embed it. One binary, any model, MCP-native — built for autonomous work, not just chat.

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.

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. 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.

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.

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."

Layer When it runs What it does

Guards Before a tool call Deny by capability, argument regex, and session history. A match returns a denial instead of executing the call.

Hooks After a tool result A non-zero exit injects stdout into the agent's inbox — lint and format failures become automatic corrections without restarting the turn.

Validators After a turn Scripts the agent reads on its next turn. This replaces "approve this change?" prompts in autonomous loops.

Hook and validator script examples: Guardrails guide.

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.

Feature What you get Learn more

Specialists & taps Packaged agents with model, prompt, MCP servers, and permissions; installs their tool dependencies on first use Tap system

Roles Per-role model, temperature, system prompt, tools Roles

Workflows Multi-step pipelines, each step with its own model and toolset Workflows

MCP client stdio and Streamable HTTP servers, with OAuth; enable/disable servers mid-session MCP tools

Intent-driven context Skills and capabilities activate on demand, keeping context small Skills

Local project tools Executable scripts in .agents/tools/ auto-register as tools Local tools

Supervisor & learning External planning and gating; file-backed learning records Supervisor, Learning

Sandbox --sandbox restricts filesystem writes to the working directory Config reference

Token efficiency Cache-aware accounting and compaction Token efficiency

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.

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

The octomind- prefix is added automatically: yourteam/my-tap maps to the repository yourteam/octomind-my-tap.

Method Command

Install script (recommended) curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash

Install script (Windows PowerShell) irm https://raw.githubusercontent.com/muvon/octomind/master/install.ps1 | iex

Homebrew (macOS) brew install muvon/tap/octomind

Scoop (Windows) scoop bucket add muvon https://github.com/Muvon/scoop-bucket then scoop install muvon/octomind

Cargo (Rust 1.95+) cargo install octomind

Docker docker run --rm ghcr.io/muvon/octomind --help

From source git clone https://github.com/muvon/octomind.git && cd octomind && cargo build --release

The install script detects your OS and architecture (Linux and macOS on x86_64/aarch64) and installs to ~/.local/bin/. Pass --install-dir <DIR> or set OCTOMIND_INSTALL_DIR to override. On Windows (x86_64/aarch64), install.ps1 installs to %LOCALAPPDATA%\octomind\bin and adds it to your user PATH; it honors OCTOMIND_INSTALL_DIR and OCTOMIND_VERSION too. install.sh still works from Git Bash or MSYS2.

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.

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

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

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.

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.

Command Description

/help Show all commands

/info Token usage and costs

/model anthropic:claude-haiku-4-5 Switch model mid-session

/role developer:general Switch to a configured role or tap tag

/new Review auth Start a fresh session (title optional)

/done Force context compression and start background learning extraction when enabled

/exit Exit the session

Full list: Session commands.

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, honored first export OCTOMIND_TELEMETRY=0 # for subsequent commands in this shell

or set telemetry = false in config.toml

Exact field list: Telemetry.

Start here Go deeper Integrate Reference

Installation Roles WebSocket server CLI

Quickstart Workflows ACP protocol Config

Configuration Compression Daemon & hooks Session commands

Providers & models Guardrails Editor integration Environment variables

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

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.

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.

Community participation follows our Code of Conduct. Report vulnerabilities privately using the security policy.