Install agents, not frameworks.
Open-source runtime for specialist AI agents. One command. Any model. Any domain.
[](LICENSE)
[](https://crates.io/crates/octomind)
[](https://github.com/muvon/octomind/stargazers)
[](https://octomind.run)
[Documentation](https://octomind.run/docs/) · [Tap Registry](https://github.com/muvon/octomind-tap) · [Website](https://octomind.run)
---
## Table of Contents
- [The Problem](#the-problem)
- [Five Pillars](#five-pillars)
- [Pillar 1 — Zero Config, Full Flexibility](#pillar-1--zero-config-full-flexibility)
- [Pillar 2 — Sessions That Stay Sharp at Hour 4](#pillar-2--sessions-that-stay-sharp-at-hour-4)
- [Pillar 3 — Cost as a Control Plane](#pillar-3--cost-as-a-control-plane)
- [Pillar 4 — Guardrails: Policy as Code, Not Approval Clicks](#pillar-4--guardrails-policy-as-code-not-approval-clicks)
- [Pillar 5 — Intent-Driven Context: Skills Activate on What You Mean](#pillar-5--intent-driven-context-skills-activate-on-what-you-mean)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Power Users — Roles, Workflows, Layers](#power-users--roles-workflows-layers)
- [Embedders — ACP, WebSocket, Daemon](#embedders--acp-websocket-daemon)
- [Installation](#installation)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Contributing](#contributing)
- [License](#license)
---
## The Problem
Building a specialist AI agent in 2026 means stitching together three different tools, writing glue code nobody wants to own, and praying it holds. You spend 45 minutes wiring MCP servers, system prompts, tool configs, and credentials — every domain, every machine, every time.
- **Config Wars.** No central registry. Skills here, MCP servers there, agent configs nowhere. The community calls it ["solidarity in frustration."](https://dev.to/satinathnit/the-agent-config-wars-why-your-ai-agent-documentation-is-already-obsolete-4d6i)
- **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](https://dev.to/aibughunter/ai-agents-in-april-2026-from-research-to-production-whats-actually-happening-55oc) for serious work.
- **One generic assistant for every task.** Rust debugging, blood-test interpretation, contract review — same prompt, same tools. Drift compounds.
- **Sessions break at hour 4.** Naive truncation drops the decisions you need. Quality collapses. You restart.
- **Bills surprise you.** Cursor users posting $7K daily overages. No per-task budget, no kill switch.
Octomind ships specialist agents ready to run — and a runtime that grows with you.
---
## Five Pillars
| Pillar | What it gives you |
|---|---|
| **Zero config, full flexibility** | `octomind run lawyer:sg` works out of the box. Need a different model, MCP server, or guardrail pipe? Same TOML, no framework code. |
| **Sessions stay sharp at hour 4** | Adaptive compaction: cache-aware, structurally preserving. Smaller context = faster responses + lower cost. |
| **Cost as a control plane** | Per-step model selection across many providers. Hard spending caps and cache-aware accounting come for free. |
| **Guardrails: policy as code** | Govern autonomous agents with deterministic scripts — pre-call guards, post-result hooks, post-turn validators. No modal approval clicks. Fits CI. |
| **Intent-driven context** | Skills and capabilities activate only when what you're asking for matches them. Smaller context by default, lower cost, no surprise tools. |
---
## Pillar 1 — Zero Config, Full Flexibility
Most agent tools force a tradeoff: zero-config (Lindy, no-code) or fully customizable (Mastra, LangGraph). Octomind gives you both. `octomind run lawyer:sg` works out of the box. Need a different model, a custom MCP server, a guardrail pipe — all live in TOML, no framework code.
```bash
octomind run developer:general # general dev, language skills auto-activate
octomind run doctor:blood # blood-test interpretation specialist
octomind run doctor:nutrition # nutrition specialist
```
### What happens when you run a specialist
```
→ Fetches the agent manifest from the tap registry
→ Installs required binaries automatically (skips if already present)
→ Prompts once for any credentials, saves permanently
→ Spins up the right MCP servers for this domain
→ Loads specialist model config, system prompt, tool permissions
→ Ready in ~5 seconds, not 45 minutes
```
This is **packaged expertise** — not a prompt file, not a skill injection. The full stack, configured by the community, ready to run.
### Specialists grow at runtime
Every agent has built-in power tools that let it acquire new capabilities and spawn sub-agents mid-session, without restart:
| Tool | What it does |
|---|---|
| `tap` | Delegate to any specialist role from the tap registry. Foreground for an inline reply or background for long tasks. |
| `mcp` | Enable or disable MCP servers on the fly. Agent picks the server it needs and registers it mid-conversation. |
| `agent` | Spawn a specialist sub-agent for a sub-task. Sub-agent runs, returns, parent continues. |
```
User: "Cross-reference our Postgres metrics with the deployment log"
Agent:
→ mcp.enable(postgres-mcp) # auto-detected need, no user prompt
→ agent.spawn(log_reader) # delegates log parsing
→ results merge mid-session
→ mcp.disable(postgres-mcp) # cleans up
→ presents the analysis
```
Most agent harnesses pre-load every available tool into context. Octomind starts focused for the domain and grows only when needed. **Smaller context, lower cost, faster responses, no surprise tools.** See [Pillar 5](#pillar-5--intent-driven-context-skills-activate-on-what-you-mean) for how activation actually works.
### Add your own taps
```bash
octomind tap yourteam/tap # clones github.com/yourteam/octomind-tap
octomind tap yourteam/internal ~/path # local tap for private agents
octomind run finance:analyst # available immediately
octomind run security:owasp
```
Each tap is a Git repo. Each agent is one TOML file. Pull requests are contributions.
> Want to publish your expertise? A `doctor:medications`, a `lawyer:us`, a `devops:terraform`. One file, and everyone with that problem gets a specialist instantly. [How to write a tap agent →](https://github.com/muvon/octomind-tap)
---
## Pillar 2 — Sessions That Stay Sharp at Hour 4
Every coding agent degrades after a few hours. Context fills. Decisions get truncated. The agent forgets why it started.
Octomind's adaptive compaction engine runs automatically:
- **Cache-aware** — calculates if compaction is worth it *before* paying for it. Never breaks the prompt-cache hit by accident.
- **Pressure-tiered** — compacts more aggressively as context grows.
- **Structurally preserving** — keeps decisions, file references, errors, dependencies; drops noise.
- **Plan-aware and free-form-aware** — works whether you use the `plan` tool or have a free-form chat.
- **Fully automatic** — you never think about it.
The second-order benefit: smaller context means **fewer tokens, faster responses, lower cost** every turn after compaction fires. The three pillars compound.
> Work on a hard problem for 4 hours. The agent still knows what it decided in hour one.
---
## Pillar 3 — Cost as a Control Plane
Pick the right model for each step. A cheap one for routine research, a frontier one for review — per-role, per-step, mid-session swap. Real-time cost tracking and hard spending caps come for free.
```toml
# Per-role model selection — pay Opus only where it's worth it
[[roles]]
name = "researcher"
model = "openrouter:google/gemini-2.5-flash" # cheap broad context
[[roles]]
name = "reviewer"
model = "anthropic:claude-opus-4-7" # precision where it counts
# Hard spending limits — enforced, not advisory
max_request_spending_threshold = 0.50 # USD per request
max_session_spending_threshold = 5.00 # USD per session
```
- Per-role and per-layer model selection across many providers via [octolib](https://github.com/muvon/octolib) — different roles can run on different vendors.
- Mid-session model swap with `/model anthropic:claude-haiku-4-5`.
- Real-time cost tracking per request and per session.
- Cache-aware token accounting (`cache_read_tokens`, `cache_write_tokens` separated from input/output).
- Hard spending thresholds with enforcement. On a **session cap** Octomind prompts you to continue (interactive) or auto-stops (non-interactive); on a **request cap** it stops execution outright — before the bill, not after.
> Cursor users get $7,000 surprise bills. Octomind agents trip a budget and stop — interactive sessions ask before continuing, non-interactive runs halt automatically.
---
## Pillar 4 — Guardrails: Policy as Code, Not Approval Clicks
Other agent CLIs make the human the safety layer: every dangerous tool call pops a modal, every file write waits for a click. That works for one developer at the keyboard. It breaks the moment you point an agent at a long-running task, a CI job, or an autonomous loop.
Octomind takes the opposite position. **Policy lives in scripts, not prompts.** Drop a `.agents/guardrails.toml` in your repo and the runtime enforces it deterministically — pre-call, post-result, post-turn.
```toml
# 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."
# Post-result hook — non-zero exit injects feedback into the agent's inbox
[[hook]]
match = "text_editor(path=src/.*\\.rs)"
on = "success"
script = ".agents/check-clippy.sh"
# Post-turn validator — fires only over the call slice since it last ran
[[validator]]
name = "tests-pass"
roles = ["developer"]
script = ".agents/run-tests.sh"
```
- **Guards** — pre-call deny rules. Match by `capability(arg_name=regex)`, gate by history (`+used` / `-unused`), require loaded capabilities (`has = [...]`). The agent never even attempts a blocked call.
- **Hooks** — post-result scripts. Run after each tool returns. Non-zero exit injects stdout into the agent's inbox as a user message — clippy errors, lint failures, format diffs become *automatic corrections without restarting the turn*.
- **Validators** — post-turn scripts. Fire only over the new call-log slice (cursor-based, never re-fires on old activity). Filter by role. Output is wrapped in `