---------------------------------------------------------------------- This is the API documentation for the cc_steer library. ---------------------------------------------------------------------- ## Scanning Mine feedback events out of transcripts, incrementally. ## Detection The signal detectors and the candidate shape they emit. ## Storage The feedback event store. ---------------------------------------------------------------------- This is the CLI documentation for the package. ---------------------------------------------------------------------- ## CLI: cc-steer ``` Usage: cc-steer [OPTIONS] COMMAND [ARGS]... Collect developer steering signals from existing Claude Code transcripts. Options: --version Show the version and exit. --help Show this message and exit. Commands: audit Audit a seeded stratified sample of the current... enrich Ground every refined pair in the code evidence behind... eval Compute the mechanical metrics for the current prompt... export Export the steering lineage as a HuggingFace dataset. hooks Manage the global SessionEnd hook that feeds... inbox List recent and undelivered steers — the fallback... index Embed the accepted steering exemplars for the... list List recent feedback events, newest first. live Control live steering: the delivery mode, the kill... models Inspect and flip the registry of lab-trained model... pairs Print the refined training pairs — the pipeline's... pipeline Run the collection stages as one budgeted,... refine Refine every accepted steering event into atomic... sample-negatives Sample gate training windows: rewound positives, hard... scan Scan transcripts for feedback, incrementally. shadow Analyze the live watcher's shadow-mode proposals. stats Print ingestion counts by source kind and triage... triage Judge every stored candidate lacking a verdict at the... view-samples Serve the training-pairs dashboard: refined pairs and... watch Tail live transcripts and run the steering cascade,... ``` ### cc-steer scan ``` Usage: cc-steer scan [OPTIONS] Scan transcripts for feedback, incrementally. Each transcript is parsed only when new or modified since the last scan, and every candidate is inserted with ``INSERT OR IGNORE`` keyed by a content digest, so re-running ``scan`` over unchanged inputs is a no-op. Recording a file and inserting its candidates commit in one transaction. With ``--findings``, superset ``issues.jsonl`` files under the given directories are anchored to the closest session and recorded through the same idempotent insert. A pass that changes data syncs the dataset to HuggingFace; ``--no- sync`` skips it. Options: --transcripts DIRECTORY Transcript directories to scan. Defaults to ~/.claude/projects. --findings DIRECTORY Directories to search for superset issues.jsonl findings files. May be repeated. --full Re-scan every transcript, ignoring recorded mtimes. --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --sync / --no-sync Rebuild the derived dataset and push it to your private HuggingFace repo when the pass changed data. [default: sync] --help Show this message and exit. ``` ### cc-steer stats ``` Usage: cc-steer stats [OPTIONS] Print ingestion counts by source kind and triage coverage. Options: --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer list ``` Usage: cc-steer list [OPTIONS] List recent feedback events, newest first. Options: --source [transcript_message|plan_review|interrupt_rejection|review_comment|question_answer] Restrict to one source kind. --limit INTEGER Maximum events to show. [default: 20] --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --help Show this message and exit. ``` ### cc-steer triage ``` Usage: cc-steer triage [OPTIONS] Judge every stored candidate lacking a verdict at the current prompt version. Incremental and idempotent: verdicts persist per row as soon as each call completes, failed rows stay pending and are retried on the next run, and re- running over a fully judged corpus is a no-op. With ``--refresh-summary``, rows judged at summary fidelity are re-judged; a full-fidelity verdict replaces the summary one once the row's window hydrates again. A pass that changes data syncs the dataset to HuggingFace; ``--no-sync`` skips it. Options: --model [small|medium|large] Judge model tier. [default: medium] --limit INTEGER Judge at most this many rows this pass. --concurrency INTEGER Maximum concurrent claude subshells. [default: 8] --refresh-summary Also re-judge rows whose verdict was recorded at summary fidelity. --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --sync / --no-sync Rebuild the derived dataset and push it to your private HuggingFace repo when the pass changed data. [default: sync] --help Show this message and exit. ``` ### cc-steer audit ``` Usage: cc-steer audit [OPTIONS] Audit a seeded stratified sample of the current prompt version's verdicts. The auditor is a stronger model, blind to the judge's verdicts; its labels are keyed independently of the judge's prompt version, so they accumulate across iterations and re-auditing a sampled row costs nothing. A pass that changes data syncs the dataset to HuggingFace; ``--no-sync`` skips it. Options: --accepts INTEGER Audit budget for judge-accepted rows. [default: 60] --rejects INTEGER Audit budget for judge-rejected rows. [default: 60] --seed INTEGER Deterministic sampling seed (iteration number). [default: 1] --model [small|medium|large] Auditor model tier. [default: large] --concurrency INTEGER Maximum concurrent claude subshells. [default: 8] --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --sync / --no-sync Rebuild the derived dataset and push it to your private HuggingFace repo when the pass changed data. [default: sync] --help Show this message and exit. ``` ### cc-steer eval ``` Usage: cc-steer eval [OPTIONS] Compute the mechanical metrics for the current prompt version. No LLM calls. Recomputes everything from raw verdicts: the golden-set gate, audited precision and reject contamination over the reproduced uniform core, the cumulative-pool secondary estimates, per-kind tables, and (with ``--compare- to``) verdict flips against an earlier prompt version. Options: --seed INTEGER The seed the audit ran with. [default: 1] --accepts INTEGER The audit's accept budget. [default: 60] --rejects INTEGER The audit's reject budget. [default: 60] --compare-to INTEGER Earlier prompt version for flip analysis. --json Emit the full metrics as JSON. --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer refine ``` Usage: cc-steer refine [OPTIONS] Refine every accepted steering event into atomic training pairs. Incremental and idempotent: pairs commit per event as soon as each call completes, failed events stay pending and are retried on the next run, and re-running over a fully refined corpus is a no-op. A pass that changes data syncs the dataset to HuggingFace; ``--no-sync`` skips it. Options: --model [small|medium|large] Refiner model tier. [default: medium] --limit INTEGER Refine at most this many events this pass. --concurrency INTEGER Maximum concurrent claude subshells. [default: 8] --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --sync / --no-sync Rebuild the derived dataset and push it to your private HuggingFace repo when the pass changed data. [default: sync] --help Show this message and exit. ``` ### cc-steer enrich ``` Usage: cc-steer enrich [OPTIONS] Ground every refined pair in the code evidence behind it. Hands each pair's steering anchor and direction to cc-transcript's shared correction extractor, which harvests the candidate edits and their later corrections (from the session, or from git history), picks the one the direction faults — an LLM call when a backend is ready, the best-overlap candidate otherwise — and appends it to the shared ``corrections`` ledger. Anchors that yield no correction (expired transcripts, editless windows) cost no LLM call. Incremental and idempotent: a pair settles once its anchor carries a ledger row, a failure aborts the pass loudly (corrections already appended to the ledger persist, so a re-run resumes), and a refine re-run resurfaces its new pairs here automatically. A pass that changes data syncs the dataset to HuggingFace; ``--no-sync`` skips it. Options: --model [small|medium|large] Linking model tier. [default: medium] --limit INTEGER Enrich at most this many pairs this pass. --concurrency INTEGER Maximum concurrent claude subshells. [default: 8] --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --sync / --no-sync Rebuild the derived dataset and push it to your private HuggingFace repo when the pass changed data. [default: sync] --help Show this message and exit. ``` ### cc-steer export ``` Usage: cc-steer export [OPTIONS] Export the steering lineage as a HuggingFace dataset. Builds the canonical ``traces`` config — one row per judged event, carrying the context, judge and auditor verdicts, refined pairs, and code evidence — plus the TRL-ready ``sft``, ``dpo``, and ``kto`` projections. Both source databases are read-only; every config lands as per-split parquet under ``--out`` next to a generated dataset card, and ``--push`` uploads every config to a private dataset in your HF namespace (created on first push), ``--repo-id`` overriding the target. Options: --out DIRECTORY Directory to write the per-config parquet files and dataset card into. [default: /home/runner/.cc- steer/dataset] --repo-id TEXT HuggingFace dataset repo to push to. [default: (/cc-steer-traces)] --push / --no-push Push every config to --repo-id as a private dataset. [default: no-push] --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer pairs ``` Usage: cc-steer pairs [OPTIONS] Print the refined training pairs — the pipeline's deliverable. Each pair is one atomic direction: a faithful re-synthesis of what Claude did, the verbatim user excerpt, and the distilled one-sentence direction. Options: --jsonl Emit full pairs as JSON lines for fine-tuning export. --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer sample-negatives ``` Usage: cc-steer sample-negatives [OPTIONS] Sample gate training windows: rewound positives, hard and random negatives. Positive windows and hard negatives are recomputed from the judged corpus and deduped by key; random negatives parse a budgeted, seed-deterministic batch of transcripts that carry none yet, excluding anything near a detected event, so repeated passes extend coverage. No LLM calls. Options: --seed INTEGER Deterministic sampling seed. [default: 1] --sessions INTEGER Maximum transcripts to parse this pass. [default: 400] --per-session INTEGER Random negatives per transcript. [default: 20] --resample Revisit sessions that already carry random samples. --transcripts DIRECTORY Transcript roots to mine. Defaults to ~/.claude/projects plus the mirror corpus. --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer index ``` Usage: cc-steer index [OPTIONS] Embed the accepted steering exemplars for the frontier refiner's retrieval. Incremental by content digest — only exemplars whose rendered context changed re-embed. Train-split events only, so evaluation retrieval is never contaminated. Requires the ``embed`` extra. Options: --model TEXT Embedding model for the exemplar index. [default: voyage-4-large] --batch INTEGER Encode batch size. [default: 32] --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --help Show this message and exit. ``` ### cc-steer hooks ``` Usage: cc-steer hooks [OPTIONS] COMMAND [ARGS]... Manage the global SessionEnd hook that feeds continual collection. Options: --help Show this message and exit. Commands: install Wire an async SessionEnd scan into the user-level Claude... status Show the scan command currently wired at SessionEnd, if any. uninstall Remove the SessionEnd scan hook, leaving every other hook... ``` ### cc-steer hooks install ``` Usage: cc-steer hooks install [OPTIONS] Wire an async SessionEnd scan into the user-level Claude Code settings. Every session on the machine then feeds the store incrementally as it ends; the LLM stages and the HF sync stay with the scheduled pipeline. Idempotent: re-running updates the one cc-steer-owned group in place and preserves every other hook untouched. Options: --prefix TEXT Command prefix the hook invokes cc-steer with. [default: uvx cc-steer] --settings FILE Settings file. Defaults to ~/.claude/settings.json. --help Show this message and exit. ``` ### cc-steer hooks uninstall ``` Usage: cc-steer hooks uninstall [OPTIONS] Remove the SessionEnd scan hook, leaving every other hook untouched. Options: --settings FILE Settings file. Defaults to ~/.claude/settings.json. --help Show this message and exit. ``` ### cc-steer hooks status ``` Usage: cc-steer hooks status [OPTIONS] Show the scan command currently wired at SessionEnd, if any. Options: --settings FILE Settings file. Defaults to ~/.claude/settings.json. --help Show this message and exit. ``` ### cc-steer live ``` Usage: cc-steer live [OPTIONS] COMMAND [ARGS]... Control live steering: the delivery mode, the kill switch, and the prompt- submit hook. Options: --help Show this message and exit. Commands: accept Mark PROPOSAL_ID accepted — an explicit positive... dismiss Mark PROPOSAL_ID dismissed — an explicit negative... edit Mark PROPOSAL_ID edited — an explicit... hook The ``UserPromptSubmit`` handler: pop and surface the... install-hook Wire the synchronous UserPromptSubmit steer hook into... mode Set the delivery mode in ``~/.cc-steer/live.toml`` (the... off Halt live delivery everywhere: touch the... on Resume live delivery: clear the... status Show the live mode, the kill switch, allowed projects,... uninstall-hook Remove the UserPromptSubmit steer hook, leaving every... ``` ### cc-steer live hook ``` Usage: cc-steer live hook [OPTIONS] The ``UserPromptSubmit`` handler: pop and surface the freshest queued steer (fail-open, exits 0). Options: --help Show this message and exit. ``` ### cc-steer live install-hook ``` Usage: cc-steer live install-hook [OPTIONS] Wire the synchronous UserPromptSubmit steer hook into the user-level Claude Code settings. Options: --prefix TEXT Command prefix the hook runs. [default: uvx cc-steer] --settings FILE Settings file. --help Show this message and exit. ``` ### cc-steer live uninstall-hook ``` Usage: cc-steer live uninstall-hook [OPTIONS] Remove the UserPromptSubmit steer hook, leaving every other hook untouched. Options: --settings FILE Settings file. --help Show this message and exit. ``` ### cc-steer live on ``` Usage: cc-steer live on [OPTIONS] Resume live delivery: clear the ``~/.cc-steer/live.off`` kill switch. Options: --help Show this message and exit. ``` ### cc-steer live off ``` Usage: cc-steer live off [OPTIONS] Halt live delivery everywhere: touch the ``~/.cc-steer/live.off`` kill switch and expire the backlog. Options: --help Show this message and exit. ``` ### cc-steer live mode ``` Usage: cc-steer live mode [OPTIONS] {shadow|mirror|live_allow|live_all} Set the delivery mode in ``~/.cc-steer/live.toml`` (the live modes are a human-only escalation). The change expires every queued steer so a backlog built under the old policy never delivers under the new one. Options: --help Show this message and exit. ``` ### cc-steer live status ``` Usage: cc-steer live status [OPTIONS] Show the live mode, the kill switch, allowed projects, and today's delivery counts. Options: --help Show this message and exit. ``` ### cc-steer live accept ``` Usage: cc-steer live accept [OPTIONS] PROPOSAL_ID Mark PROPOSAL_ID accepted — an explicit positive reaction that outranks the attribution scan. Options: --help Show this message and exit. ``` ### cc-steer live dismiss ``` Usage: cc-steer live dismiss [OPTIONS] PROPOSAL_ID Mark PROPOSAL_ID dismissed — an explicit negative reaction that outranks the attribution scan. Options: --help Show this message and exit. ``` ### cc-steer live edit ``` Usage: cc-steer live edit [OPTIONS] PROPOSAL_ID Mark PROPOSAL_ID edited — an explicit corrected-positive reaction that outranks the attribution scan. Options: --help Show this message and exit. ``` ### cc-steer inbox ``` Usage: cc-steer inbox [OPTIONS] List recent and undelivered steers — the fallback surface when the hook stays quiet. Options: --limit INTEGER How many recent deliveries to show. [default: 20] --help Show this message and exit. ``` ### cc-steer models ``` Usage: cc-steer models [OPTIONS] COMMAND [ARGS]... Inspect and flip the registry of lab-trained model versions. Options: --help Show this message and exit. Commands: list List registered versions, oldest first; the promoted one is... promote Atomically point ``current`` at VERSION (full name or its... rollback Flip ``current`` back to the version registered before it. ``` ### cc-steer models list ``` Usage: cc-steer models list [OPTIONS] [COMPONENT] List registered versions, oldest first; the promoted one is marked ``*``. With no COMPONENT, every component in the registry is listed. Options: --help Show this message and exit. ``` ### cc-steer models promote ``` Usage: cc-steer models promote [OPTIONS] COMPONENT VERSION Atomically point ``current`` at VERSION (full name or its ``v`` prefix). Options: --help Show this message and exit. ``` ### cc-steer models rollback ``` Usage: cc-steer models rollback [OPTIONS] COMPONENT Flip ``current`` back to the version registered before it. Options: --help Show this message and exit. ``` ### cc-steer pipeline ``` Usage: cc-steer pipeline [OPTIONS] COMMAND [ARGS]... Run the collection stages as one budgeted, schedulable pass. Options: --help Show this message and exit. Commands: install-launchd Schedule the pass nightly — plus the weekly model... run Run one budgeted pass over every stage: scan,... uninstall-launchd Unload and remove the nightly pipeline, weekly... ``` ### cc-steer pipeline run ``` Usage: cc-steer pipeline run [OPTIONS] Run one budgeted pass over every stage: scan, triage, refine, enrich, export. A weekly pass adds the auditor and the mechanical eval before the export. A stage failure is recorded and skipped past so later stages still run, a failed HF push downgrades to a local-only export, and with ``--journal- repo`` the pass appends its one-line summary to that repo's cc-notes journal. Exits nonzero when any stage failed. Options: --weekly Also run the auditor and the mechanical eval this pass. --auto-weekly Treat Sunday runs as weekly; the launchd agent's mode. --push / --no-push Push the export to HuggingFace. [default: push] --triage-limit INTEGER Judge at most this many. [default: 400] --refine-limit INTEGER Refine at most this many. [default: 400] --enrich-limit INTEGER Enrich at most this many. [default: 200] --concurrency INTEGER Maximum concurrent claude subshells. [default: 8] --journal-repo DIRECTORY Repository whose cc-notes journal records this pass. --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --help Show this message and exit. ``` ### cc-steer pipeline install-launchd ``` Usage: cc-steer pipeline install-launchd [OPTIONS] Schedule the pass nightly — plus the weekly model retrain and the shadow watcher — via macOS LaunchAgents. The pipeline agent covers both collection cadences: it runs ``pipeline run --auto-weekly``, so the Sunday pass folds in the auditor and eval. The retrain agent runs the lab's ``harness.retrain`` every Sunday, refreshing the promoted gate model when the training data moved (``--no-retrain`` skips it). The watch agent runs ``cc-steer watch`` continuously under ``KeepAlive`` so a fail-fast crash respawns (``--no-watch`` skips it). Logs land under ``~/.cc-steer/logs/``. Re-running replaces the agents in place. Options: --prefix TEXT Command prefix the agent invokes cc-steer with. [default: uvx cc-steer] --journal-repo DIRECTORY Repository whose cc-notes journal records each pass. --hour INTEGER Local hour the nightly pass fires at. [default: 3] --retrain / --no-retrain Also install the weekly gate-retrain agent, run through the lab checkout. [default: retrain] --lab DIRECTORY The cc-steer-lab checkout the retrain agent runs harness.retrain in. [default: (~/Code/cc-steer- lab)] --retrain-hour INTEGER Local hour the Sunday retrain fires at. [default: 4] --watch / --no-watch Also install the always-on watch daemon under KeepAlive. [default: watch] --help Show this message and exit. ``` ### cc-steer pipeline uninstall-launchd ``` Usage: cc-steer pipeline uninstall-launchd [OPTIONS] Unload and remove the nightly pipeline, weekly retrain, and shadow watch LaunchAgents. Options: --help Show this message and exit. ``` ### cc-steer watch ``` Usage: cc-steer watch [OPTIONS] Tail live transcripts and run the steering cascade, delivering per ``~/.cc- steer/live.toml``. Every open session is followed as it writes; each time one goes quiet after completing a turn, the cascade — stage-1 gate, drafting model, optional exemplar-conditioned refiner — decides whether the user would have steered right there. Stage 1 defaults to the promoted lexical gate from the model registry, thresholded at its trained 2 fires/100 turns budget (``--gate- threshold`` overrides); without a promoted version it falls back to the turn-floor heuristic. Stage 2 defaults to the promoted local watcher (the mlx extra) when one exists, abstaining at its trained budget threshold on P(NO_STEER); stage 3 is then disabled — the E2-validated two-stage configuration — unless ``--refiner spawn`` re-enables it. Every proposal lands in the shadow ledger (``cc-steer shadow report`` measures them); in ``mirror`` or a live mode it is also queued to the delivery mailbox (``cc- steer inbox``) for the ``UserPromptSubmit`` hook to surface. ``--shadow`` forces shadow delivery regardless of the config. Exemplar retrieval needs the ``embed`` extra and a built index (``cc-steer index``); without one the watcher still runs, stage 3 unconditioned. Runs until interrupted. Options: --shadow Force shadow delivery, ignoring the mode in ~/.cc-steer/live.toml. --root DIRECTORY Transcript roots to tail. Defaults to ~/.claude/projects. --gate [heuristic|lexical] Stage-1 gate: the lab-trained lexical model (from the registry) or the turn-floor heuristic. [default: (lexical when a gate model is promoted, else heuristic)] --gate-threshold FLOAT Stage-1 gate score below which a turn is suppressed. [default: (the trained threshold (lexical) or 0.5 (heuristic))] --drafter [auto|spawn|mlx] Stage-2 drafter: the local trained watcher (mlx) or the claude CLI (spawn); auto picks mlx when a watcher model is promoted and the mlx extra is installed. [default: auto] --stage2-threshold FLOAT Local drafter abstain threshold on P(NO_STEER); ignored for the spawn drafter. [default: (the promoted watcher's budget threshold)] --refiner [auto|spawn|none] Stage 3: the claude CLI refiner or none (a fired draft ships as-is); auto disables it for the mlx drafter (two-stage, per E2) and keeps it for spawn. [default: auto] --debounce FLOAT Seconds a session must stay quiet before its last completed turn is evaluated. [default: 2.0] --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --shadow-db FILE Shadow ledger path. Defaults to ~/.cc- steer/shadow.db. --help Show this message and exit. ``` ### cc-steer shadow ``` Usage: cc-steer shadow [OPTIONS] COMMAND [ARGS]... Analyze the live watcher's shadow-mode proposals. Options: --help Show this message and exit. Commands: report Join shadow proposals against the interventions users actually... ``` ### cc-steer shadow report ``` Usage: cc-steer shadow report [OPTIONS] Join shadow proposals against the interventions users actually made. Feedback events carry no turn index, so the join is time within a session: a steer is a HIT when the same session shows a real feedback event within ``--window`` minutes after the proposal fired, and a nuisance candidate otherwise. Also reports stage-2/3 abstention rates, per-category hit counts, the drafter's sentinel-probability distribution, proposals per session, and the sessions that produced proposals. No LLM calls. Options: --window INTEGER Minutes after a proposal within which a real intervention counts as a hit. [default: 30] --json Emit the summary as JSON. --db FILE Database path. Defaults to ~/.cc- steer/feedback.db. --shadow-db FILE Shadow ledger path. Defaults to ~/.cc- steer/shadow.db. --journal-repo DIRECTORY Repository whose cc-notes journal records this report. --help Show this message and exit. ``` ### cc-steer view-samples ``` Usage: cc-steer view-samples [OPTIONS] Serve the training-pairs dashboard: refined pairs and their full lineage. Opens an interactive dashboard listing the refined pairs (the pipeline's deliverable) and every candidate behind them, with a detail pane that walks one candidate's lineage — detector hit, judge verdicts across versions, the auditor's agreement, the refiner's atomic split, and the golden gate. It is served over a transient HTTP server whose URL is printed; press Ctrl-C to stop. The corpus narrative is written by the ``claude`` CLI. Options: --db FILE Database path. Defaults to ~/.cc-steer/feedback.db. --model TEXT Model for the claude CLI summary. [default: claude- sonnet-4-6] --port INTEGER Port to serve on; 0 picks a free one. [default: 0] --open Open the dashboard in a browser once serving. --help Show this message and exit. ```