Skip to content

local-development.md

Latest commit

 

History

History
364 lines (258 loc) · 8.58 KB

local-development.md

File metadata and controls

364 lines (258 loc) · 8.58 KB

Local Development Setup

📖 See Also:

This guide covers first-time setup for developing Marcus itself locally. If you just want to use Marcus to run agents on a project, follow the Quickstart instead.

Choose Your Path

Marcus runs locally in all paths. The difference is which kanban backend you use during development.

Path When to choose External dependencies
A: SQLite (default) Default. Recommended for nearly all development. None.
B: Planka When you specifically need to test the drag-and-drop kanban UI or the Planka integration. Docker (Planka + Postgres + kanban-mcp).

Path A is what you want unless you're touching the Planka integration code or kanban-mcp itself.

Path A: SQLite (default, zero external dependencies)

1. Clone Marcus

cd ~/projects   # or wherever you keep code
git clone https://github.com/lwgray/marcus.git
cd marcus

2. Install in editable mode

pip install -e .
pip install -r requirements-dev.txt

Requires Python 3.11+.

3. Configure your LLM provider

cp .env.example .env
cp config_marcus.example.json config_marcus.json
echo "CLAUDE_API_KEY=sk-ant-..." >> .env

config_marcus.example.json already defaults to SQLite — no kanban edits needed.

4. Start Marcus

./marcus start
./marcus status
./marcus logs --tail 50

Marcus runs at http://localhost:4298/mcp. SQLite database is created automatically at ./data/kanban.db on first project creation.

5. Iterate

# Edit Marcus code
./marcus stop
./marcus start

That's the whole loop. Tests:

pytest tests/unit -m unit

Inspect the board from the terminal:

sqlite3 data/kanban.db "SELECT name, status, assigned_to FROM tasks"

Path B: Planka (drag-and-drop kanban UI)

Use this path when you're working on the Planka integration itself, the kanban-mcp client, or you want a visual UI during development.

Docker is infrastructure only — runs Planka + Postgres + kanban-mcp. Marcus itself still runs locally via ./marcus start.

1. Clone marcus and kanban-mcp as siblings

cd ~/projects
git clone https://github.com/lwgray/marcus.git
git clone https://github.com/lwgray/kanban-mcp.git

# Structure:
# ~/projects/
# ├── marcus/
# └── kanban-mcp/

Marcus auto-detects kanban-mcp as a sibling. If you can't use sibling directories, set KANBAN_MCP_PATH:

export KANBAN_MCP_PATH="/custom/path/to/kanban-mcp/dist/index.js"

2. Build kanban-mcp

cd ~/projects/kanban-mcp
npm install
npm run build

This builds kanban-mcp only. Postgres and Planka run via Docker.

3. Install Marcus and configure for Planka

cd ~/projects/marcus
pip install -e .
pip install -r requirements-dev.txt
cp .env.example .env
cp config_marcus.example.json config_marcus.json
echo "CLAUDE_API_KEY=sk-ant-..." >> .env

Edit config_marcus.json:

{
  "kanban": {
    "provider": "planka",
    "planka_base_url": "http://localhost:3333",
    "planka_email": "demo@demo.demo",
    "planka_password": "demo"  // pragma: allowlist secret
  }
}

4. Start Planka in Docker

cd ~/projects/marcus
docker compose up -d postgres planka
# Wait ~10–15 seconds, then open http://localhost:3333
# Login: demo@demo.demo / demo
# Create at least one list (Backlog / In Progress / Done) before creating projects

5. Start Marcus locally

./marcus start
./marcus status

Iterate on kanban-mcp

cd ~/projects/kanban-mcp
# Edit operations/projects.ts (or wherever)
npm run build

cd ~/projects/marcus
./marcus stop && ./marcus start

Stop everything

./marcus stop
docker compose down                # stops Planka + Postgres
docker compose down -v             # also wipes Planka data

Auto-Detection (technical details)

Marcus detects environment + kanban-mcp path automatically. Useful when something breaks.

Environment detection

