blitz-cli 0.12.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.

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