Marcus AI Documentation#

Board-Mediated Coordination for AI Coding Agents

Marcus is an open-source orchestration server that lets multiple AI agents collaborate on software projects through a shared kanban board — never through chat. Any MCP-compatible agent works: Claude Code, Codex, Gemini CLI, Kimi, AutoGen, LangGraph, or a custom runtime.

🚀 Quickstart

Install Marcus and run your first project in 5 minutes

Quickstart Guide

💡 Core Concepts

Agents, tasks, projects, the board pattern

Core Concepts

📖 API Reference

Auto-generated API and MCP tool reference

API Reference

🏗️ Systems Architecture

Marcus internals — coordination, intelligence, infrastructure

🏗️ Marcus System Architecture Documentation

Why Marcus?#

Board-Mediated Coordination

Agents pull from a shared kanban board — no group chats, no message passing. A modern take on the classical Blackboard pattern (Hayes-Roth, 1985), applied to autonomous LLM agents over MCP. Context is preserved per-task; failures recover from board state; throughput scales with the number of agents.

Bring Your Own Agent

Any MCP-compatible runtime works: Claude Code, Codex, Gemini CLI, Kimi, AutoGen, LangGraph, or a custom agent. Two operating modes: Runner mode (one-command via the /marcus skill in Claude Code) and Attach mode (any agent connects to http://localhost:4298/mcp).

SQLite by Default

Zero-setup kanban — Marcus creates data/kanban.db on first project. No Docker, no Postgres, no external services. Optional providers: Planka (drag-and-drop UI via Docker), GitHub Projects, Linear.

Built-in Observability

Every action is on the board: tasks, dependencies, decisions, artifacts, progress. Pair with Cato for a real-time dashboard, Posidonius for multi-run experiments, and Epictetus for post-run grading.

Quick Example#

The fastest path from idea to working software, using the /marcus skill in Claude Code:

# One-time install
git clone https://github.com/lwgray/marcus.git
cd marcus && pip install -e .
cp -r skills/marcus ~/.claude/skills/marcus

# Configure your LLM provider
cp .env.example .env
cp config_marcus.example.json config_marcus.json
# Edit .env: set CLAUDE_API_KEY=sk-ant-...

# Start Marcus
./marcus start

# Inside Claude Code, in your project directory:
#   /marcus Build a todo app with authentication using 3 agents
#
# The skill registers the MCP server, injects the agent prompt,
# decomposes the project, and spawns 3 agents in tmux panes.

For other runtimes (Codex, Gemini CLI, AutoGen, custom), use Attach mode — connect your agent to http://localhost:4298/mcp and follow the work loop in prompts/Agent_prompt.md. See PROTOCOL.md for the full agent protocol spec.