Marcus is a domain-agnostic AI agent coordination platform. While it excels at turning your ideas into working software, Marcus can coordinate AI agents for any multi-step project - from software development to content creation, research, marketing, and beyond.
Tell Marcus what you want to create in plain English, and it breaks down the work into tasks that multiple AI agents execute autonomously with proper context and coordination.
I was stuck between micromanaging every agent decision or letting agents run wild. I wanted to step away and trust that agents had enough context to build what I wanted. Marcus solves this by being the project manager - you describe once, agents build with proper context and boundaries.
Example 1: Software Development
- You say: "Build a todo app with authentication"
- Marcus: Creates tasks on a project board with dependencies
- Agents: Pull tasks, get context from previous work, build autonomously
- You: Watch progress, intervene only when needed
Example 2: Content Creation
- You say: "Create a 10-minute podcast about chess opening history"
- Marcus: Breaks down into research, outline, script writing, fact-checking, audio production
- Agents: Research specialist → Content strategist → Script writer → Fact checker (in sequence)
- You: Receive completed podcast script with verified sources
Each task is locked to one agent until complete, preventing conflicts. Agents share context through the board, seeing what others built without direct communication.
Marcus accepts any artifact type (code, research, scripts, designs, marketing copy, etc.), making it suitable for:
- 🖥️ Software Development - APIs, frontends, databases
- 🎙️ Content Creation - Podcasts, videos, articles
- 🔬 Research - Literature reviews, data analysis, reports
- 📊 Marketing - Campaigns, copy, social media
- 📚 Education - Course content, lesson plans, assessments
- ...and any other domain requiring multi-agent coordination
- Docker
- Claude Code or another MCP-compatible AI agent
- AI model: Choose one option:
- Free: Local model with Ollama (zero cost, recommended for contributors)
- Paid: Anthropic or OpenAI API key
**Using Planka with Docker Compose**
📖 **See the complete guide:** [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md)
**Quick overview:**
```bash
# 1. Clone and start Planka
git clone https://github.com/lwgray/marcus.git
cd marcus
docker-compose up -d postgres planka
^board_id
# 2. Configure and start Marcus
# Option A: Use default config
cp config_marcus.example.json config_marcus.json
# Edit config with your board IDs and API key
docker-compose up -d marcus
# Option B: Use a specific config (Anthropic, GitHub, etc.)
MARCUS_CONFIG=config_marcus.json.anthropic docker-compose up -d marcus
# Option C: Create .env file for persistent config selection
echo "MARCUS_CONFIG=config_marcus.json.anthropic" > .env
docker-compose up -d marcusFor detailed setup instructions, troubleshooting, and customization options, see DOCKER_QUICKSTART.md.
# For Claude Code:
claude mcp add --transport http marcus http://localhost:4298/mcp
# Marcus provides MCP-compatible endpoints for any agentCopy the Agent System Prompt to your AI agent:
For Claude Code users:
- Copy the contents from prompts/Agent_prompt.md
- Add to your Claude Code configuration as a CLAUDE.md file
What this enables:
- ✅ Autonomous work loop (register → request → work → report → repeat)
- ✅ Context sharing through artifacts and decisions
- ✅ Smart dependency handling with
get_task_context - ✅ Progress reporting at 25%, 50%, 75%, 100%
- ✅ Architectural decision logging for other agents
- ✅ Continuous task execution without waiting for user input
Want to understand or customize the workflow? See the Agent Workflow Guide for detailed explanations of each component.
# Tell your configured agent:
"Create a project for a todo app with Marcus and start working"
# The agent will automatically:
# 1. Register with Marcus
# 2. Create Tasks onto the Planka board from your description
# 3. Request and work on tasks continuously
# 4. Report progress as it goes
# 5. Keep working until all tasks are done- Agent registers itself with Marcus ("Agent claude-1 registered")
- Project created on GitHub with tasks
- Agent continuously pulling tasks and working
- Progress updates: "25% complete", "50% complete", etc.
- Tasks moving through board columns: TODO → IN PROGRESS → DONE
- Context flowing between tasks (API specs → implementation → tests)
# Want multiple agents working in parallel? Three options:
# Option A: Multiple windows (simplest)
# Open a new terminal/Claude window, connect to Marcus, and start another agent
# Both agents will pull different tasks from the same board
# Option B: Claude subagents
# If using Claude, launch subagents with the Task tool
# Each subagent automatically registers and works independently
# Option C: Git worktrees (prevents code conflicts)
git worktree add ../project-agent2 -b agent2-branch
# Each agent works in its own directory/branch
# Merge when readyUnlike proprietary AI coding tools, Marcus is completely open source. Anyone can use it, modify it, and contribute to make it better.
Marcus empowers anyone - even non-programmers - to build real software. Describe what you want in plain English, and watch it get built.
- Other tools: You copy-paste between chats or manage each agent
- Marcus: Agents work independently with shared context through the board
- Result: You can actually step away while software gets built
Built by developers, for developers. We're focused on making software creation accessible to everyone, not maximizing profits.
| Problem | Solution |
|---|---|
| "Connection refused" | Ensure Marcus Docker container is running on port 4298 |
| "No tasks available" | Agent needs to create a project first with create_project |
| "Agent not registered" | Agent must call register_agent before requesting tasks |
| "GitHub auth failed" | Check GitHub token has project permissions |
| "Failed to create any tasks" (Planka) | Board has no lists! Add lists: Backlog, In Progress, Blocked, Done |
| "find_target_list failed" | Open Planka board and create at least one list/column |
📖 Developer guides:
- Local Development Setup - First-time setup
- Development Workflow - Daily workflows
Marcus is open source and we need your help!
- Kanban Provider Integrations - Add Jira, Trello, Linear support
- Documentation - Tutorials, use cases, examples
- Use Case Definitions - Show what Marcus can build
# Fork and clone
git clone https://github.com/YOUR_USERNAME/marcus.git
cd marcus
# Install dev dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/See CONTRIBUTING.md and Local Development Setup for detailed guidelines.
📖 Full reference: Configuration Guide
Marcus supports multiple configuration methods:
Quick config via environment variables:
MARCUS_KANBAN_PROVIDER=github \
MARCUS_KANBAN_GITHUB_TOKEN=ghp_... \
MARCUS_KANBAN_GITHUB_OWNER=your_username \
MARCUS_KANBAN_GITHUB_REPO=your_repo \
MARCUS_AI_ANTHROPIC_API_KEY=sk-ant-... \
docker-compose up -dOr use a config file:
# Use default config
cp config_marcus.example.json config_marcus.json
# Edit with your settings
docker-compose up -d
# Or select a specific config
MARCUS_CONFIG=config_marcus.json.anthropic docker-compose up -dSee the Configuration Reference for all available options.
- Quick Start - Get Marcus running in 5 minutes
- Docker Quickstart - Complete Docker setup guide
- Agent System Prompt - Configure your AI agent
- Core Concepts - Understand Marcus fundamentals
- Local Development Setup - First-time setup and directory structure
- Development Workflow - Daily development workflows (restart, rebuild, test)
- Configuration Reference - All environment variables and config options
- Agent Workflow Guide - How agents interact with Marcus
- Registration - How agents register
- Requesting Tasks - Task assignment
- Getting Context - Task dependencies
- Reporting Progress - Progress tracking
- Handling Blockers - Error recovery
- Complete Documentation - Full Sphinx docs (when published)
- Docker Hub Publishing - Publishing Marcus images
- 💬 Discord: Join our Discord - Real-time help and discussions
- 🗣️ Discussions: GitHub Discussions
- 🐛 Issues: GitHub Issues
- 📖 Docs: Full Documentation
- 🤝 Contributing: Contribution Guide
MIT License - see LICENSE for details
⭐ Star us on GitHub if Marcus helps you build something awesome!