bmsdna-devtools 0.41.0__tar.gz → 0.43.0__tar.gz

bmsdna_devtools-0.41.0/README.md → bmsdna_devtools-0.43.0/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.5
+Name: bmsdna-devtools
+Version: 0.43.0
+Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
+Requires-Python: >=3.14
+Requires-Dist: pgdevkit[db]>=0.7.1
+Requires-Dist: requests>=2.32.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.26.7
+Provides-Extra: lint
+Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
+Provides-Extra: usage
+Requires-Dist: duckdb>=1.3.0; extra == 'usage'
+Requires-Dist: plotly>=5.24.0; extra == 'usage'
+Description-Content-Type: text/markdown
+
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
@@ -29,6 +46,8 @@ uv tool install bmsdna-devtools
 
 Or as a project dependency: `uv add bmsdna-devtools`.
 
+Optional extras: `bmsdna-devtools[lint]` (`bdt lint` SQL rules), `bmsdna-devtools[usage]` (`bdt usage`, below).
+
 ## `bdt pr status`
 
 Find the PR opened from the current branch and report build/check status
@@ -36,7 +55,7 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch BRANCH] [--wait]
+bdt pr status [--target-branch BRANCH] [--pr-id N] [--wait [--timeout SECONDS]]
 ```
 
 Every command that acts on an existing PR (`pr status/info/retry/publish/update/comment`, `issue take` without
@@ -61,6 +80,12 @@ stage/check needs a reviewer plus a link to act on it, and exits **3**
 build/check has already failed, that's reported instead (exit 1) even when
 one is also waiting on approval.
 
+`--wait --timeout SECONDS` gives up after that long when the checks are still running: it prints the current
+state of every pipeline/check, ends with `Still running after N s. Re-run ... to keep waiting.` (the command pins `--pr-id` to the PR it watched) and exits **4**
+(like `issue watch`). Use it where the caller's own limit is shorter than CI, e.g. an agent's shell tool, which
+kills the command after a few minutes and discards its output; re-run the same command to keep waiting.
+Without `--timeout` (or with `0`) it waits until everything is done, as before. `--timeout` needs `--wait`.
+
 On Azure DevOps, `--wait` on a PR with no builds yet also checks that the target branch has an enabled
 Build validation policy; if it doesn't, no build will ever run, so it exits 1 with an error instead of
 polling forever (a failed policy lookup is ignored and the wait continues).
@@ -1018,6 +1043,39 @@ such as `'assets/**/*.js'`) or `[tool.bdt.lint] exclude_dirs = [...]` in `pyproj
 Identical findings on the same line are reported once. Silence a confirmed-safe finding with
 `# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>` (TS/JS) on, or directly above, the line.
 
+## `bdt usage analyze` / `bdt usage sql`
+
+Where do the tokens of your Claude Code and codex sessions go, per step of the `dev-workflow`? Needs the extra:
+`uv tool install 'bmsdna-devtools[usage]'` (DuckDB reads the logs, plotly draws the report; neither is imported by other commands).
+
+```bash
+bdt usage analyze [--scope workflow|all] [--since 2026-10-01] [--price gpt-6-sol=1.25,10,0.125] [--no-codex] [--rebuild]
+bdt usage sql "select label, round(pct_cost, 1) from v_steps"    # ad hoc SQL on the last analysis
+```
+
+It reads `~/.claude/projects` (`--logs`) and `~/.codex/sessions` (`--codex-logs`, skipped if missing), prints a summary and
+writes `report.html` (charts plus a table view, light/dark) with CSV / Parquet exports next to the database
+(`~/.cache/bdt/usage/`, or `--db` / `--out`). The report is self-contained and contains your session titles and agent
+descriptions, so look at it before sharing it.
+
+- **Steps:** setup, plan, plan review, implement, test, screenshots, design review, quick review, full review, publish / CI.
+  Every model turn is assigned to one by markers in its tool calls: skill calls (`bms-code-review --quick|--full`,
+  `design-review`, `bms-plan-review`; for codex, reading the skill's `SKILL.md`), `bdt` commands, edits (`apply_patch` for
+  codex), pytest / lint, screenshot tooling, image reads. A step stays until the next marker; test runs only count for
+  the turn that runs them. Subagents inherit the step of the turn that spawned them. Only threads that follow the workflow
+  (and what they spawn) are counted, `--scope all` takes every session. It is a heuristic: read differences of a few percent
+  as noise. The rules are SQL in `bmsdna/devtools/usage/sql/03_markers.sql`.
+- **Numbers:** cost is the API list price (cache writes 1.25x / 2x, cache reads, output, per model), not your actual bill;
+  "% tokens" counts cache reads too, "% fresh tokens" does not. The report also estimates what screenshots cost by sitting in
+  the context of every later turn.
+- **codex:** a codex run that Claude started with `codex exec` / `codex review` (same directory, within 15 minutes) is counted
+  in that Claude session and step, so reviews run by codex show up under "Review" even though Claude's own log doesn't contain
+  them; codex subagents follow their parent thread. codex models have no built-in price: give one with
+  `--price MODEL=INPUT,OUTPUT,CACHED` (USD per million tokens), repeatable. Turns without a price are counted in tokens
+  but missing from every cost number, and the summary says how many.
+- **Cache:** parsed records are kept in the database, so the next run only parses new or changed log files (a few seconds).
+  `--rebuild` re-reads everything. Message text is not stored.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

