blitz-cli 0.14.0

Developer CLI for Blitz locker-room: spec-driven playbooks, a codebase/huddle ontology graph with an MCP tool, and the composable watcher/trainer/graph containers.

blitz-cli

Developer CLI for the Blitz locker-room: spec-driven playbooks for your coding agent, a local ontology graph of your codebase/huddles/features (served to agents over MCP), and the composable containers that keep it fresh.

pip install blitz-cli

The core CLI is stdlib plus rich. Two optional extras carry heavier deps only when you need them: blitz-cli[locker-room] (the MCP server) and blitz-cli[train] (the QLoRA trainer).

Top-level commands: init, model, locker-room.

Playbooks: spec-driven development commands

blitz init installs a set of spec-driven-development slash-commands into a repo, rendered for whichever agent you use (Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenCode), plus a shared .blitz/ working area.

blitz init                 # auto-detect the agent(s) in this repo
blitz init --agent claude  # or target one explicitly
blitz init --all           # install for every supported agent

The commands are specify, plan, tasks, implement, playbook, clarify, and analyze. Run at a folder of repos, init installs into each repo it finds (recursing through non-git folders) and adds a workspace-level /huddle command for coordinating a feature across repos. Use --ignore PATH to skip a repo and --root to force a single install.

Model execute: run a tasks.md with a local model

Experimental. This is under active development, its interface and output may change without notice, and it is not recommended for production use.

blitz model execute drives a local model (served by Ollama) through a playbook-generated tasks.md, one task at a time. The model only proposes actions (full-file writes and shell commands); the driver applies them, runs each phase's machine-runnable verification, retries with the failure fed back (default 2), snapshots every file before overwriting it, and checks off - [x] in the tasks.md. A task that keeps failing stops the run so the state stays inspectable. Per-attempt model replies, snapshots, and exact token accounting (usage.json, per task and total) land under .blitz/execute/runs/<timestamp>/.

blitz model execute                                   # auto-detect the open specs/*/tasks.md
blitz model execute specs/001-my-feature/tasks.md     # or name it
blitz model execute --model qwen2.5-14b-28k --start-at T005

Tasks whose text says "optional manual" are skipped and left unchecked. The Ollama endpoint comes from --ollama-url or OLLAMA_HOST; the model from --model or BLITZ_EXECUTE_MODEL.

Collection over the ingest endpoint

blitz model execute --collect records every generation attempt as DPO training data. By default it writes straight to the activity SQLite database (ACTIVITY_DB_PATH, else data/activity.db). With COLLECT_ENDPOINT set, the same writes go over HTTP JSON to a collect ingest server instead, so the collector needs no filesystem access to the database:

# on the locker-room node (default port 1739, binds all interfaces, no auth):
ACTIVITY_DB_PATH=data/activity.db blitz locker-room collect-serve

# on the collecting machine:
COLLECT_ENDPOINT=http://locker-room-host:1739 blitz model execute --collect

Each attempt is acknowledged by the endpoint before the next model call starts. If the endpoint is unreachable when the run starts, the run fails fast, same as an unwritable database. If it fails mid-run, the run keeps going: undelivered payloads are buffered to collect-buffer.jsonl in the run directory and the final output names the file. Deliver them later with

blitz model collect flush .blitz/execute/runs/<stamp>/collect-buffer.jsonl

Flushing is idempotent (the server deduplicates attempts on their run/task/sample/attempt identity), so re-running a flush, or flushing rows the server already received, never duplicates data. pairs extract/export/stats read the database directly, unaffected by the endpoint.

Locker-room: ontology graph, watcher, trainer, MCP

The locker-room is a context node: a set of containers that ingest, build, and serve an ontology of your codebase to agents (on your machine, a VPN, or a team host). blitz locker-room init scaffolds a docker-compose.yml that pulls the prebuilt node images (from sparepartslabs/blitz-locker-room) for four roles sharing ./data:

• watch: ingests your coding agent's session transcripts into a corpus.
• graph: rebuilds an ontology of your playbook-enabled repos, huddles, features, and their code lineage into data/ontology.db on a loop.
• mcp: serves that ontology to agents over MCP (SSE) and a browser graph view.
• train: on-demand QLoRA trainer (needs a GPU).

blitz locker-room init          # write ./locker-room/docker-compose.yml
cd locker-room
blitz locker-room up            # start watch + graph + mcp
blitz locker-room logs

The CLI is just these static commands (init, and the up/down/logs/pull/ train lifecycle passthroughs). The runtime (ingest, graph build, serving) lives in the node images, not the CLI.

The graph agents can query

The graph engine (a blitz-cli library the node runs) reuses playbook discovery and static code parsing (Python symbols + imports + calls; File nodes for other languages) to build Workspace, Repo, AgentTool, Playbook, Feature (with lifecycle stage), Huddle, File, and Symbol nodes. Each feature's git branch diff links it to the code it touches (Feature -TOUCHES-> File/Symbol), so an agent can walk a spec out to the full lineage of code it implements, and back.

The mcp role serves this: point an agent's MCP config at http://<node>:1738/sse (tools list_repos, get_repo, list_huddles, get_huddle, get_playbooks, get_lineage, impact_of, get_file, get_symbol, neighbors), or open http://<node>:1738/graph in a browser.

Training (optional)

Experimental. This is under active development, its interface and output may change without notice, and it is not recommended for production use.

blitz locker-room train runs an on-demand QLoRA fine-tune of the watcher corpus in the trainer container (needs a GPU); adapters land in ./train-out. Override the base model with BASE_MODEL_HF or blitz locker-room init --base-model.

Activity: replay a coding-agent session

blitz locker-room activity reads your coding agent's own local session transcripts (currently Claude Code's, at ~/.claude/projects) for the current repo and replays each prompt alongside the actions taken to resolve it (tool calls, sub-agents) and the final response:

blitz locker-room activity --list               # sessions for this repo, most recent first
blitz locker-room activity                      # the most recent session's timeline
blitz locker-room activity <session-id-prefix>  # a specific session
blitz locker-room activity --full               # untruncated prompts/responses/tool I/O
blitz locker-room activity --html report.html   # also write a self-contained HTML report

The terminal view is compact by default; --full shows untruncated text. The HTML report includes each action's full tool input/output, collapsed per action. Each turn shows its raw token usage and, where a pre-edit backup exists, a real diff of what an Edit/Write changed. Point at a different transcript root with --sessions-dir. This only reads local session data, no project id or API key.