Metadata-Version: 2.4
Name: blitz-cli
Version: 0.17.1
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.11
Requires-Dist: rich>=13
Provides-Extra: secrets
Requires-Dist: boto3>=1.34; extra == 'secrets'
Provides-Extra: toml
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'toml'
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` records every generation attempt as SFT training data.
Collection is on by default; pass `--no-collect` to turn it off, in which case
no database is opened at all. 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
```

Each attempt is acknowledged by the endpoint before the next model call
starts. If the endpoint is unreachable when the run starts, the run warns on
stderr and continues without collection, 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. `blitz model sft` reads the
database directly, unaffected by the endpoint.

`blitz model execute` exits 0 when the run completes, 1 when it completes with
unsolved tasks, and 2 when it aborts on an environment failure: the model
endpoint became unreachable, everything collected before the failure was saved,
and the remaining tasks were not attempted. An outage is recorded as an
environment failure on the attempt and never queues a task for repair.

### The repair queue: `blitz model sft`

A task the local model does not solve leaves a placeholder in the repair queue,
awaiting a reference solution. Attaching the frontier's repair to that
placeholder is what turns a failed run into supervised training data.

```bash
blitz model sft stats [--run RUN_ID]        # attempt counts, pass rates, queue depth
blitz model sft solve --run RUN_ID --task T014 --solution-file repair.patch
blitz model sft queue --run RUN_ID --task T009
```

`sft stats` reports, per run, the attempt count, per-task pass rates with the
20 to 80 percent band marked, and the repair-queue depth.

`sft solve` attaches a reference solution to a queued task, setting it to
`has_solution` and attributing it to `frontier`. Give the solution with
`--solution TEXT`, `--solution-file PATH`, or `--solution-stdin`. A task that
already has a solution is left alone unless you pass `--force`. The solution
lands on the queue row only: the collected attempt record holds local-model
output and never receives frontier text.

`sft queue` queues a task after the fact, for the case where the local model
reported a task complete and the work was not done. The default reason is
`false_success`, which keeps it distinguishable from a task that honestly
exhausted its retries. The prompt is reused from the run's earliest recorded
attempt for that task; pass `--prompt-file PATH` when the run recorded none. A
row that already carries a solution is left unchanged.

Every subcommand takes `--db PATH` (default: `BLITZ_ACTIVITY_DB_PATH`, else
`data/activity.db`).

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