bmsdna_devtools-0.41.0/PKG-INFO → bmsdna_devtools-0.43.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.5
-Name: bmsdna-devtools
-Version: 0.41.0
-Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
-Requires-Python: >=3.14
-Requires-Dist: pgdevkit[db]>=0.7.1
-Requires-Dist: requests>=2.32.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: typer>=0.26.7
-Provides-Extra: lint
-Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
-Description-Content-Type: text/markdown
-
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
@@ -43,6 +29,8 @@ uv tool install bmsdna-devtools
 
 Or as a project dependency: `uv add bmsdna-devtools`.
 
+Optional extras: `bmsdna-devtools[lint]` (`bdt lint` SQL rules), `bmsdna-devtools[usage]` (`bdt usage`, below).
+
 ## `bdt pr status`
 
 Find the PR opened from the current branch and report build/check status
@@ -50,7 +38,7 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch BRANCH] [--wait]
+bdt pr status [--target-branch BRANCH] [--pr-id N] [--wait [--timeout SECONDS]]
 ```
 
 Every command that acts on an existing PR (`pr status/info/retry/publish/update/comment`, `issue take` without
@@ -75,6 +63,12 @@ stage/check needs a reviewer plus a link to act on it, and exits **3**
 build/check has already failed, that's reported instead (exit 1) even when
 one is also waiting on approval.
 
+`--wait --timeout SECONDS` gives up after that long when the checks are still running: it prints the current
+state of every pipeline/check, ends with `Still running after N s. Re-run ... to keep waiting.` (the command pins `--pr-id` to the PR it watched) and exits **4**
+(like `issue watch`). Use it where the caller's own limit is shorter than CI, e.g. an agent's shell tool, which
+kills the command after a few minutes and discards its output; re-run the same command to keep waiting.
+Without `--timeout` (or with `0`) it waits until everything is done, as before. `--timeout` needs `--wait`.
+
 On Azure DevOps, `--wait` on a PR with no builds yet also checks that the target branch has an enabled
 Build validation policy; if it doesn't, no build will ever run, so it exits 1 with an error instead of
 polling forever (a failed policy lookup is ignored and the wait continues).
@@ -1032,6 +1026,39 @@ such as `'assets/**/*.js'`) or `[tool.bdt.lint] exclude_dirs = [...]` in `pyproj
 Identical findings on the same line are reported once. Silence a confirmed-safe finding with
 `# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>` (TS/JS) on, or directly above, the line.
 
