Documentation

Use Case: Automated Code Review in CI/CD

Run Octomind as part of your CI/CD pipeline to automatically review pull requests, check for security issues, or enforce coding standards.

Use Case: Event-Driven Agent with Webhooks

Run Octomind as a persistent daemon that reacts to external events -- GitHub pushes, Slack messages, monitoring alerts.

Use Case: Custom Development Workflow

Build a multi-stage AI pipeline that refines, researches, and validates a task before another agent executes the fix.

Use Case: Web Dashboard with AI Assistant

Embed Octomind into a web application as a real-time AI coding assistant using the WebSocket server.

Use Case: Multi-Agent Task Delegation

Split complex tasks across specialized AI agents that work independently and report back to a coordinator.

Use Case: AI Self-Configuring MCP Servers at Runtime

Let the AI discover what tools it needs and connect new MCP servers on the fly -- no config changes, no restarts.

Use Case: Scheduled Tasks and Timed Automation

Use the built-in schedule tool to have the AI perform actions at specific times during a session -- reminders, periodic checks, timed workflows.

Use Case: Long-Running Development with Session Resume

Use named sessions and resume to work on complex tasks across multiple sittings without losing context.

Use Case: Custom Hooks -- Build Any Integration in Any Language

Hooks are HTTP listeners backed by scripts you write in any language. You have full control: parse any payload, filter events, transform data, and…

CLI Reference

Complete reference for all octomind CLI commands and flags.

Session Commands Reference

All interactive session commands. Type the command at the prompt. There are 25 distinct commands; the autocomplete list also includes the aliases…

Configuration Reference

Complete field-by-field reference for ~/.local/share/octomind/config/config.toml.

Environment Variables Reference

WebSocket Server

Octomind provides a WebSocket server for remote AI sessions, enabling programmatic access from web clients, bots, and automation tools.

ACP Protocol

The Agent Client Protocol (ACP) enables Octomind to run as a sub-agent over stdio, communicating via JSON-RPC. This is used for editor integration…

Daemon Mode and Webhook Hooks

Run Octomind as a persistent background session that reacts to external events.

Tap System

Taps are Homebrew-style registries for distributing Octomind agents, skills, and capabilities.

Installation

Quickstart

Get from zero to a productive AI session in 5 minutes.

Configuration

Octomind uses TOML configuration files stored in a platform-specific data directory.

AI Providers

Octomind talks to language models through a unified interface implemented in octolib. octolib wires 20 network providers plus a special cli…

Sessions

All interaction with Octomind happens through sessions. A session is a conversation with context, tool access, and cost tracking.

Roles and Permissions

Roles control what the AI can do in a session: which tools are available, what system prompt is used, and how the AI behaves.

MCP Tools Reference

Octomind uses the Model Context Protocol (MCP) to provide AI models with external tools. This is the single reference for all built-in tools.

Context Compression

Octomind automatically manages conversation context size through intelligent compression. This is the single reference for the compression system.

Workflows

octomind workflow <file.toml> is an external orchestrator that chains multiple octomind run invocations into a multi-step process. Each step is an…

Commands, Layers, Agents, and Prompts

Octomind provides four mechanisms for extending AI capabilities beyond the base session:

Structured Output

Octomind can emit its session activity as machine-readable JSON instead of human-formatted terminal text. This is what you use for automation, CI/CD…

Editor Integration

Octomind integrates with code editors via the ACP (Agent Client Protocol), providing AI assistance directly in your IDE.

Cross-Session Learning

Octomind can extract and reuse lessons across sessions — mistakes corrected, patterns that worked, user preferences — so the same issues aren't…

Supervisor

The supervisor is an out-of-band control plane that runs beside the agent loop — never in your transcript. It watches each turn, keeps the agent on…

Skills

Skills are reusable instruction packs that inject domain knowledge into AI sessions on demand. They follow the AgentSkills specification and are…

Token Efficiency: Capabilities, Auto-Activation, and LRU Eviction

Octomind keeps the model's tool surface small on purpose. Every exposed tool eats prompt tokens on every turn, and a wide tool zoo encourages the LLM…

Local Tools

Drop a shebang script into <workdir>/.agents/tools/<name> and it becomes an MCP tool — auto-discovered, role-agnostic, no config required. The…

Guardrails

Per-project policy for tool use and input preprocessing, defined in .agents/guardrails.toml. Four section types cover four phases of the session…

Building from Source

Architecture

Internal architecture overview for Octomind contributors.

MCP Server Development

Guide for adding new built-in MCP servers to Octomind.

Common Issues

Migration Guide

> Read this first: every structural change in this guide is manual. octomind config --upgrade only bumps the config schema version field (the current…

Octomind Documentation

Octomind is a session-first AI development assistant with built-in MCP tools and multi-provider support.