Metadata-Version: 2.4
Name: blitz-cli
Version: 0.16.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`.

### 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
(`BLITZ_ACTIVITY_DB_PATH`, else `data/activity.db`). With `BLITZ_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:

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

# on the collecting machine:
BLITZ_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

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

```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>: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 `BLITZ_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.