+## `bdt usage analyze` / `bdt usage sql`
+
+Where do the tokens of your Claude Code and codex sessions go, per step of the `dev-workflow`? Needs the extra:
+`uv tool install 'bmsdna-devtools[usage]'` (DuckDB reads the logs, plotly draws the report; neither is imported by other commands).
+
+```bash
+bdt usage analyze [--scope workflow|all] [--since 2026-10-01] [--price gpt-6-sol=1.25,10,0.125] [--no-codex] [--rebuild]
+bdt usage sql "select label, round(pct_cost, 1) from v_steps"    # ad hoc SQL on the last analysis
+```
+
+It reads `~/.claude/projects` (`--logs`) and `~/.codex/sessions` (`--codex-logs`, skipped if missing), prints a summary and
+writes `report.html` (charts plus a table view, light/dark) with CSV / Parquet exports next to the database
+(`~/.cache/bdt/usage/`, or `--db` / `--out`). The report is self-contained and contains your session titles and agent
+descriptions, so look at it before sharing it.
+
+- **Steps:** setup, plan, plan review, implement, test, screenshots, design review, quick review, full review, publish / CI.
+  Every model turn is assigned to one by markers in its tool calls: skill calls (`bms-code-review --quick|--full`,
+  `design-review`, `bms-plan-review`; for codex, reading the skill's `SKILL.md`), `bdt` commands, edits (`apply_patch` for
+  codex), pytest / lint, screenshot tooling, image reads. A step stays until the next marker; test runs only count for
+  the turn that runs them. Subagents inherit the step of the turn that spawned them. Only threads that follow the workflow
+  (and what they spawn) are counted, `--scope all` takes every session. It is a heuristic: read differences of a few percent
+  as noise. The rules are SQL in `bmsdna/devtools/usage/sql/03_markers.sql`.
+- **Numbers:** cost is the API list price (cache writes 1.25x / 2x, cache reads, output, per model), not your actual bill;
+  "% tokens" counts cache reads too, "% fresh tokens" does not. The report also estimates what screenshots cost by sitting in
+  the context of every later turn.
+- **codex:** a codex run that Claude started with `codex exec` / `codex review` (same directory, within 15 minutes) is counted
+  in that Claude session and step, so reviews run by codex show up under "Review" even though Claude's own log doesn't contain
+  them; codex subagents follow their parent thread. codex models have no built-in price: give one with
+  `--price MODEL=INPUT,OUTPUT,CACHED` (USD per million tokens), repeatable. Turns without a price are counted in tokens
+  but missing from every cost number, and the summary says how many.
+- **Cache:** parsed records are kept in the database, so the next run only parses new or changed log files (a few seconds).
+  `--rebuild` re-reads everything. Message text is not stored.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{bmsdna_devtools-0.41.0 → bmsdna_devtools-0.43.0}/bmsdna/devtools/cli.py

@@ -34,7 +34,8 @@ from . import translate as translate_mod
 from . import pr_build, pr_info as pr_info_mod, pr_issue_link, pr_labels, pull as pull_mod, worktree as worktree_mod
 from .ado_auth import auth_header
 from .bdt_config import find_pyproject, load_bdt_table
