octomind

Octomind is an open-source AI agent client and agent runtime. Its core positioning is to let models call MCP tools to accomplish actual work—reading and writing files, running shell commands, searching code, and delegating to subagents. The same runtime supports multiple entry points: the same session can run interactively, be piped in via stdin, run as a background daemon, be served over WebSocket, or be embedded into other agent stacks as an ACP subagent. Models, tools, roles, guardrails, and budgets are all configured using TOML, with no framework code required.

Main capabilities

1. A single binary, five runtime interfaces Octomind is delivered as a single binary. The command-line interface uses a plain-text line mode, supports Markdown rendering and shell completion, requires no learning of a TUI, and can be used over SSH, tmux, and CI logs. The positional argument to octomind run is a role or tap tag, not a message. Piped stdin runs non-interactively, using plain format by default, and the output format can be selected via --format plain or --format jsonl. In a terminal, omitting --format starts an interactive session. server and acp do not accept --format. --daemon keeps the process alive but does not detach it from the terminal; octomind send must be used in another terminal.

2. Ways to connect to models You can connect to Octomind Cloud via octomind login—this subscription includes model access through the octohub gateway, with no additional configuration required. You can also skip login entirely and bring your own key for any provider: OpenRouter, Anthropic, OpenAI, DeepSeek, Ollama, etc. Cloud is the baseline option, and BYOK is always a first-class path.

3. Expert roles and Taps The built-in default tap is muvon/tap, providing experts such as developer:general, lawyer:sg, and doctor:blood. The default tag for configuring itself is assistant:concierge, so running octomind run directly starts that role. Each tap is a Git repository, and each agent is a TOML file. You can run developer:gen via octomind runeral launch expert. Users can publish their own taps, such as doctor:medications, lawyer:us, devops:terraform.

IV. Guardrails — Policy as Code Place .agents/guardrails.toml in the repository, and it will be executed deterministically at runtime. This includes: Guards (pre-call rejection rules, matchable by capability(arg_name=regex), gated by history +used / -unused, requiring loaded capabilities has = [...]); Hooks (scripts that run after tool results; a non-zero exit injects stdout into the agent inbox as a user message); Validators (post-turn scripts that check calls since the previous turn filtered by when history, with output wrapped in a <validation> block for the agent to read in the next turn). This DSL combines capability, arg-regex, history, role, and result-regex in a single declarative file, requiring no compiled code or plugin installation, and is suitable for CI, daemons, scheduled tasks, and ACP subagents.

V. Cost Control Supports selecting models by role and by workflow step across multiple providers (OpenRouter, OpenAI, Anthropic, Google, DeepSeek, Amazon Bedrock, Cloudflare, etc., via octolib). You can switch models mid-session with /model anthropic:claude-haiku-4-5, and the session total includes usage from model switches. It provides real-time cost tracking per request and per session, as well as cache-aware token accounting (cache_read_tokens and cache_write_tokens separate from input/output). Request and session thresholds are configurable; both are off by default and are continuity checks rather than prepaid billing limits.

VI. Long-Task Context Retention The adaptive compaction engine runs automatically: cache-aware (calculates whether it is worthwhile before paying the compaction cost), growth-aware (adjusts the compaction target based on measured growth and the context limit), structure-preserving (retains key knowledge, selected analysis findings, and live exchanges), and plan-aware (the supervisor tracks complex work externally). Sessions can be persisted: octomind run --name my-feature saves while running, octomind run --resume my-feature or --resume-recent to resume. Use /done at task boundaries to force compaction and start background learning.

1. Intent-driven context Roles determine the tools loaded at startup, and additional skills and capabilities can be activated as the task evolves. Skills inject instructions and load the required capabilities, remaining active until forgotten or cleared at task boundaries. Activation mechanisms include: semantic rules (an internal embedding model scores requests against a skill's semantic phrases and capability trigger phrases), manual rules (skill authors can pin activation to file names, file contents, or exact phrases), abstention on close semantic ties, and calibration to skip rather than guess. Activating a skill also enables the required capability servers. Deactivated skills are discarded on compaction, and their content can be restored on the next activation.

2. MCP tools Octomind is an MCP client supporting stdio and Streamable HTTP servers, supports OAuth, and internally routes built-in tools. File system tools (via octofs): view, text_editor, batch_edit, extract_lines, shell, workdir. Brain (via octobrain): memorize, remember, forget, knowledge for persistent memory and knowledge indexing. core, orchestration, runtime, agent are the four built-in MCP servers in the default configuration. Local project tools: put executable scripts with an # @description header into <workdir>/.agents/tools/, and they will be automatically discovered as MCP tools for that project.

3. Advanced configuration Supports per-role model overrides, system prompts, MCP servers, and tool permissions; Layers (ACP subprocess stages, also used for the /run command); Guardrails (deterministic policies and input pipelines); Workflows (a task runner with sequential, parallel, conditional, and loop steps); Supervisor (out-of-band planning, loop/no-progress detection, completion verification, tool output condensation, and cross-session learning). All in TOML, no code required.

Installation

One-line install command: automatically detects the OS and architecture, and installs to ~/.local/bin/ by default. Supports macOS, Linux, and Windows; on Windows it must be run from Git Bash or MSYS2. The agent is a Rust binary, and external MCP tools have their own dependencies.

cargo install octomind (requires Rust 1.95+), or build from source.

Using Octomind Cloud: octomind login for device code login (similar to gh auth login), stores locally the octohub gateway key issued by the server, and the default configuration already sets name = "octohub:auto" under [model].

Bring your own key: Octomind is fully open source and can run independently with supported providers; add the key you choose to ~/.bashrc or ~/.zshrc.

Limitations and notes

The installation command may require Rust 1.95+; external MCP tools have their own dependencies. Cost thresholds are continuity checks, and provider calls may exceed the configured amount. Compaction itself consumes tokens and may invalidate the cache. Available providers depend on the version of octolib linked into the binary. For some feature details such as the WebSocket server, ACP protocol, daemon and hooks, structured output, etc., the materials only mention their names, and specific configuration requirements are not yet provided.