Octomind — Summary

Octomind is a Rust-compiled single-binary CLI (octomind) that provides a specialist AI agent runtime: instead of prompting a generic AI, users run domain-specific agents (e.g., octomind run doctor:blood, octomind run lawyer:sg, octomind run developer) from a community tap registry — each agent ships with its own model config, system prompt, MCP servers, tool permissions, and specialist knowledge. The framework has five architectural pillars: zero-config tap-based agent discovery, adaptive context compaction (cache-aware, pressure-tiered), per-role and per-step model selection with hard spending thresholds, policy-as-code guardrails (pre-call deny, post-result hooks), and intent-driven capability auto-activation. Multi-model routing is deep: different roles within a single session can run on completely different providers (Anthropic, OpenAI, Google, DeepSeek) with per-role temperature, MCP servers, and tool permissions — all in TOML, no framework code. Agents can spawn sub-agents, enable/disable MCP servers dynamically, and be embedded via ACP (agent-to-agent protocol) or WebSocket. The closest seed analog is claude-flow (multi-agent orchestration with MCP integration), but Octomind's specialist domain focus, TOML-driven role system, and hard cost enforcement are architecturally distinct.

Octomind — Overview

Origin

Created by Muvon Un Limited (Apache-2.0 license, 59 stars, Rust, last commit 2026-05-26 — actively developed day of analysis). Version 0.29.0. The INSTRUCTIONS.md reads like a production architecture document, suggesting a team environment.

Philosophy

"Install agents, not frameworks." "Open-source runtime for specialist AI agents. One command. Any model. Any domain."

The core argument against generic AI:

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

The five pillars:

1. Zero config, full flexibility: octomind run lawyer:sg works out of the box — full customization in TOML, no framework code
2. Sessions stay sharp at hour 4: Adaptive compaction preserves decisions, file references, errors; drops noise
3. Cost as a control plane: Per-step model selection + hard spending thresholds enforce before the bill, not after
4. Guardrails: policy as code: Deterministic scripts for pre-call guards, post-result hooks, post-turn validators — fits CI
5. Intent-driven context: Skills and capabilities activate only when what you're asking for semantically matches them

Anti-patterns Targeted

"Cursor users get $7,000 surprise bills. Octomind agents trip a budget and stop, fall back, or warn — before the bill, not after." "Most agent harnesses pre-load every available tool into context. Octomind starts focused for the domain and grows only when needed."

Community Tap Registry

The most distinctive design element: specialist agents are published as TOML files in Git repos (taps). The community publishes domain expertise as doctor:medications, lawyer:us, security:owasp — one file, immediately installable. This is a package manager for specialist agents.

Octomind — Architecture

Distribution

• Type: standalone-repo (Rust binary, distributed via install.sh + cargo)
• Binary: octomind (single static binary)
• Version: 0.29.0
• Language: Rust 1.95+, tokio async

Install Methods

# One-line install
curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash
# Detects OS + architecture, installs to ~/.local/bin/

# Cargo
cargo install octomind

# Build from source
git clone https://github.com/muvon/octomind.git && cargo build --release

Required Runtime

• Rust 1.95+ (build only)
• No runtime dependencies — single statically-linked binary

Configuration Location

~/.local/share/octomind/config/config.toml (user-global) ./INSTRUCTIONS.md — custom instructions loaded as user message (configurable filename) ./CONSTRAINTS.md — appended to each user request (configurable filename) .agents/guardrails.toml — project-level policy rules

Source Structure

src/
├── main.rs              # Entry: CLI parsing → Config::load() → dispatch
├── config/              # Config types, loading, migrations
├── mcp/                 # Tool routing, server lifecycle, builtin tools
│   ├── core/            # plan, tap, capability, skill, dynamic servers
│   └── runtime/         # agent, skill, schedule, capability tools
├── session/
│   ├── chat/session/    # Main loop, command dispatch, API calls
│   ├── layers/          # AI sub-agent execution
│   ├── pipelines/       # Deterministic script pipelines
│   ├── workflows/       # AI-orchestrated multi-step workflows
│   └── learning/        # Cross-session lesson extraction/injection
├── acp/                 # ACP stdio server (agent-to-agent protocol)
├── websocket/           # WebSocket server for remote sessions
├── agent/               # Tap registry, manifest resolution
└── commands/            # CLI subcommand handlers
config-templates/
├── default.toml         # ALL config fields with defaults
└── agents/developer     # Developer agent template

Config Architecture

All behavior derives from a single resolved TOML config:

• Arrays (roles, workflows) are concatenated + deduped by name
• Tables are deep-merged
• mcp-*.toml files always load after mcp.toml (override last)
• Per-role config: get_merged_config_for_role(role) → collects explicit server_refs UNION auto_bind matches

API Keys (env vars)

