{"id":49741051,"url":"https://github.com/Muvon/octomind","last_synced_at":"2026-05-26T09:01:24.451Z","repository":{"id":298135553,"uuid":"994166447","full_name":"Muvon/octomind","owner":"Muvon","description":"Plug and play AI agents for any domain","archived":false,"fork":false,"pushed_at":"2026-05-20T10:21:58.000Z","size":6361,"stargazers_count":56,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-20T12:29:24.894Z","etag":null,"topics":["agentic-ai","ai","ai-agents","ai-assistant","ai-developer","autonomous-agents","claude-code","cli","cli-app","code-assist-tool","code-assistant","developer-tools","development","mcp","mcp-server","rust","semantic-search","vibe-coding"],"latest_commit_sha":null,"homepage":"https://octomind.run","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Muvon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-01T11:09:23.000Z","updated_at":"2026-05-20T08:39:31.000Z","dependencies_parsed_at":"2026-04-01T22:04:17.815Z","dependency_job_id":null,"html_url":"https://github.com/Muvon/octomind","commit_stats":null,"previous_names":["muvon/octomind"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/Muvon/octomind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctomind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctomind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctomind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctomind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Muvon","download_url":"https://codeload.github.com/Muvon/octomind/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctomind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai","ai-agents","ai-assistant","ai-developer","autonomous-agents","claude-code","cli","cli-app","code-assist-tool","code-assistant","developer-tools","development","mcp","mcp-server","rust","semantic-search","vibe-coding"],"created_at":"2026-05-09T19:00:48.056Z","updated_at":"2026-05-26T09:01:24.445Z","avatar_url":"https://github.com/Muvon.png","language":"Rust","funding_links":[],"categories":["Terminal-native coding agents"],"sub_categories":["Open Source"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://octomind.run\" target=\"_blank\"\u003e\n    \u003cimg src=\"assets/logo.svg\" width=\"640\" alt=\"Octomind — AI Agent Runtime\" /\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\u003cbr /\u003e\n  \u003cstrong\u003eInstall agents, not frameworks.\u003c/strong\u003e\u003cbr /\u003e\n  \u003cem\u003eOpen-source runtime for specialist AI agents. One command. Any model. Any domain.\u003c/em\u003e\n  \u003cbr /\u003e\u003cbr /\u003e\n\n  [![License](https://img.shields.io/badge/license-Apache%202.0-7c3aed?style=flat-square)](LICENSE)\n  [![Version](https://img.shields.io/crates/v/octomind?style=flat-square\u0026color=7c3aed)](https://crates.io/crates/octomind)\n  [![GitHub stars](https://img.shields.io/github/stars/muvon/octomind?style=flat-square\u0026color=7c3aed)](https://github.com/muvon/octomind/stargazers)\n  [![Website](https://img.shields.io/badge/website-octomind.run-7c3aed?style=flat-square)](https://octomind.run)\n\n  \u003cbr /\u003e\n\n  [Documentation](https://octomind.run/docs/) · [Tap Registry](https://github.com/muvon/octomind-tap) · [Website](https://octomind.run)\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [The Problem](#the-problem)\n- [Five Pillars](#five-pillars)\n- [Pillar 1 — Zero Config, Full Flexibility](#pillar-1--zero-config-full-flexibility)\n- [Pillar 2 — Sessions That Stay Sharp at Hour 4](#pillar-2--sessions-that-stay-sharp-at-hour-4)\n- [Pillar 3 — Cost as a Control Plane](#pillar-3--cost-as-a-control-plane)\n- [Pillar 4 — Guardrails: Policy as Code, Not Approval Clicks](#pillar-4--guardrails-policy-as-code-not-approval-clicks)\n- [Pillar 5 — Intent-Driven Context: Skills Activate on What You Mean](#pillar-5--intent-driven-context-skills-activate-on-what-you-mean)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Power Users — Roles, Workflows, Layers](#power-users--roles-workflows-layers)\n- [Embedders — ACP, WebSocket, Daemon](#embedders--acp-websocket-daemon)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Architecture](#architecture)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## The Problem\n\nBuilding 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.\n\n- **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)\n- **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.\n- **One generic assistant for every task.** Rust debugging, blood-test interpretation, contract review — same prompt, same tools. Drift compounds.\n- **Sessions break at hour 4.** Naive truncation drops the decisions you need. Quality collapses. You restart.\n- **Bills surprise you.** Cursor users posting $7K daily overages. No per-task budget, no kill switch.\n\nOctomind ships specialist agents ready to run — and a runtime that grows with you.\n\n---\n\n## Five Pillars\n\n| Pillar | What it gives you |\n|---|---|\n| **Zero config, full flexibility** | `octomind run lawyer:sg` works out of the box. Need a different model, MCP server, or pipeline? Same TOML, no framework code. |\n| **Sessions stay sharp at hour 4** | Adaptive compaction: cache-aware, structurally preserving. Smaller context = faster responses + lower cost. |\n| **Cost as a control plane** | Per-step model selection across many providers. Hard spending caps and cache-aware accounting come for free. |\n| **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. |\n| **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. |\n\n---\n\n## Pillar 1 — Zero Config, Full Flexibility\n\nMost 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 pipeline of agents — all live in TOML, no framework code.\n\n```bash\noctomind run developer            # general dev, language skills auto-activate\noctomind run doctor:blood         # blood-test interpretation specialist\noctomind run doctor:nutrition     # nutrition specialist\n```\n\n### What happens when you run a specialist\n\n```\n→ Fetches the agent manifest from the tap registry\n→ Installs required binaries automatically (skips if already present)\n→ Prompts once for any credentials, saves permanently\n→ Spins up the right MCP servers for this domain\n→ Loads specialist model config, system prompt, tool permissions\n→ Ready in ~5 seconds, not 45 minutes\n```\n\nThis is **packaged expertise** — not a prompt file, not a skill injection. The full stack, configured by the community, ready to run.\n\n### Specialists grow at runtime\n\nEvery agent has built-in power tools that let it acquire new capabilities and spawn sub-agents mid-session, without restart:\n\n| Tool | What it does |\n|---|---|\n| `tap` | Delegate to any specialist role from the tap registry. Foreground for an inline reply or background for long tasks. |\n| `mcp` | Enable or disable MCP servers on the fly. Agent picks the server it needs and registers it mid-conversation. |\n| `agent` | Spawn a specialist sub-agent for a sub-task. Sub-agent runs, returns, parent continues. |\n\n```\nUser: \"Cross-reference our Postgres metrics with the deployment log\"\n\nAgent:\n  → mcp.enable(postgres-mcp)        # auto-detected need, no user prompt\n  → agent.spawn(log_reader)         # delegates log parsing\n  → results merge mid-session\n  → mcp.disable(postgres-mcp)       # cleans up\n  → presents the analysis\n```\n\nMost 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.\n\n### Add your own taps\n\n```bash\noctomind tap yourteam/tap                 # clones github.com/yourteam/octomind-tap\noctomind tap yourteam/internal ~/path     # local tap for private agents\n\noctomind run finance:analyst              # available immediately\noctomind run security:owasp\n```\n\nEach tap is a Git repo. Each agent is one TOML file. Pull requests are contributions.\n\n\u003e 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)\n\n---\n\n## Pillar 2 — Sessions That Stay Sharp at Hour 4\n\nEvery coding agent degrades after a few hours. Context fills. Decisions get truncated. The agent forgets why it started.\n\nOctomind's adaptive compaction engine runs automatically:\n\n- **Cache-aware** — calculates if compaction is worth it *before* paying for it. Never breaks the prompt-cache hit by accident.\n- **Pressure-tiered** — compacts more aggressively as context grows.\n- **Structurally preserving** — keeps decisions, file references, errors, dependencies; drops noise.\n- **Plan-aware and free-form-aware** — works whether you use the `plan` tool or have a free-form chat.\n- **Fully automatic** — you never think about it.\n\nThe second-order benefit: smaller context means **fewer tokens, faster responses, lower cost** every turn after compaction fires. The three pillars compound.\n\n\u003e Work on a hard problem for 4 hours. The agent still knows what it decided in hour one.\n\n---\n\n## Pillar 3 — Cost as a Control Plane\n\nPick 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.\n\n```toml\n# Per-role model selection — pay Opus only where it's worth it\n[[roles]]\nname = \"researcher\"\nmodel = \"openrouter:google/gemini-2.5-flash\"   # cheap broad context\n\n[[roles]]\nname = \"reviewer\"\nmodel = \"anthropic:claude-opus-4-7\"            # precision where it counts\n\n# Hard spending limits — enforced, not advisory\nmax_request_spending_threshold = 0.50    # USD per request\nmax_session_spending_threshold = 5.00    # USD per session\n```\n\n- Per-role and per-layer model selection across many providers via [octolib](https://github.com/muvon/octolib) — different roles can run on different vendors.\n- Mid-session model swap with `/model anthropic:claude-haiku-4-5`.\n- Real-time cost tracking per request and per session.\n- Cache-aware token accounting (`cache_read_tokens`, `cache_write_tokens` separated from input/output).\n- Hard spending thresholds with enforcement — agent stops, falls back, or warns before the bill.\n\n\u003e Cursor users get $7,000 surprise bills. Octomind agents trip a budget and stop, fall back, or warn — before the bill, not after.\n\n---\n\n## Pillar 4 — Guardrails: Policy as Code, Not Approval Clicks\n\nOther 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.\n\nOctomind 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.\n\n```toml\n# Pre-call deny — block a class of calls before they execute\n[[guard]]\nmatch   = \"shell(command=^rm\\\\s+-rf?)\"\nmessage = \"rm -rf blocked.\"\n\n# Conditional rule — only fires after the agent ran git status this session\n[[guard]]\nmatch   = \"shell(command=git push)\"\nwhen    = [\"+shell(command=git status)\"]\nmessage = \"Review changes before pushing.\"\n\n# Post-result hook — non-zero exit injects feedback into the agent's inbox\n[[hook]]\nmatch  = \"text_editor(path=src/.*\\\\.rs)\"\non     = \"success\"\nscript = \".agents/check-clippy.sh\"\n\n# Post-turn validator — fires only over the call slice since it last ran\n[[validator]]\nname   = \"tests-pass\"\nroles  = [\"developer\"]\nscript = \".agents/run-tests.sh\"\n```\n\n- **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.\n- **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*.\n- **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 `\u003cvalidation\u003e` blocks the agent reads on its next turn. **This is what replaces \"approve this change?\" prompts in autonomous loops.**\n\nThe DSL is richer than competitor lifecycle hooks: capability+arg-regex+history+role+result-regex in one declarative file. No code to compile, no plugin to install. **Designed for full automation: fits CI, daemons, scheduled runs, ACP sub-agents.**\n\n\u003e The world is going autonomous. The choice isn't \"ask vs auto\" — it's \"auto with deterministic policy\" vs \"auto with hope.\" Octomind ships the former.\n\n---\n\n## Pillar 5 — Intent-Driven Context: Skills Activate on What You Mean\n\nEvery other agent CLI loads every tool, every skill, every instruction pack into context up front. The model sees fifty tool definitions and a wall of system prompts before the user types a single character. **Token bills follow. Cache misses follow. Confused tool selection follows.**\n\nOctomind inverts this. Skills and capabilities sit dormant until the user's intent matches them — then they activate, inject their content, and stay only as long as they're relevant. **Context is a function of what the user is actually trying to do.**\n\n### How activation works (no keyword guessing)\n\nSkills describe what they're for. The runtime matches your prompt against those descriptions and only loads the skills that fit:\n\n- **Meaning, not keywords.** A dedicated embedding model — trained on activation traffic — scores how well your request matches each skill. \"Help me refactor this auth flow\" and \"the login is broken\" both find the same skill; \"what's the weather\" finds none.\n- **Hand-authored rules where precision matters.** Skill authors can pin activation to file names, file contents, or exact phrases when they know better than a similarity score.\n- **Abstain on near-ties.** When two skills score close, **neither fires.** Better to load nothing than the wrong thing.\n- **Calibrated to skip, not guess.** Wrong activations bloat context and waste tokens. The system defaults to silence when in doubt.\n\n### Why this matters\n\n```\nOther agent CLIs:                       Octomind:\n─────────────────────                   ──────────\n1. User starts session                  1. User starts session\n2. Load 50 tools into context           2. Load 5 core tools into context\n3. Load 30 skills into system prompt    3. Skills sit dormant\n4. User types one sentence              4. User types one sentence\n5. Model picks tool from a wall         5. Embed model scores → 1 skill matches\n                                           → skill content injected\n                                           → 6 tools in context, not 80\n                                        6. Skill goes silent again when no longer relevant\n```\n\n**Smaller context = faster first token, lower cost per turn, fewer wrong tool calls.** The same prompt that costs $0.12 in a preloaded-everything CLI costs $0.03 here.\n\n### What this combines with\n\n- **`mcp.enable` mid-session.** Even when a skill activates, the underlying MCP server only spins up if the skill actually calls it. Inactive servers = zero token cost.\n- **Compression interplay (Pillar 2).** A deactivated skill is dropped during compaction — its content is recoverable on next activation, not pinned forever.\n- **Guardrails (Pillar 4).** A guard can require `has = [\"filesystem-read\"]` and only fire when that capability is currently loaded. Policy and activation share the same capability namespace.\n\n\u003e Most \"agentic\" CLIs pretend context is free. Octomind treats it as the scarcest resource in the system — and only spends it on what the user actually meant.\n\n---\n\n## Quick Start\n\n```bash\n# Install (macOS \u0026 Linux)\ncurl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash\n\n# One API key gets you many providers\nexport OPENROUTER_API_KEY=\"your_key\"\n\n# Start with a specialist — no setup required\noctomind run developer\n```\n\n```\noctomind v0.29.0 · role: developer · model: openrouter:...\n\u003e _\n```\n\nYou're in an interactive session with a specialist that can read your code, run commands, edit files, and grow capabilities as needed.\n\n---\n\n## How It Works\n\n### Built-in MCP tools (every agent has these)\n\n| Tool | Purpose |\n|---|---|\n| `plan` | Structured multi-step task tracking |\n| `mcp` | Enable/disable MCP servers at runtime |\n| `agent` | Spawn specialist sub-agents mid-session |\n| `schedule` | Inject messages at future times |\n| `skill` | Inject reusable instruction packs from taps |\n| `tap` | Delegate to any specialist role from a tap registry |\n\n### Filesystem tools (via [octofs](https://github.com/muvon/octofs))\n\n`view`, `text_editor`, `batch_edit`, `shell`, `semantic_search`, `structural_search`, `workdir` — file operations come from the companion octofs MCP server, included by default in tap formulas that need them.\n\n### Brain (via [octobrain](https://github.com/muvon/octobrain))\n\n`memorize`, `remember`, `forget`, `knowledge`, `relate`, `memory_graph` — long-term memory, knowledge indexing, and relationship graphs. The companion octobrain MCP server is included by default in taps that need persistent context across sessions.\n\n### Providers\n\nOctomind supports many providers — OpenRouter, OpenAI, Anthropic, Google, DeepSeek, Amazon Bedrock, Cloudflare, and more — via [octolib](https://github.com/muvon/octolib). New providers added there become available in Octomind automatically. See [Providers \u0026 Models](doc/usage/04-providers.md) for the current list and supported models.\n\nSwitch providers mid-session with `/model anthropic:claude-sonnet-4-6`. Mix providers across roles — cheap model for research, best model for execution. Cost tracked separately per provider.\n\n---\n\n## Power Users — Roles, Workflows, Layers\n\nFor most users, taps are enough. For teams and power users, the configuration system is deep — **all TOML, no code**.\n\n```toml\n# Per-role: independent model, temperature, MCP servers, tools, system prompt\n[[roles]]\nname = \"senior-reviewer\"\nmodel = \"anthropic:claude-opus-4-7\"\ntemperature = 0.2\n[roles.mcp]\nserver_refs = [\"filesystem\", \"github\"]\nallowed_tools = [\"view\", \"ast_grep\", \"create_pr\"]\n\n# Workflows — multi-step, each step its own model and toolset\n[[workflows]]\nname = \"deep_review\"\n[[workflows.steps]]\nname = \"analyze\"\nlayer = \"context_researcher\"     # gemini-flash, broad context\n[[workflows.steps]]\nname = \"critique\"\nlayer = \"senior_reviewer\"        # claude-opus, precision\n\n# Sandbox — lock all writes to current directory\nsandbox = true\n```\n\n- **Roles** — model, temperature, system prompt, MCP servers, tool permissions per role.\n- **Layers** — chained AI sub-agents that run after each response.\n- **Pipelines** — deterministic script-driven pre-processing.\n- **Workflows** — multi-step orchestrated task runners with validation loops.\n\nSee [Configuration Reference](doc/reference/03-config-reference.md) for everything.\n\n---\n\n## Embedders — ACP, WebSocket, Daemon\n\nOctomind isn't just a CLI. It runs in every context an agent needs to live in:\n\n| Mode | Use for |\n|---|---|\n| Interactive CLI | Daily work, any domain |\n| `--format jsonl` pipe | CI/CD pipelines, shell scripts, automation |\n| `--daemon` + `send` | Background agents, continuous monitoring, long-running tasks |\n| WebSocket server | IDE plugins, web dashboards, external integrations |\n| ACP protocol | Multi-agent orchestration, being called by other agents |\n\n```bash\n# ACP — drop into any multi-agent system as a sub-agent\noctomind acp developer:general\n\n# Non-interactive — single message, plain output\noctomind run developer \"Explain the auth module\" --format plain\n\n# Structured JSON output for pipelines\noctomind run developer \"List TODO items\" --schema todos.json --format jsonl\n```\n\nOne binary. Every workflow.\n\n---\n\n## Installation\n\n### One-line install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash\n```\n\nDetects OS and architecture, installs to `~/.local/bin/`. macOS and Linux supported. Single Rust binary, no runtime dependencies.\n\n### Cargo\n\n```bash\ncargo install octomind\n```\n\nRequires Rust 1.95+. See [Building from Source](doc/dev/01-building-from-source.md).\n\n### Build from source\n\n```bash\ngit clone https://github.com/muvon/octomind.git\ncd octomind\ncargo build --release\n```\n\n### API keys\n\n```bash\n# OpenRouter — recommended, access to many providers with one key\nexport OPENROUTER_API_KEY=\"your_key\"\n\n# Or any specific provider\nexport OPENAI_API_KEY=\"your_key\"\nexport ANTHROPIC_API_KEY=\"your_key\"\nexport DEEPSEEK_API_KEY=\"your_key\"\n```\n\nAdd to `~/.bashrc` or `~/.zshrc` for persistence.\n\n### Verify\n\n```bash\noctomind --version\noctomind config       # generate default config\noctomind run          # start your first session\n```\n\n---\n\n## Configuration\n\nConfig lives at `~/.local/share/octomind/config/config.toml`.\n\n```bash\noctomind config --show          # view current config\noctomind config --validate      # validate config\n```\n\nKey areas:\n\n- **Roles** — model, temperature, system prompt, MCP servers, tool permissions\n- **Workflows** — multi-step AI processing with validation loops\n- **Pipelines** — deterministic script-driven pre-processing\n- **MCP Servers** — external tools and capabilities\n- **Spending Limits** — per-request and per-session thresholds\n\nFull reference: [Configuration Reference](doc/reference/03-config-reference.md).\n\n### Session commands\n\n| Command | Description |\n|---|---|\n| `/help` | Show all commands |\n| `/info` | Token usage and costs |\n| `/model \u003cprovider:model\u003e` | Switch model mid-session |\n| `/effort \u003clevel\u003e` | Set reasoning effort (low/medium/high/xhigh/max) |\n| `/role \u003cname\u003e` | Switch role mid-session |\n| `/session` | Manage saved sessions (sessions auto-save) |\n| `/exit` | Exit session |\n\nFull list: [Session Commands](doc/reference/02-session-commands.md).\n\n---\n\n## Architecture\n\nOne binary. The session is the unit of work. Around it: roles (who's talking), layers and workflows (multi-step orchestration), pipelines (deterministic pre-processing), adaptive compaction (long-session quality), guardrails (deterministic policy), and MCP servers (tools). All of it driven by a single resolved TOML config — no hardcoded behavior, no framework code to edit.\n\nEmbedders pick their surface: interactive CLI, ACP for multi-agent orchestration, WebSocket for IDEs and dashboards, daemon mode for long-running background agents.\n\nSee [Architecture](doc/dev/02-architecture.md) for internals.\n\n---\n\n## Contributing\n\nThe most impactful contribution isn't code — **it's specialist agents.**\n\nEvery domain expert who publishes a specialist makes Octomind useful for an entirely new audience. A cardiologist publishing `doctor:medications`. A tax attorney publishing `lawyer:us`. A security researcher publishing `security:owasp`. One TOML file — and everyone with that problem gets a specialist-grade AI instantly.\n\n- [How to write a tap agent](https://github.com/muvon/octomind-tap)\n- [Open issues](https://github.com/muvon/octomind/issues)\n- [Building from source](doc/dev/01-building-from-source.md)\n\n---\n\n## Documentation\n\n- [Installation \u0026 Setup](doc/usage/01-installation.md)\n- [Quickstart](doc/usage/02-quickstart.md)\n- [Configuration](doc/usage/03-configuration.md)\n- [Providers \u0026 Models](doc/usage/04-providers.md)\n- [Sessions \u0026 Compression](doc/usage/05-sessions.md)\n- [Roles](doc/usage/06-roles.md)\n- [MCP Tools](doc/usage/07-mcp-tools.md)\n- [Workflows](doc/usage/09-workflows.md)\n- [Pipelines](doc/usage/14-pipelines.md)\n- [Learning](doc/usage/13-learning.md)\n- [WebSocket \u0026 ACP](doc/integration/01-websocket-server.md)\n- [CLI Reference](doc/reference/01-cli-reference.md)\n- [Config Reference](doc/reference/03-config-reference.md)\n\nFull index: [doc/README.md](doc/README.md).\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n\n---\n\n**Octomind** by [Muvon](https://muvon.io) | [Website](https://octomind.run) | [Documentation](https://octomind.run/docs/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMuvon%2Foctomind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMuvon%2Foctomind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMuvon%2Foctomind/lists"}