Metadata-Version: 2.4
Name: marcus-mini
Version: 0.1.0
Summary: Board-mediated multi-agent coordination in ~500 lines of Python
Author-email: Larry Gray <lwgray@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/lwgray/marcus-mini
Project-URL: Repository, https://github.com/lwgray/marcus-mini
Project-URL: Issues, https://github.com/lwgray/marcus-mini/issues
Project-URL: Changelog, https://github.com/lwgray/marcus-mini/releases
Keywords: multi-agent,ai,coordination,llm,claude,kanban,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# marcus-mini

**Board-mediated multi-agent coordination in ~500 lines of Python.**

Multiple AI agents work in parallel on a shared task board. They never talk to
each other — they coordinate exclusively through a SQLite kanban board. This
minimal implementation proves that board-mediated coordination works before
adding any production complexity.

---

## Demo

<!-- demo GIF goes here -->

*`mini build "a snake game in Python"` — 3 agents decompose, coordinate, and ship.*

---

## The idea

Most multi-agent frameworks let agents talk to each other directly. `marcus-mini`
does the opposite: agents are **blind to each other** and coordinate only through
a shared board.

Three invariants hold in every run:

1. **Agents self-select work.** The board assigns nothing — agents pull the next
   available task whose dependencies are all complete.
2. **Agents make all implementation decisions.** The board says *what* to build,
   never *how*.
3. **Agents communicate only through the board.** Artifacts and decisions logged
   to a task become context for downstream agents. No direct messages, no shared
   memory outside the board.

This mirrors how distributed teams actually work: a shared backlog, async
handoffs, no mandatory standups.

---

## Quickstart

**Requirements:** Python 3.11+, [Claude Code CLI](https://claude.ai/code), tmux

```bash
pip install marcus-mini
export MINI_API_KEY=sk-ant-...   # your Anthropic key — for decomposition only
mini build "a snake game in Python"
```

> **Why `MINI_API_KEY` and not `ANTHROPIC_API_KEY`?**
> Claude Code agents inherit your shell environment. If `ANTHROPIC_API_KEY` is set,
> agents use it for every API call — even if you have a Claude subscription — and
> you get charged. `MINI_API_KEY` is only read by the decomposer (one call per
> `mini build`). Agents run under your subscription key, not this one.

`mini build` will:
1. Call Claude to decompose the goal into a parallel task DAG
2. Persist all tasks to a local SQLite board
3. Spawn N agents in a tmux session (N = DAG width)
4. Each agent loops: claim task → implement → log artifacts → mark done

Watch the board live:

```bash
mini watch          # live-refreshing kanban
mini status         # per-agent activity
mini bench          # coordination metrics
```

---

## Install

```bash
pip install marcus-mini
```

Or from source:

```bash
git clone https://github.com/lwgray/marcus-mini
cd marcus-mini
pip install -e .
```

---

## Commands

| Command | Description |
|---|---|
| `mini build "goal"` | Decompose goal, spawn agents |
| `mini watch` | Live kanban board (auto-exits on completion) |
| `mini board` | Static kanban snapshot |
| `mini status` | Per-agent activity with staleness warnings |
| `mini bench` | Wall time, utilization, coordination tax |
| `mini dag` | ASCII dependency graph |
| `mini tasks` | Task list with dependency info |
| `mini progress` | Completion percentage |
| `mini time` | Project elapsed time |
| `mini logs` | Tail agent log files |
| `mini projects` | All known projects |
| `mini open` | Print output directory (`cd $(mini open)`) |
| `mini config` | View/set API key env var |

### Key flags

```bash
mini build "goal" --agents 4          # override agent count
mini build "goal" --output-dir ~/myproject
mini watch --interval 5               # refresh every 5s
mini bench --project my-project-1200
```

---

## How it works

```
mini build "snake game"
        │
        ▼
  ┌─────────────┐
  │  decomposer │  Claude call → flat task list + dependency DAG
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │    board    │  SQLite (WAL mode) — the shared environment
  └──────┬──────┘
         │  MCP server exposes 5 tools to each agent
         │
    ┌────┴────┐
    │         │
  agent-1   agent-2   ...   agent-N     (tmux panes)
    │         │
    └─────────┘
    read/write the same board, never each other
```

### Board MCP tools (what agents see)

| Tool | Purpose |
|---|---|
| `request_next_task` | Claim next task whose deps are all DONE |
| `log_artifact` | Store output (API spec, schema, file path) |
| `log_decision` | Record an architectural choice |
| `get_task_context` | Read artifacts from dependency tasks |
| `report_done` | Mark task complete, unblock dependents |

### Task assignment (atomic SQL)

A task is claimable when `status = 'TODO'` and every dependency has
`status = 'DONE'`. The claim runs inside `BEGIN EXCLUSIVE` with a
`json_each()` dependency check — no race conditions, no external lock manager.

### Coordination tax

`mini bench` measures the gap between theoretical and actual parallelism:

```
agent utilization  =  total task work  /  (n_agents × wall_time)
coordination tax   =  1 − utilization
```

A tax of 0 % means every agent was always working. Typical software projects
land at 30–60 % due to the critical path.

---

## Project structure

```
marcus-mini/
├── marcus_mini/
│   ├── board.py          # SQLite board + async API
│   ├── board_server.py   # MCP server (5 tools)
│   ├── cli.py            # mini CLI (Click)
│   ├── decomposer.py     # Claude → task DAG
│   ├── models.py         # Task dataclass
│   ├── monitor.py        # tmux monitor pane
│   └── spawn.py          # tmux agent spawner
├── prompts/
│   └── agent_prompt.md   # agent loop instructions
├── tests/
└── pyproject.toml
```

---

## The evolution: Marcus

`marcus-mini` proves the concept. [Marcus](https://github.com/lwgray/marcus)
is the production system built on the same coordination primitives, adding:

- **Contract-first decomposition** — agents agree on APIs before building,
  enabling coordination beyond software (any domain with specifiable contracts)
- **Full observability** — structured logging, experiment tracking, run comparison
- **Enterprise resilience** — circuit breakers, retry strategies, error framework
- **Multi-provider support** — agent-agnostic board protocol

If `marcus-mini` is the proof, Marcus is the product.

---

## Why not CrewAI / AutoGen / LangGraph?

Those frameworks route messages between agents. `marcus-mini` does not. Agents
in this system are genuinely autonomous — they pull work, they decide how to do
it, they post results. The board is the only channel.

This means: parallelism is structural (DAG-derived), not programmed. You don't
write agent communication logic. You write a goal, and the board handles the rest.

---

## License

MIT
