# Bambam — agent-first Kanban (CLI + MCP)

**Pebbles** are the work items on the board (also called **cards** in the API, CLI `bambam card …`, and SQLite `cards` table). Each has **title**, **description**, **comments**, and **status**:

`requested` → `code_creation` (Code Creation) → `testing` → `validation` → `complete`

**Agent policy:** implementers advance **requested** → **code_creation** → **testing**. **Testing** agents do **not** apply code fixes: they add findings and limited recommendations as comments, then move the pebble to **`requested`** when more work is needed; if fully passing, they move it to **`validation`** (no `--hil` required). Moving to **`complete`** requires a human operator: `--hil` on the CLI, `hil=true` on MCP tools, or `BAMBAM_HIL=1`. Moving to **`validation`** from any status **other than** **testing** also requires HIL (human skip-QA / rescue).

**Context feedback:** when you **move** a pebble, you can log how useful Bambam’s guidance was for the step you just finished: `context_helpfulness` **1–5** (5 = enough context, 1 = lots of extra file reads/searches) plus optional `extra_lookups` and `feedback_note`. CLI: `bambam card move ID --status … --context-helpfulness 4 --extra-lookups 2`. MCP: `bambam_card_move` with the same fields (`context_helpfulness: 0` skips logging). `bambam advise` / MCP `bambam_agent_instruction` include the rating scale and recent feedback history.

**Assignment:** each pebble has `assigned_agent_id` (empty = unclaimed). **Claim is not allowed while the pebble is in `requested`** (backlog): **move** to **`code_creation`** first, then `bambam card claim ID --agent-id my-agent`. Another agent’s claim fails until you `release` or **move** the pebble (any status change clears the assignee). Use `--agent-id` on `comment`, `update`, and `move` (or set `BAMBAM_AGENT_ID`) when the pebble is assigned so only that agent can mutate it. MCP: `bambam_card_claim`, `bambam_card_release`, and `acting_agent_id` on comment/update/move. Human-oriented moves (`--hil` / `BAMBAM_HIL=1` when required, or explicit `--hil`) bypass assignee checks as documented in code.

**Blocked pebbles:** if work pauses but the agent did not crash, mark the pebble **blocked** with a required hint: `bambam card block ID --hint "…" --agent-id my-agent` (or MCP `bambam_card_block`). This **releases assignment**; **claim** and normal **move** are disallowed until `bambam card unblock` / `bambam_card_unblock` (same blocker agent, or `--hil` / `hil=true`). A **HIL-style move** (explicit `--hil` / `BAMBAM_HIL=1` when the transition requires HIL) clears blocked and updates status so humans can rescue stuck boards.

## Quick start (development)

```bash
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[mcp,tui]"
python -m bambam init
python -m bambam card create --title "Example"
python -m bambam advise
```

Database: `.bambam/kanban.sqlite` under the current working directory, or override with `BAMBAM_DB=/path/to/file.sqlite`.

**Human project index:** `bambam init` records the project when you use the usual layout `cwd/.bambam/kanban.sqlite` (not when `BAMBAM_DB` or `--db` points elsewhere—use `project add` for those). Registry file: `~/.config/bambam/projects.sqlite` (override with `BAMBAM_CONFIG_DIR`). Commands:

```bash
bambam project list
bambam project add /path/to/existing/repo   # register a board you created earlier
bambam project forget /path/to/repo         # remove registry entry only (keeps SQLite file)
```

Repo entrypoint: `bambam.py` (same as `python -m bambam`).

## Install to `~/.local/bin/bambam`

```bash
./install.sh              # default prefix ~/.local
./install.sh /opt/custom  # custom prefix → /opt/custom/bin/bambam
```

This creates a dedicated venv at `{prefix}/libexec/bambam/venv` so the CLI works from any directory.

## MCP (Cursor / Claude Desktop)

Run the stdio server:

```bash
python -m bambam mcp
```

Example Cursor MCP config:

```json
{
  "mcpServers": {
    "bambam": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "bambam", "mcp"],
      "env": {
        "BAMBAM_PROJECT_ROOT": "/absolute/path/to/repo"
      }
    }
  }
}
```

Omit `env` if the host starts the server with the workspace as **cwd** (then `.bambam/kanban.sqlite` is resolved there). Tools intentionally **do not** take `project_root` / `db_path` arguments — some clients serialize those badly; use **`BAMBAM_PROJECT_ROOT`** or **`BAMBAM_DB`** instead. `bambam_card_list` uses `status` with default `"all"` (not nullable) so clients don’t emit broken JSON for optional filters.

See [docs/cursor-mcp.md](docs/cursor-mcp.md) for Cursor JSON errors and troubleshooting.

Tools include `bambam_agent_instruction` (markdown guidance keyed off pebble status) plus CRUD/move helpers (`bambam_card_*`).

## TUI (live board)

Watch a **single** project’s SQLite board update in real time (polls the DB on an interval). The UI is **five Kanban columns** (requested → complete); pebbles move between columns as their status changes.

```bash
pip install -e ".[tui]"
bambam tui --project /path/to/repo
# optional: bambam tui --project . --interval 0.5
```

`[` / `]` move focus between columns; **↑**/**↓** move within a column; **q** quit; **r** refresh. Requires `project/.bambam/kanban.sqlite`.

## Web GUI (read-only)

Five-column Kanban in the browser; **view only** (stdlib HTTP server + static HTML/JS). Refreshes from SQLite every ~2.5s.

```bash
bambam gui                          # board for current directory / BAMBAM_DB
bambam gui --project /path/to/repo  # project/.bambam/kanban.sqlite
bambam gui --port 8742 --no-open    # fixed port; don’t launch browser
bambam gui --host 0.0.0.0 --port 8742   # LAN (use with care)
```

Default `--port 0` picks a free port and prints the URL.

## Autonomous agent loop (no IDE hooks)

To run coding agents **repeatedly** against the board without wiring MCP into each harness, use **`AGENTS.md`** plus **`scripts/bambam-agent-loop.sh`**:

- **`AGENTS.md`** — policy: how to pick pebbles, claim, comment, move, block, and respect HIL rules using the **CLI** (or MCP if available).
- **`scripts/README.md`** — runner env vars, examples, and security note for **`BAMBAM_AGENT_CMD`**.

Quick example (after `bambam` is on your `PATH`):

```bash
export BAMBAM_AGENT_ID="loop-$(hostname)-$$"
export BAMBAM_AGENT_CMD='echo "Replace with your agent CLI; pebble $BAMBAM_NEXT_PEBBLE_ID ($BAMBAM_NEXT_PEBBLE_STATUS)"'
./scripts/bambam-agent-loop.sh /path/to/repo
```

Copy **`AGENTS.md`** and the **`scripts/`** folder into any Bambam project you want to drive this way.

## Advisory check (Claude Code)

`projects/bambam_agent_validation/` seeds a board and runs `claude -p` to validate that `bambam advise` matches agent/HIL expectations. See that folder’s README.

## Demo project

See `projects/pacman/` — TypeScript + HTML canvas game; `npm install && npm run build`, then serve the folder (ES modules):

```bash
cd projects/pacman && python -m http.server 8765
```

Open `http://127.0.0.1:8765/`.