-from .cli_tools import CLI_TIMEOUT_SECS, detect_agent_session, require_az, require_gh
+from .cli_tools import CLI_TIMEOUT_SECS, EXIT_WAIT_TIMEOUT, detect_agent_session, require_az, require_gh
+from .usage.cli import usage_app
 from .gitrepo import (
     AdoRemote,
     GitHubRemote,
@@ -103,6 +104,8 @@ issue_app.add_typer(issue_comment_app, name="comment")
 logs_app = typer.Typer(name="logs", help="Application Insights / Log Analytics queries")
 app.add_typer(logs_app, name="logs")
 
+app.add_typer(usage_app, name="usage")
+
 cleanup_app = typer.Typer(
     name="cleanup",
     help="Prune merged git worktrees and their orphaned pgdevkit Postgres test databases",
@@ -468,18 +471,28 @@ def pr_publish(
 def pr_status(
     target_branch: str | None = typer.Option(None, "--target-branch", help=_LOOKUP_TARGET_HELP),
     wait: bool = typer.Option(False, "--wait", help="Poll until all pipelines/checks are completed; stops early and reports status if one needs manual approval"),
+    timeout: float = typer.Option(
+        0,
+        "--timeout",
+        help="With --wait: stop after this many seconds if the checks are still running, print their current state and exit "
+        f"{EXIT_WAIT_TIMEOUT} (0 = wait forever, the default). Use it where the caller's own time limit is shorter than CI, "
+        "e.g. an agent's shell tool, then re-run the same command to keep waiting",
+    ),
     pr_id: int | None = typer.Option(None, "--pr-id", help=_PR_ID_HELP),
     pat: str | None = typer.Option(None, "--pat", envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"], help="Azure DevOps PAT (else falls back to `az` login)"),
 ) -> None:
     """Show build/check status for the PR opened from the current branch, or for --pr-id
     directly (Azure DevOps or GitHub, auto-detected).
     """
+    if timeout and not wait:
+        raise typer.BadParameter("--timeout only works together with --wait", param_hint="--timeout")
+    _check_poll_options(None, timeout)
     remote = current_remote()
     if isinstance(remote, GitHubRemote):
         gh = require_gh()
-        gh_pr.run(gh, wait, pr_id=gh_pr.resolve_pr_id(gh, pr_id, target_branch))
+        gh_pr.run(gh, wait, pr_id=gh_pr.resolve_pr_id(gh, pr_id, target_branch), timeout=timeout)
         return
-    pr_build.run(remote, pat, target_branch, wait, pr_id=pr_id)
+    pr_build.run(remote, pat, target_branch, wait, pr_id=pr_id, timeout=timeout)
 
 
 @pr_app.command("info")

{bmsdna_devtools-0.41.0 → bmsdna_devtools-0.43.0}/bmsdna/devtools/cli_tools.py

@@ -13,7 +13,9 @@ import os
 import shutil
 import sys
 import time
+from collections.abc import Callable
 from dataclasses import dataclass
+from typing import NoReturn
 
 AZ_INSTALL_HINT = "Install the Azure CLI: https://learn.microsoft.com/cli/azure/install-azure-cli"
 GH_INSTALL_HINT = "Install the GitHub CLI: https://cli.github.com"
@@ -26,6 +28,11 @@ PSQL_INSTALL_HINT = "Install the PostgreSQL client tools (psql): https://www.pos
 # this tool), and callers branching on exit code shouldn't confuse the two.
 EXIT_NEEDS_APPROVAL = 3
 
+# `pr status --wait --timeout N` exits with this code when the checks are still running after N seconds
+# (same code as `issue watch` / `issue search --wait` use for "gave up waiting"). The caller learns the
+# current state from the output and can simply run the same command again to keep waiting.
+EXIT_WAIT_TIMEOUT = 4
+
 # How long a `--wait` poll loop may go without printing anything before `PollHeartbeat`
 # forces a line out anyway. Every `--wait` loop in this tool polls every 30s but used to
 # print only when the status text changed -- for a check/build that sits in the same
@@ -73,6 +80,42 @@ class PollHeartbeat:
         self._last_print = now
 
 
+class WaitDeadline:
+    """Optional overall time limit of a `--wait` poll loop (`timeout_secs` of 0 / None = wait forever).
+
+    Exists because a caller often can't wait as long as CI takes: an agent's shell tool kills a command
+    after a few minutes and throws its output away. Giving up on our own terms lets us report where things
+    stand and exit with `EXIT_WAIT_TIMEOUT` so the caller knows to re-run.
+    """
+
+    def __init__(self, timeout_secs: float | None) -> None:
+        self.timeout_secs = timeout_secs or 0.0
+        self._end = time.monotonic() + self.timeout_secs if self.timeout_secs else None
+
+    def expired(self) -> bool:
+        return self._end is not None and time.monotonic() >= self._end
+
+    def sleep(self, secs: float) -> None:
+        """`time.sleep(secs)`, cut short so the loop wakes up right at the deadline."""
+        time.sleep(secs if self._end is None else max(0.0, min(secs, self._end - time.monotonic())))
+
+
+def status_rerun_cmd(pr_id: int | None, timeout_secs: float) -> str:
+    """The command that keeps waiting where a timed-out `pr status --wait` stopped. Pins `--pr-id` to the PR that
+    was being watched, so re-running can't resolve to a different PR (e.g. another branch checked out since)."""
+    return f"bdt pr status --pr-id {pr_id} --wait --timeout {timeout_secs:g}" if pr_id else f"bdt pr status --wait --timeout {timeout_secs:g}"
+
+
+def exit_wait_timeout(msg: str, print_details: Callable[[], object], deadline: WaitDeadline, rerun_cmd: str) -> NoReturn:
+    """Report where a `--wait` loop stands when its `deadline` ran out (status line, per-item details), then
+    exit `EXIT_WAIT_TIMEOUT`. The last line tells the caller what to run to keep waiting."""
+    print(msg)
+    print("\nDetails:")
+    print_details()
+    print(f"\nStill running after {deadline.timeout_secs:g} s. Re-run `{rerun_cmd}` to keep waiting.")
+    sys.exit(EXIT_WAIT_TIMEOUT)
+
+
 def is_claude_code() -> bool:
     """True if this process is running as a subprocess of Claude Code.
 

{bmsdna_devtools-0.41.0 → bmsdna_devtools-0.43.0}/bmsdna/devtools/gh_pr.py

@@ -20,7 +20,17 @@ from pathlib import Path
 from typing import Any
 
 from . import pr_issue_link
-from .cli_tools import CLI_TIMEOUT_SECS, EXIT_NEEDS_APPROVAL, PollHeartbeat, detect_agent_session, ensure_agent_session_note, is_claude_code
+from .cli_tools import (
+    CLI_TIMEOUT_SECS,
+    EXIT_NEEDS_APPROVAL,
+    PollHeartbeat,
+    WaitDeadline,
+    detect_agent_session,
+    ensure_agent_session_note,
+    exit_wait_timeout,
+    is_claude_code,
+    status_rerun_cmd,
+)
 from .gitrepo import current_branch
 from .pr_choice import PrCandidate, choose_pr
 from .pr_markdown import build_attachments_section, build_comment_content, build_screenshots_section
@@ -308,8 +318,11 @@ def exit_needs_approval(msg: str, item_lines: list[str], rerun_cmd: str) -> None
     sys.exit(EXIT_NEEDS_APPROVAL)
 
 
-def run(gh: str, wait: bool, pr_id: int | None = None) -> None:
+def run(gh: str, wait: bool, pr_id: int | None = None, timeout: float = 0) -> None:
+    """`timeout` (seconds, only with `wait`): stop polling after that long and exit `EXIT_WAIT_TIMEOUT`
+    with the current state; 0 = wait until every check is done."""
     heartbeat = PollHeartbeat()
+    deadline = WaitDeadline(timeout)
     draft_notice_shown = False
     while True:
         pr = get_pr(gh, pr_id)
@@ -368,7 +381,9 @@ def run(gh: str, wait: bool, pr_id: int | None = None) -> None:
         # must not keep polling forever waiting for it to become unstuck.
         if "pending" in buckets and wait and not waiting_approval:
             heartbeat.show(msg)
-            time.sleep(30)
+            if deadline.expired():
+                exit_wait_timeout(msg, lambda: [print_check(c) for c in checks], deadline, status_rerun_cmd(pr_number, timeout))
+            deadline.sleep(30)
             continue
 
         print(msg)

{bmsdna_devtools-0.41.0 → bmsdna_devtools-0.43.0}/bmsdna/devtools/pr_build.py

@@ -6,12 +6,13 @@ import re
 import sys
 import time
 from pathlib import Path
+from typing import NoReturn
 from urllib.parse import quote
 
 import requests
 
 from .ado_auth import auth_header
-from .cli_tools import EXIT_NEEDS_APPROVAL, HTTP_TIMEOUT_SECS, PollHeartbeat, detect_agent_session, ensure_agent_session_note, is_claude_code
+from .cli_tools import EXIT_NEEDS_APPROVAL, HTTP_TIMEOUT_SECS, PollHeartbeat, WaitDeadline, detect_agent_session, ensure_agent_session_note, exit_wait_timeout, is_claude_code, status_rerun_cmd
 from .gitrepo import AdoRemote, current_branch
 from .pr_choice import PrCandidate, choose_pr
 from .pr_markdown import build_attachments_section, build_comment_content, build_screenshots_section
@@ -766,7 +767,10 @@ def run(
     wait: bool,
     source_branch: str | None = None,
     pr_id: int | None = None,
+    timeout: float = 0,
 ) -> None:
+    """`timeout` (seconds, only with `wait`): stop polling after that long and exit `EXIT_WAIT_TIMEOUT`
+    with the current state; 0 = wait until every pipeline is done."""
     session = requests.Session()
     session.headers.update(auth_header(pat))
 
@@ -804,8 +808,14 @@ def run(
     draft_notice_shown = False
     policy_checked = False
     heartbeat = PollHeartbeat()
+    deadline = WaitDeadline(timeout)
+
+    def time_out(msg: str, builds: list, pr_number: int) -> NoReturn:
+        exit_wait_timeout(msg, lambda: [print_build(session, remote, b) for b in builds], deadline, status_rerun_cmd(pr_number, timeout))
+
     while True:
         pr = _poll_or_exit(fetch_pr)
+        pipeline_builds: list = []
         if not draft_notice_shown:
             draft_msg = draft_notice(pr)
             if draft_msg:
@@ -827,7 +837,9 @@ def run(
                         b.get("definition", {}).get("name", "?") for b in stale
                     )
                     heartbeat.show(msg)
-                    time.sleep(30)
+                    if deadline.expired():
+                        time_out(msg, [b for b in pipeline_builds if b not in stale], pr_number)
+                    deadline.sleep(30)
                     continue
             msg += " | " + ", ".join(
                 f"{b.get('definition', {}).get('name', '?')} #{b['id']} {b.get('status')} ({b.get('result') or '—'})"
@@ -889,7 +901,9 @@ def run(
         heartbeat.show(msg)
 
         if wait:
-            time.sleep(30)
+            if deadline.expired():
+                time_out(msg, pipeline_builds, pr_number)
+            deadline.sleep(30)
 
 
 def run_watch_deploy(remote: AdoRemote, pat: str | None, target_branch: str, wait: bool) -> None:

bmsdna_devtools-0.43.0/bmsdna/devtools/usage/__init__.py

@@ -0,0 +1,5 @@
+"""`bdt usage`: where do the tokens of Claude Code / codex sessions go, per step of the dev-workflow?
+
+Reads the local session logs with DuckDB, attributes every model turn to a workflow step and prices it.
+The heavy dependencies (duckdb, plotly) are the optional `usage` extra and only imported when a command runs.
+"""

bmsdna_devtools-0.43.0/bmsdna/devtools/usage/cli.py

@@ -0,0 +1,122 @@
+"""`bdt usage`: profile Claude Code / codex session logs per step of the dev-workflow."""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import date
+from pathlib import Path
+
+import typer
+
+from . import pricing
+
+usage_app = typer.Typer(
+    name="usage",
+    help="Where do the tokens of Claude Code / codex sessions go, per step of the dev-workflow? "
+    "(needs the `usage` extra: `uv tool install 'bmsdna-devtools\\[usage]'`)",
+)
+
+INSTALL_HINT = "bdt usage needs duckdb and plotly: install the extra, e.g. `uv tool install --reinstall 'bmsdna-devtools[usage]'`"
+DEFAULT_CLAUDE_LOGS = "~/.claude/projects"
+DEFAULT_CODEX_LOGS = "~/.codex/sessions"
+
+
+def default_data_dir() -> Path:
+    cache = Path(os.environ.get("XDG_CACHE_HOME") or "~/.cache").expanduser()
+    return cache / "bdt" / "usage"
+
+
+def require_duckdb():
+    try:
+        import duckdb
+    except ImportError:
+        print(INSTALL_HINT, file=sys.stderr)
+        raise typer.Exit(1) from None
+    return duckdb
+
+
+@usage_app.command("analyze")
+def analyze(
+    logs: str = typer.Option(DEFAULT_CLAUDE_LOGS, "--logs", help="Claude Code projects directory"),
+    codex_logs: str = typer.Option(DEFAULT_CODEX_LOGS, "--codex-logs", help="codex sessions directory (skipped if it does not exist)"),
+    no_codex: bool = typer.Option(False, "--no-codex", help="Ignore codex logs"),
+    db: str | None = typer.Option(None, "--db", help="DuckDB file (default: <cache dir>/bdt/usage/profile.duckdb). Doubles as the parse cache"),
+    out: str | None = typer.Option(None, "--out", help="Directory for report.html and the CSV / Parquet exports (default: next to the database)"),
+    scope: str = typer.Option("workflow", "--scope", help="workflow: only threads that follow dev-workflow (and what they spawn); all: every session"),
+    since: str = typer.Option("1970-01-01", "--since", help="Only messages from this date on (YYYY-MM-DD)"),
+    rebuild: bool = typer.Option(False, "--rebuild", help="Ignore the parse cache in the database and re-read every log file"),
+    no_report: bool = typer.Option(False, "--no-report", help="Only print the summary"),
+    price: list[str] = typer.Option(
+        [], "--price", metavar="MODEL=IN,OUT,CACHED",
+        help="USD per million tokens for a model without a built-in price (codex / OpenAI models), repeatable. "
+        "Example: --price gpt-6-sol=1.25,10,0.125",
+    ),
+) -> None:
+    """Load the session logs, attribute every model turn to a workflow step, price it, and print / render the result.
+
+    The first run parses every log file; later runs only parse new or changed ones. Costs are API list prices
+    (not your actual bill); turns of a model without a price are counted in tokens but not in cost.
+    """
+    if scope not in ("workflow", "all"):
+        raise typer.BadParameter("Must be 'workflow' or 'all'", param_hint="--scope")
+    try:
+        date.fromisoformat(since)
+    except ValueError:
+        raise typer.BadParameter("Must be a date like 2026-10-01", param_hint="--since") from None
+    try:
+        prices = dict(pricing.parse_price(p) for p in price)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint="--price") from None
+    duckdb = require_duckdb()
+    from . import pipeline
+
+    data_dir = default_data_dir()
+    db_path = Path(db).expanduser() if db else data_dir / "profile.duckdb"
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    con = duckdb.connect(str(db_path))
+    print(f"Reading {logs}" + ("" if no_codex else f" and {codex_logs}") + " ...", file=sys.stderr)
+    stats = pipeline.build(
+        con, Path(logs), None if no_codex else Path(codex_logs), scope=scope, since=since, rebuild=rebuild, prices=prices
+    )
+    print(f"{stats.files} log files, {stats.ingested} parsed ({stats.files - stats.ingested} from cache), {stats.removed} removed", file=sys.stderr)
+
+    summary = con.execute("SELECT * FROM v_summary").fetchone()
+    if not summary or not summary[2]:
+        print("No sessions in scope. Nothing used dev-workflow in these logs (try --scope all)?", file=sys.stderr)
+        raise typer.Exit(1)
+    con.sql("SELECT * EXCLUDE (unpriced_msgs, unpriced_models) FROM v_summary").show(max_width=200)
+    con.sql("""
+        SELECT label AS step, msgs AS turns, sessions, round(cost, 2) AS usd,
+               round(pct_cost, 1) AS "% cost", round(pct_tokens, 1) AS "% tokens",
+               round(pct_fresh_tokens, 1) AS "% fresh tokens",
+               round(pct_of_step_via_subagents) AS "% via subagents"
+        FROM v_steps""").show(max_width=200)
+    con.sql("SELECT provider, msgs AS turns, tokens, round(cost, 2) AS usd, round(pct_tokens, 1) AS \"% tokens\" FROM v_providers").show(max_width=200)
+    unpriced = con.execute("SELECT unpriced_msgs, unpriced_models FROM v_summary").fetchone()
+    if unpriced and unpriced[0]:
+        print(
+            f"Note: {unpriced[0]} turns of {unpriced[1]} have no price, so they are missing from the cost columns. "
+            "Add one with --price MODEL=IN,OUT,CACHED (USD per million tokens).",
+            file=sys.stderr,
+        )
+    if not no_report:
+        from . import report
+
+        out_dir = Path(out).expanduser() if out else db_path.parent
+        print(f"Report: {report.write_report(con, out_dir)}", file=sys.stderr)
+
+
+@usage_app.command("sql")
+def sql(
+    query: str = typer.Argument(..., help="SQL to run against a database built by `bdt usage analyze` (tables: facts, msgs, threads, v_*)"),
+    db: str | None = typer.Option(None, "--db", help="DuckDB file (default: the one `analyze` writes)"),
+) -> None:
+    """Run ad-hoc SQL on the last analysis, e.g. `bdt usage sql "select label, round(pct_cost, 1) from v_steps"`."""
+    duckdb = require_duckdb()
+    db_path = Path(db).expanduser() if db else default_data_dir() / "profile.duckdb"
+    if not db_path.exists():
+        print(f"{db_path} does not exist yet: run `bdt usage analyze` first.", file=sys.stderr)
+        raise typer.Exit(1)
+    con = duckdb.connect(str(db_path), read_only=True)
+    con.sql(query).show(max_width=200, max_rows=100)