Bambam

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)

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:

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

./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:

python -m bambam mcp

Example Cursor MCP config:

{
  "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 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.

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.

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):

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):

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

Open http://127.0.0.1:8765/.