octomind manual
documentation
install octomind, configure your agents, and put them to work.
start in three commands
curl -fsSL https://octomind.run/install.sh | bash
octomind login
octomindgetting started
- Install Octomind: Open-Source AI Coding Agent CLI Install Octomind, an open-source AI coding agent for the terminal, sign in to the default OctoHub gateway, and set up shell completions.
- Quickstart: Getting Started with the Octomind CLI Agent Install Octomind, choose where its models come from, and start an interactive session. Then learn the commands you need day-to-day.
- Configuration: Models, Roles, and MCP Config in TOML Configure Octomind's models, roles, tools, and runtime limits in TOML, including file locations, merge order, and overrides.
- AI Providers: Multi-LLM Model Routing and Local Models Choose and authenticate models using provider:model. This guide is for users configuring OctoHub, direct providers, local endpoints, or a CLI-backed model.
- Sessions: Resume and Persist Agent Conversations Start, resume, and inspect Octomind AI agent conversations from the terminal, and keep them persistent across separate runs.
- Roles and Tool Permissions for AI Agents Configure roles to select system prompts, model settings, and tool grants for an AI agent, and to check effective tool permissions.
- MCP Tools Reference: Add MCP Servers to Your CLI Agent Use this reference to add MCP servers to Octomind, an MCP client, and to inspect the tools available to your CLI agent session.
- Context Compression and Context Window Management Configure and inspect context compression, which manages the context window of long-running Octomind sessions with automatic folds and task boundaries.
- Workflows: Multi-Agent and Multi-Step AI Agent Workflows Use AI agent workflows to run repeatable multi-step tasks from local TOML files or installed taps, directly from your terminal.
- Custom Commands, Agents, and Prompt Templates Add custom commands, ACP sub-agents, and prompt templates to Octomind: define them in a TOML file in your config directory, then start a new session.
- Structured Output: JSON Schema and JSONL for LLM Responses Use this guide to consume Octomind session activity as JSONL and to request JSON Schema-shaped model answers in machine-readable form.
- Editor Integration: Neovim, Zed, and JetBrains via ACP Use this guide to connect an ACP-capable editor or client, such as Neovim, Zed, or JetBrains, to Octomind as a coding agent.
- Cross-Session Learning: Agent Memory Across Sessions Use cross-session learning to carry your rules and grounded project knowledge into later Octomind agent sessions and to inspect what it retrieves.
- Supervisor: Agent Completion Verification and Planning The supervisor checks progress and completion, manages plans, and narrows large tool results around your Octomind agent session.
- Agent Skills: Auto-Activating Skills and Validators Use skills to load reusable instructions and supporting resources into an Octomind agent session, with activation rules and optional validators.
- Token Efficiency: Reduce LLM Token Usage and Cost Use this guide to reduce LLM token usage by keeping tool schemas focused with on-demand capabilities and by inspecting the context your session sends.
- Local Tools: Turn Project Scripts into MCP Tools Use local tools to expose project scripts as MCP actions without adding MCP server configuration, covering script headers, inputs, and outputs.
- Guardrails: Safe AI Agent Policies, Hooks, and Validators Use .agents/guardrails.toml to set AI agent guardrails: transform session input, deny matching tool calls, and run feedback scripts.
integration
- WebSocket Server for Remote AI Agent Sessions Use Octomind's WebSocket server to run remote AI agent sessions from web clients, bots, and automation tools over JSON frames.
- ACP Protocol: Run Octomind as an Agent Client Protocol Agent The Agent Client Protocol (ACP) lets Octomind run as a JSON-RPC sub-agent over stdio for editor integration and agent-to-agent delegation.
- Daemon Mode and Webhook Hooks: Run a Background AI Agent Run Octomind as a persistent daemon session that reacts to external events, using octomind send or HTTP webhook hooks to enqueue work.
- Tap System: Share and Install Reusable AI Agents Install and author reusable Octomind agents, skills, capabilities, workflows, and plugins with taps, the shareable agent package system.
reference
- CLI Reference: Octomind Commands, Flags, and Options Launch sessions, configure Octomind, and automate workflows from your shell. This reference covers every command, flag, and argument, hidden ones included.
- Session Commands Reference: In-Session Slash Commands Operate a CLI session or build an ACP/WebSocket client with this reference: every slash command, its arguments and output, and transport differences.
- Configuration Reference: Octomind TOML Config Fields and Defaults Use this reference when editing Octomind’s TOML configuration or diagnosing a load error, with every field and its default.
- Environment Variables Reference Use this reference when configuring credentials, relocating state, or diagnosing startup and script behavior with environment variables.
use cases
- Automated AI Code Review in CI/CD Pipelines Use this guide to add Octomind reviews to a CI pipeline. It covers stdin prompts, structured review results, and a shell gate for pull requests.
- Event-Driven Webhooks: Run an AI Agent on GitHub Events Use this guide to connect external HTTP events, such as GitHub webhooks, to a persistent Octomind session that runs an AI agent.
- Custom AI Development Workflow Use this guide to build a custom development workflow that refines a request, researches the checkout, and implements a fix.
- Web Dashboard Integration: Embed an AI Agent over WebSocket Use this guide to connect a browser dashboard to Octomind's WebSocket server and embed an AI agent in your web frontend.
- Multi-Agent Task Delegation with Sub-Agents Use this guide to delegate development tasks to local, tap-provided, or runtime-created sub-agents from a coordinating Octomind session.
- Dynamic MCP Servers: Add MCP Servers at Runtime Use the built-in mcp tool to connect and manage MCP tool servers during a live session when you need additional tools mid-task.
- Scheduled AI Agent Tasks and Timed Messages Use the built-in schedule tool or /schedule command for reminders, periodic checks, and follow-up work in a running session.
- Long-Running Development: Resume Named AI Agent Sessions Use named sessions and resume to continue development across multiple sittings, with saved work and controlled context growth.
- Custom Hooks: Webhook Scripts for an AI Agent Use script-backed HTTP listeners to turn external events into messages for a running Octomind session through custom webhook hooks.
- Block destructive commands and check the agent's work Set up sandbox boundaries, command guardrails, and verification so an autonomous agent cannot damage files or skip checks.
- Put spending checkpoints around each task Set request and session spending checkpoints around each task so every agent task has a visible, predictable cost in Octomind.
- Check the result before accepting “done” Set up completion review and executable checks so done means the requested change actually works before you accept the agent's result.
- Apply project conventions without repeating them each session Package project conventions as standing instructions, reusable skills, and executable checks that apply in every relevant session.
- Carry project corrections into the next session Store project corrections as durable memories that automatically guide related work in future Octomind coding agent sessions.
- Let the agent run your project checks correctly Expose project scripts as typed local tools so AI coding agents run the right builds, tests, and release commands in your repository.
- Give your team a reusable release-review specialist Package a release-review specialist agent as a tap that your whole team can install and use consistently across projects.
- Build a source-backed map of an unfamiliar codebase Build a source-backed map of an unfamiliar codebase, from entry points and state ownership to tests and one execution path.
- Keep private code in local model sessions with Ollama Configure local model sessions with Ollama that keep private code on your machine and make any switch to a cloud model explicit.
- Get a second opinion before accepting a risky change Run independent model reviews in parallel and combine them into one comparison that keeps disagreements visible before a risky change.
- Split a broad research question into focused investigations Build a research workflow that plans focused investigations, runs them in parallel, and synthesizes an evidence-backed report.
- Keep fixing a change until it passes review Build a finite implementation, independent review, and correction loop that keeps working until the change passes review.
- Turn Git history into reviewable release notes Create a repeatable command that turns Git history into reviewable release notes with commit references and structured output.
- Calibrated checks with the evaluation model Ask a calibrated yes/no about the agent's own work from the shell, a guardrail validator, or a pipe, and act on the probability instead of parsing prose.
development
- Building Octomind from Source (Rust) Build Octomind from source in Rust and prepare the local checks used when contributing changes, including platform-specific builds.
- Architecture of the Octomind AI Agent Runtime Use this contributor guide to trace a request from CLI configuration through sessions, MCP tools, and supervision in the Octomind runtime.
- MCP Server Development: Build a Built-in MCP Server in Rust Add a built-in MCP server in Rust when you are extending Octomind itself, from tool definitions and routing to verification.
- Learning Benchmark: Retrieval and Consolidation Contracts Use these live contract benchmarks when changing learning retrieval or consolidation in Octomind's cross-session memory feature.
troubleshooting
- Common Issues and Troubleshooting Use these troubleshooting checks when Octomind installation, authentication, configuration, MCP tools, or sessions fail to work as expected.
- Migration Guide: Upgrade Octomind and Its Config Use this guide when upgrading an existing Octomind installation or porting a hand-written config to the current config schema, version 12.