Metadata-Version: 2.4
Name: blitz-cli
Version: 0.13.0
Summary: 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.
License: MIT
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: rich>=13
Provides-Extra: train
Requires-Dist: accelerate==1.2.1; extra == 'train'
Requires-Dist: datasets==3.2.0; extra == 'train'
Requires-Dist: liger-kernel==0.5.2; extra == 'train'
Requires-Dist: mlflow==2.19.0; extra == 'train'
Requires-Dist: peft==0.14.0; extra == 'train'
Requires-Dist: sentencepiece==0.2.0; extra == 'train'
Requires-Dist: transformers==4.48.0; extra == 'train'
Requires-Dist: trl==0.13.0; extra == 'train'
Description-Content-Type: text/markdown

# 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.

```bash
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.

```bash
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>/`.

```bash
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).

```bash
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:

```bash
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.
