Metadata-Version: 2.4
Name: blitz-cli
Version: 0.7.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: locker-room
Requires-Dist: mcp>=1.0; extra == 'locker-room'
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: `playbooks`, `locker-room`, `activity`.

## Playbooks: spec-driven development commands

`blitz playbooks 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 `.playbooks/` working area.

```bash
blitz playbooks init                 # auto-detect the agent(s) in this repo
blitz playbooks init --agent claude  # or target one explicitly
blitz playbooks 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.

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

`blitz locker-room init` scaffolds a `docker-compose.yml` that pulls prebuilt
images (from `sparepartslabs/blitz-locker-room`, pinned to this CLI version) for
three 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 SSE.

```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 ontology is also usable directly on the host, no containers required:

```bash
blitz locker-room ontologize    # scan a workspace into ./data/ontology.db
blitz locker-room list          # list playbook-enabled repos + their active feature
blitz locker-room mcp           # stdio MCP server for a local agent
```

### The graph an agent can query

`ontologize` reuses playbook discovery and static code parsing (Python symbols +
imports + calls; File nodes for other languages) to build a graph of `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 tools expose this:
`list_repos`, `get_repo`, `list_huddles`, `get_huddle`, `get_playbooks`,
`get_lineage`, `impact_of`, `get_file`, `get_symbol`, and a generic `neighbors`.

### Training (optional)

`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 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 activity --list               # sessions for this repo, most recent first
blitz activity                      # the most recent session's timeline
blitz activity <session-id-prefix>  # a specific session
blitz activity --full               # untruncated prompts/responses/tool I/O
blitz 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.