OPENROUTER_API_KEY   # OpenRouter (recommended — multi-provider)
OPENAI_API_KEY       # OpenAI direct
ANTHROPIC_API_KEY    # Anthropic direct
DEEPSEEK_API_KEY     # DeepSeek direct
GOOGLE_APPLICATION_CREDENTIALS  # Google Cloud
AWS_ACCESS_KEY_ID    # Amazon Bedrock
CLOUDFLARE_API_TOKEN # Cloudflare Workers AI

Target Tools

Any LLM provider accessible via TOML config. Primary: Anthropic (Claude), OpenAI (GPT), Google (Gemini), DeepSeek, OpenRouter. Not a Claude Code plugin — standalone runtime.

Octomind — Components

CLI Subcommands (10)

Session Commands (interactive, slash-prefixed)

Roles (TOML-defined)

Default roles from config-templates/default.toml:

Tap Agents (muvon/octomind-tap registry)

Community specialists accessed via octomind run <tap>:<role>:

• octomind:assistant — general assistant
• doctor:blood — blood-test interpretation
• doctor:nutrition — nutrition specialist
• lawyer:sg — Singapore law
• developer — general development
• developer:general — general dev with language skill auto-activation

Layers (AI sub-agents)

Defined as [[layers]] in TOML — chained AI sub-agents that run after each response:

• Each layer is a role (model + tools + prompt)
• Example: context_researcher (Gemini flash) → senior_reviewer (Claude Opus)

Pipelines (deterministic)

Script-driven pre-processing stages defined as [[pipelines]] in config — run before the AI receives the message.

Workflows (AI-orchestrated multi-step)

Defined as [[workflows]] in TOML — multi-step task runners with validation loops:

[[workflows]]
name = "deep_review"
[[workflows.steps]]
name = "analyze"
layer = "context_researcher"
[[workflows.steps]]
name = "critique"
layer = "senior_reviewer"

Guardrails (.agents/guardrails.toml)

Policy-as-code rules applied deterministically:

[[guard]]
match = "shell(command=^rm\\s+-rf?)"
message = "rm -rf blocked."

[[guard]]
match = "shell(command=git push)"
when = ["+shell(command=git status)"]
message = "Review changes before pushing."

[[hook]]
match = "text_editor(path=src/.*\\.rs)"
on = "success"
script = ".agents/check-clippy.sh"

Learning System

Cross-session lesson extraction/injection (src/learning/) — the agent can extract lessons from completed sessions and inject them into future sessions for continuous improvement.

Built-in MCP Tools

tap — delegate to any specialist from registry
mcp — enable/disable MCP servers dynamically mid-session
agent — spawn a specialist sub-agent for a sub-task

Octomind — Uniqueness

differs_from_seeds

The closest seed is claude-flow in that both implement multi-agent orchestration with dynamic sub-agent spawn and MCP server management. Key differences: Octomind is a standalone Rust binary (not a Node.js npm package); it implements a tap registry (community-published specialist agents as TOML files) that has no parallel in any seed; its cost-control plane (hard per-request and per-session USD thresholds) is unique; and its adaptive cache-aware compaction engine is architecturally distinct from claude-flow's HNSW vector store. Unlike taskmaster-ai (task JSON decomposition for a single model), Octomind routes different roles to different providers within a single session and supports per-step model selection in workflows. The sandbox mode (Landlock/Seatbelt) and guardrails.toml policy-as-code approach have no analog in any of the 11 seeds.

Distinctive Positioning

1. Tap registry ecosystem: The only framework in the corpus with a community package manager for specialist agents. Publishing expertise as a TOML file and making it immediately available to all users is a novel distribution model.
2. Hard cost enforcement: Per-request and per-session USD thresholds that actually stop execution — not advisory warnings. The "$7K Cursor bill" comparison is a marketing claim backed by a real enforcement mechanism.
3. Cache-aware adaptive compaction: Calculates whether compaction is worth the cost before doing it, and never breaks the prompt-cache hit in the process. Structurally preserving (keeps decisions, drops noise). Zero user interaction.
4. ACP protocol: First framework in this batch that implements a formalized agent-to-agent communication protocol (ACP stdio) — Octomind can be called as a sub-agent by external orchestrators.
5. OS-native sandbox: Rust + Landlock (Linux) / Seatbelt (macOS) sandbox mode restricts filesystem writes at the OS level — not just advisory.
6. Rust implementation: Single static binary, no Node.js/Python runtime needed, fast startup, memory-safe.

Observable Failure Modes

• Low star count (59) for its ambition: The feature set is enterprise-grade but community adoption is nascent; tap ecosystem is thin
• TOML config complexity: Per-role, per-layer, per-workflow, per-pipeline config can become difficult to manage at scale
• ACP compatibility: ACP is not an established standard — only Octomind currently implements both sides
• Learning system opacity: Cross-session lesson extraction/injection is not documented in detail — behavior may be unpredictable
• Provider-specific compaction: Cache keepalive only works for Anthropic (1h TTL) — other providers silently skip pings
• Tap ecosystem bootstrapping: The community tap registry is new; specialist agents for obscure domains may not yet exist