Marcus checks if it's running inside Docker by inspecting:

  • /.dockerenv file presence
  • /proc/1/cgroup for docker or containerd
  • Hostname pattern (12-char hex string)

kanban-mcp path resolution (Planka path only)

Priority order:

  1. KANBAN_MCP_PATH environment variable (supports ~ expansion)
  2. Docker-internal path: /app/kanban-mcp/dist/index.js
  3. Sibling directory: ../kanban-mcp/dist/index.js relative to Marcus root

Planka URL auto-adjustment

The same config_marcus.json works inside Docker and locally:

Config value Inside Docker Running locally
http://planka:1337 http://planka:1337 http://localhost:3333
http://planka unchanged http://localhost:3333
http://localhost:3333 unchanged unchanged
Custom IP/domain unchanged unchanged

Troubleshooting

./marcus start fails — Connection refused or port in use

./marcus status                       # is Marcus already running?
./marcus stop
./marcus start --port 5000            # use a different port

Module not found

pip install -e .
pip install -r requirements-dev.txt
python --version                      # must be 3.11+

SQLite path errors

Confirm the directory exists and is writable:

ls -la ./data
mkdir -p ./data && chmod u+w ./data

Planka path: Could not find kanban-mcp

ls ~/projects/                                       # marcus/ and kanban-mcp/ both present?
ls ~/projects/kanban-mcp/dist/index.js               # built?
cd ~/projects/kanban-mcp && npm run build            # if not, build
# Or set explicit path:
export KANBAN_MCP_PATH="/custom/path/kanban-mcp/dist/index.js"

Planka path: Failed to create any tasks / find_target_list failed

Open http://localhost:3333 and create at least one list (Backlog / In Progress / Done) before creating projects.

Configuration issues

See Configuration Reference for the full schema.

Best Practices

1. Use the CLI

# Use these
./marcus start
./marcus stop
./marcus status
./marcus logs --tail 50

# Avoid
python -m src.marcus_mcp.server
kill -9 $(ps aux | grep marcus)

2. Default to SQLite during development

Faster restarts, no Docker overhead, no external dependencies. Switch to Planka only when testing kanban-mcp or Planka integration.

3. Keep Planka in Docker (when you do use it)

Stable, persistent data, easy to reset (docker compose down -v). Don't try to install Planka natively.

4. Run tests before commits

pytest -m unit               # fast unit tests (always run these)
pytest tests/integration     # if your change touches integration paths

5. Use sibling directories for Planka path

~/projects/
├── marcus/
└── kanban-mcp/

No environment variable needed.

Common Scenarios

Scenario 1 — Quick bug fix in Marcus (SQLite)

# Edit src/integrations/kanban_factory.py (or wherever)
./marcus stop && ./marcus start
pytest tests/unit -m unit -k kanban_factory
git commit -am "fix: short reason"

Scenario 2 — Touching the Planka integration

cd ~/projects/marcus
docker compose up -d postgres planka
# Edit code that uses the Planka client
./marcus stop && ./marcus start
# Verify against Planka UI at http://localhost:3333

Scenario 3 — Touching kanban-mcp itself

cd ~/projects/kanban-mcp
# Edit operations/*.ts
npm run build

cd ~/projects/marcus
./marcus stop && ./marcus start
# Test, commit both repos

Summary

# SQLite (default, recommended)
git clone https://github.com/lwgray/marcus.git
cd marcus && pip install -e . && pip install -r requirements-dev.txt
cp .env.example .env && cp config_marcus.example.json config_marcus.json
echo "CLAUDE_API_KEY=sk-ant-..." >> .env
./marcus start

# Planka (only if you need the UI or are touching kanban-mcp)
# (clone kanban-mcp as a sibling, npm run build,
#  docker compose up -d postgres planka,
#  edit config_marcus.json to provider=planka,
#  ./marcus start)

Key commands:

  • ./marcus start — start Marcus
  • ./marcus stop — stop Marcus
  • ./marcus status — is it running?
  • ./marcus logs --tail 50 — recent logs
  • ./marcus board — terminal view of the kanban board
  • pytest -m unit — unit tests