cctx-cli 0.1.0__tar.gz → 1.0.0__tar.gz

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/.github/workflows/publish.yml

@@ -46,3 +46,18 @@ jobs:
 
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  tag-action:
+    name: Tag floating action version
+    needs: [publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Push floating major tag
+        run: |
+          MAJOR=$(echo "${{ github.event.release.tag_name }}" | cut -d. -f1)
+          git tag -f "$MAJOR"
+          git push origin "$MAJOR" --force

cctx_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Semantic release
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install python-semantic-release
+        run: pip install python-semantic-release
+
+      - name: Compute version and push
+        run: semantic-release version
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Publish GitHub release
+        run: semantic-release publish
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}

cctx_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-05-17)
+
+### Continuous Integration
+
+- Add python-semantic-release for fully automated CD
+  ([`9844921`](https://github.com/jacquardlabs/cctx/commit/98449213e5b3bd597c47d54e4d5043e245adafe4))
+
+- Add workflow_dispatch to release.yml for manual trigger
+  ([`08ac9f8`](https://github.com/jacquardlabs/cctx/commit/08ac9f80eb6ceee7b57155852febc4274cbaf3b0))
+
+
+## v0.2.0 (2026-05-16)
+
+### Bug Fixes
+
+- Ruff lint — B904, E402, E501, F841 across cli, tests, and renderers
+  ([`fa7105f`](https://github.com/jacquardlabs/cctx/commit/fa7105fef340d89136f1996b86824e30d080a730))
+
+- Trace TUI token sum within line-length limit
+  ([`5b7416c`](https://github.com/jacquardlabs/cctx/commit/5b7416c5b92790cfe66f1e53f20891ecaf6e03b0))
+
+### Chores
+
+- Bump version to 0.2.0, update PRODUCT.md and CLAUDE.md
+  ([`828ed49`](https://github.com/jacquardlabs/cctx/commit/828ed4997df9f4a264669bc38f4b10588a151f1c))
+
+### Documentation
+
+- Add CI usage section clarifying harvest is local-only
+  ([`c526408`](https://github.com/jacquardlabs/cctx/commit/c526408a35749858e1c0b0b6ba42aea95bb8f621))
+
+### Features
+
+- **#64,#63**: Tool-thrash and dead-end exploration classifiers
+  ([`14f8f45`](https://github.com/jacquardlabs/cctx/commit/14f8f45f9d3f4ef2fefac374d3e4cea36185c60d))
+
+- **#65**: Harvest v2 — route patches to any .md target (.claude/rules/, .claude/skills/)
+  ([`06ef9b7`](https://github.com/jacquardlabs/cctx/commit/06ef9b7a8ae9abacea54c2c826efc3fb6e6e80be))
+
+- **#66**: Cctx harvest --check audits CLAUDE.md for dead refs and empty sections
+  ([`a3be1d0`](https://github.com/jacquardlabs/cctx/commit/a3be1d0923d387b6830b10c7c2c5acf34a3b8917))
+
+- **#67**: Interactive aggregate drill-down; --check docs in README
+  ([`3db5429`](https://github.com/jacquardlabs/cctx/commit/3db5429dede40777b23d83e32a4b15a8c0e82a16))
+
+- **#68**: --since accepts 7d, 2w, YYYY-MM-DD, and date ranges
+  ([`434d7c4`](https://github.com/jacquardlabs/cctx/commit/434d7c448406e0a5465380ed395e1fadaa1c0db1))
+
+- **#69**: Annotate costs as estimates (~85–95%) in terminal and HTML output
+  ([`5a49889`](https://github.com/jacquardlabs/cctx/commit/5a49889bd43555d30a58c2b78eddf6acbb0d8e97))
+
+- **#70**: Cctx watch — live waste signals during an active session
+  ([`f533a13`](https://github.com/jacquardlabs/cctx/commit/f533a13e1f087da00457ce7b8215934f20c403a2))
+
+- **#72**: Cctx autopsy --github-summary writes findings to GitHub Actions job summary
+  ([`df91256`](https://github.com/jacquardlabs/cctx/commit/df91256b58b75a9bbe9594a000b00dee2ac2fbc5))
+
+- **#73**: Cctx GitHub Action (composite) + --fail-on-findings flag
+  ([`9229584`](https://github.com/jacquardlabs/cctx/commit/9229584ea192ce1b1ee6718721d981cba0ca13e0))
+
+### Refactoring
+
+- Consolidate KIND_LABEL, fix private import, clean up watcher tests
+  ([`31ad4d7`](https://github.com/jacquardlabs/cctx/commit/31ad4d75885eed9c8238c4eb1c08bd5d1ba51a15))
+
+
+## v0.1.0 (2026-05-16)
+
+- Initial Release

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/CLAUDE.md

@@ -27,8 +27,8 @@ Parser           ← dependency-free; takes a path, returns SessionTrace
 Tokenizer        ← only place that imports anthropic; offline-mode safe for CI
   ↓
 Diagnostician    ← per-turn investigation: inflection detection + pattern
-                   classifiers (retry loop, scope creep, stale context).
-                   Produces a Diagnosis.
+                   classifiers (retry loop, scope creep, stale context,
+                   tool thrash, dead end). Produces a Diagnosis.
   ↓
 Recommender      ← turns Findings into Patches: copy-pasteable CLAUDE.md /
                    rule / skill diffs, evidence-backed when cross-session.
@@ -43,30 +43,34 @@ Exporters        ← jsonl, csv.
 
 ```
 cctx/
-├── cli.py              # click + rich-click; routes to autopsy / trace / export
+├── cli.py              # click + rich-click; routes all subcommands
 ├── parsers/
 │   └── claude_code.py  # SHIPPED. Parse ~/.claude JSONL logs.
-│                       # Spec: docs/superpowers/specs/2026-05-12-claude-code-parser-design.md
 ├── tokenizer.py        # SHIPPED. anthropic.count_tokens wrapper; CCTX_OFFLINE heuristic.
 ├── models.py           # SHIPPED. Turn, ToolUse, ToolResult, Usage, Attachment,
-│                       # RawToolResultFile, SessionTrace + group_into_exchanges().
-│                       # M2 extends with Finding, Patch, Diagnosis.
+│                       # RawToolResultFile, SessionTrace, Finding, Patch, Diagnosis,
+│                       # KIND_LABEL, AggregateReport.
 ├── diagnostician/
 │   ├── __init__.py     # public: run(trace) -> Diagnosis
 │   ├── inflection.py   # detect the turn where the session diverged
 │   ├── patterns/
 │   │   ├── retry_loop.py
 │   │   ├── scope_creep.py
-│   │   └── stale_context.py
+│   │   ├── stale_context.py
+│   │   ├── tool_thrash.py
+│   │   └── dead_end.py
 │   └── aggregate.py    # cross-session pattern aggregator (--since mode)
 ├── recommender/
 │   ├── claude_md.py    # Finding -> Patch (CLAUDE.md diff proposals)
 │   └── evidence.py     # session-count + dollar evidence accumulation
-├── harvest.py          # SHIPPED. apply_patch, preview_patches, apply_patches —
-│                       # append-only, idempotent CLAUDE.md patching with
-│                       # fingerprint-based deduplication.
+├── harvest.py          # SHIPPED. apply_patch, preview_patches, apply_patches, check_claude_md —
+│                       # append-only, idempotent patching with fingerprint-based deduplication.
+│                       # v2: patches route to any .md target (rules/, skills/).
+├── discovery.py        # SHIPPED. list_projects(), latest_session() — navigate ~/.claude/projects/
+├── watcher.py          # SHIPPED. cctx watch — poll active session, surface findings live.
 ├── renderers/
-│   ├── terminal.py     # rich rendering of a Diagnosis
+│   ├── terminal.py     # rich rendering of Diagnosis, AggregateReport, projects, sessions
+│   ├── github.py       # GitHub Actions job summary renderer (--github-summary)
 │   ├── report.py       # Jinja2 HTML report (cctx autopsy --html)
 │   └── trace_tui.py    # textual TUI with autopsy findings overlaid
 └── exporters/
@@ -102,16 +106,16 @@ These came out of the brief, the parser brainstorming session, and the autopsy p
 
 1. **M0 — Project setup.** SHIPPED. (#1)
 2. **M1 — Foundation.** SHIPPED — parser, tokenizer, models, fixtures, CI. (#2–#6, plus PR #38)
-3. **M2 — Autopsy v0.** SHIPPED — single-session diagnosis + cross-session pattern detection. The wedge product. (#9, #10, #40–#49)
+3. **M2 — Autopsy v0.** SHIPPED — single-session diagnosis + cross-session pattern detection. (#9, #10, #40–#49)
 4. **M3 — Trace TUI** with autopsy overlay. SHIPPED. (PR #57)
 5. **M4 — Export.** SHIPPED — jsonl + csv exporters (html moved to autopsy --html; json deferred). (PR #54)
-6. **M5 — Harvest v1.** SHIPPED — CLAUDE.md target only in v0; promote autopsy findings to durable CLAUDE.md diffs. (PR #56)
-7. **M6 — Release v0.1.0.** Release prep underway — README, PRODUCT.md, DESIGN.md, version bump, PyPI publish. (#31, #32)
+6. **M5 — Harvest v1.** SHIPPED — CLAUDE.md target only; promote autopsy findings to durable CLAUDE.md diffs. (PR #56)
+7. **M6 — Release v0.1.0.** SHIPPED — README, version bump, PyPI publish, GitHub Action (composite), session discovery (`cctx ls`). (#31, #32, #62, #73)
+8. **M7 — v0.2.0.** SHIPPED — `cctx watch` live mode, `--github-summary`, `--fail-on-findings`, harvest v2 multi-target, `harvest --check`, tool-thrash + dead-end classifiers, `--since` string formats, interactive aggregate drill-down.
 
 Future, not yet milestoned:
-- **Memory hygiene** (`cctx harvest --check`) — audit existing CLAUDE.md and memory files for staleness / contradictions / dead skills.
-- **Live mode** (`cctx watch`) — filesystem watcher on `~/.claude/projects` to surface waste signals during a session.
-- **Cross-agent layer** — emit the same captured knowledge as `.cursorrules`, `AGENTS.md`, `.windsurfrules`, GitHub Copilot instructions.
+- **Cross-agent layer** — emit findings as `.cursorrules`, `AGENTS.md`, `.windsurfrules`, GitHub Copilot instructions.
+- **`--format json` on `export`** — deferred; no milestone.
 
 ## Design docs
 

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 0.1.0
+Version: 1.0.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT
@@ -48,9 +48,10 @@ pip install cctx-cli
 ```bash
 cctx ls                   # find your sessions
 cctx autopsy --latest     # diagnose the most recent one
+cctx watch                # live signals during an active session
 ```
 
-cctx is a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
+cctx is primarily a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. `cctx watch` runs during a session and surfaces patterns as they happen. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
 
 ## Commands
 
@@ -97,6 +98,13 @@ cctx harvest ~/Projects/myapp --since 7
 
 Turns autopsy findings into copy-pasteable `CLAUDE.md` additions. Patches are idempotent — running harvest twice on the same session won't duplicate entries. Use `--target-dir DIR` to specify which directory's `CLAUDE.md` to patch (default: current working directory).
 
+```bash
+# Audit existing CLAUDE.md for dead file references and empty sections
+cctx harvest . --check
+```
+
+`--check` reads the target `CLAUDE.md` without writing anything. Exits 1 if issues are found (dead file references, dead skill references, empty sections), 0 if clean. Useful as a CI step when `CLAUDE.md` is committed to the repo.
+
 ### `cctx export` — export session data
 
 ```bash
@@ -112,6 +120,15 @@ cctx export ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --format j
 
 Dumps session analysis as JSONL (one object per session) or CSV (one row per turn) for use in external tools.
 
+### `cctx watch` — live waste signals
+
+```bash
+cctx watch                    # watch the active session in cwd's project
+cctx watch ~/Projects/myapp   # watch a specific project
+```
+
+Tails the active session as it progresses and prints a single-line alert each time a new waste pattern is detected. Exits after 30s of session inactivity or Ctrl+C.
+
 ### `cctx trace` — interactive TUI
 
 ```bash
@@ -154,6 +171,46 @@ Claude Code writes logs to `~/.claude/projects/<encoded-path>/<session-id>.jsonl
 
 `cctx ls` handles discovery automatically — you don't need to navigate the encoded directory structure by hand.
 
+## Using cctx in CI
+
+cctx is primarily a local forensic tool — it reads session logs from `~/.claude/projects/` on your machine. Those logs are personal conversation history and should not be committed to git or uploaded as build artifacts.
+
+**The one case where cctx belongs in CI:** when Claude Code itself runs inside a GitHub Actions job (agentic PR workflows, automated coding steps). In that case the JSONL logs are written on the runner during the job and cctx can analyse them as a post-step.
+
+### GitHub Action (recommended)
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    # ... your agentic workflow config
+
+- uses: jacquardlabs/cctx@v0
+  with:
+    fail_on_findings: false   # set true to gate the job on waste findings
+    github_summary: true      # write findings to the job summary UI
+```
+
+The action auto-discovers the most recent Claude Code session written on the runner. It does not accept arbitrary file paths — that pattern would require committing session logs to the repo, which you should not do.
+
+### Manual step
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    # ... your agentic workflow config
+
+- name: Analyse session
+  run: pipx run cctx-cli autopsy --latest . --github-summary
+```
+
+`--github-summary` appends a markdown findings report to the GitHub Actions job summary UI. Add `--fail-on-findings` to exit 1 when waste patterns are detected.
+
+Commands that make sense as CI steps:
+- `cctx autopsy` — diagnose the session that just ran
+- `cctx export` — archive structured findings as a build artifact
+
+`cctx harvest` requires session logs AND writes to `CLAUDE.md` — neither step maps cleanly to CI. Run it locally after a session.
+
 ## License
 
 MIT

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/PRODUCT.md

@@ -45,65 +45,54 @@ Pattern classifiers are heuristics, not LLM calls. The same session file produce
 **6. Small surface, deep on each command.**
 Four commands. No command is shallow. Users should be able to learn the product in an afternoon and trust what it tells them.
 
-## Feature map (v0.1.0)
+## Feature map (v0.2.0)
 
 ### Shipped
 
-| Feature | Command | Status |
+| Feature | Command | Notes |
 |---|---|---|
-| Single-session diagnosis | `cctx autopsy <session>` | Shipped (M2) |
-| Cross-session pattern detection | `cctx autopsy <project> --since N` | Shipped (M2) |
-| HTML report | `cctx autopsy <session> --html FILE` | Shipped (M2/PR#59) |
-| Session trace TUI | `cctx trace <session>` | Shipped (M3) |
-| JSONL export | `cctx export <session> --format jsonl` | Shipped (M4) |
-| CSV export | `cctx export <session> --format csv` | Shipped (M4) |
-| Harvest (CLAUDE.md patcher) | `cctx harvest <session>` | Shipped (M5) |
-| Cross-session harvest | `cctx harvest <project> --since N` | Shipped (M5) |
-
-### Pattern classifiers (v0.1.0)
+| Single-session diagnosis | `cctx autopsy <session>` | M2 |
+| Cross-session pattern detection | `cctx autopsy <project> --since N` | M2 |
+| `--since` string formats | `--since 7d`, `2w`, `2026-05-01`, date ranges | M6+ |
+| Interactive aggregate drill-down | select pattern → per-session detail | M6+ |
+| HTML report | `cctx autopsy <session> --html FILE` | M2 |
+| GitHub Actions job summary | `cctx autopsy --github-summary` | M6+ |
+| CI fail gate | `cctx autopsy --fail-on-findings` | M6+ |
+| GitHub Action (composite) | `jacquardlabs/cctx@v1` in workflow | M6+ |
+| Session trace TUI | `cctx trace <session>` | M3 |
+| JSONL export | `cctx export <session> --format jsonl` | M4 |
+| CSV export | `cctx export <session> --format csv` | M4 |
+| Harvest (CLAUDE.md patcher) | `cctx harvest <session>` | M5 |
+| Harvest v2 (multi-target) | patches to `.claude/rules/`, `.claude/skills/` | M6+ |
+| Harvest --check | `cctx harvest <dir> --check` — audit for dead refs | M6+ |
+| Cross-session harvest | `cctx harvest <project> --since N` | M5 |
+| Session discovery | `cctx ls` / `cctx autopsy --latest` | M6+ |
+| Live waste signals | `cctx watch <project>` | M6+ |
+
+### Pattern classifiers (v0.2.0)
 
 | Pattern | Status |
 |---|---|
 | Retry loop | Shipped |
 | Scope creep | Shipped |
 | Stale context | Shipped |
-| Dead-end exploration | Not shipped in v0 |
-| Tool thrashing | Not shipped in v0 |
-
-### NOT in v0.1.0
-
-- `--format json` and `--format html` on `export` (html moved to `autopsy --html`; json not scheduled)
-- `--since` string formats (`7d`, `2w`, date ranges, `--until`, `--top N`) — accepts integer days only
-- Patch targets other than `CLAUDE.md` (rules, skills, ADR — v1+)
-- Interactive aggregate drill-down ("press N to inspect pattern") — read-only in v0
-- `cctx ls` / session discovery helper
-- Dead-end and tool-thrash classifiers
+| Dead-end exploration | Shipped (v0.2.0) |
+| Tool thrashing | Shipped (v0.2.0) |
 
 ## What we are NOT building
 
 - A SaaS or cloud product
 - An agent (cctx reads logs; it does not call the Anthropic API except optionally for token counting)
-- A real-time watcher (v2+ roadmap item)
-- Multi-provider support (v3+ roadmap item)
+- Multi-provider support (Claude Code only in v0/v1)
 - A fork-and-replay debugger
 - A general eval or testing framework
 
-## Known problems (as of 2026-05-15)
-
-**Release blockers for v0.1.0 (M6):**
-
-1. **No README.md.** `pyproject.toml` uses `cctx-project-brief.md` as the readme. The brief contains architecture diagrams and an internal "First session prompt" that should not be on PyPI. A user-facing README.md is required before publish.
-
-2. **`pyproject.toml` description is inaccurate.** Current: "Profile, debug, and optimize Claude Code and Agent SDK sessions." Accurate: "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md."
-
-3. **Version is `0.0.1`.** M6 requires bumping to `0.1.0`.
-
-4. **Brief example outputs show unshipped features.** The `cctx-project-brief.md` (which currently IS the readme) shows 5 pattern classifiers, 4 export formats, string `--since` arguments, a `Verdict` headline, and interactive aggregate output. None of these are accurate for the shipped CLI. Before PyPI publish, either ship them or update the brief.
+## Known problems (as of 2026-05-16)
 
-**Active gaps (non-blocking for v0.1.0 but worth tracking):**
+**Active gaps (non-blocking for v0.2.0 but worth tracking):**
 
-5. **Cost approximation honesty not surfaced in output.** The terminal renderer shows `$X.XX` total cost with no confidence annotation. The brief says "The system internals slice is honest; don't pretend to be exact" — this is a principle not yet expressed to users in output.
+1. **`cctx watch` polling is simple.** Polls every 1s and re-runs classifiers on any file growth. Does not debounce or use `fsevents`/`inotify`. Fine for v0 but will chatter on active sessions.
 
-6. **No session discovery helper.** Users must manually navigate URL-encoded project directories in `~/.claude/projects/` to find session files. First-run friction.
+2. **`--format json` on `export` not shipped.** `--html` moved to `autopsy --html`; `json` format on the `export` subcommand is still deferred.
 
-7. **Aggregate output is read-only.** The brief's example shows an interactive aggregate view. Shipped aggregate is a static table. The interactive drill-down is a meaningful UX gap that the brief implicitly promises.
+3. **Cross-agent layer not started.** Emitting findings as `.cursorrules`, `AGENTS.md`, `.windsurfrules`, or GitHub Copilot instructions is a roadmap item with no milestone yet.

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/README.md

@@ -28,9 +28,10 @@ pip install cctx-cli
 ```bash
 cctx ls                   # find your sessions
 cctx autopsy --latest     # diagnose the most recent one
+cctx watch                # live signals during an active session
 ```
 
-cctx is a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
+cctx is primarily a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. `cctx watch` runs during a session and surfaces patterns as they happen. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
 
 ## Commands
 
@@ -77,6 +78,13 @@ cctx harvest ~/Projects/myapp --since 7
 
 Turns autopsy findings into copy-pasteable `CLAUDE.md` additions. Patches are idempotent — running harvest twice on the same session won't duplicate entries. Use `--target-dir DIR` to specify which directory's `CLAUDE.md` to patch (default: current working directory).
 
+```bash
+# Audit existing CLAUDE.md for dead file references and empty sections
+cctx harvest . --check
+```
+
+`--check` reads the target `CLAUDE.md` without writing anything. Exits 1 if issues are found (dead file references, dead skill references, empty sections), 0 if clean. Useful as a CI step when `CLAUDE.md` is committed to the repo.
+
 ### `cctx export` — export session data
 
 ```bash
@@ -92,6 +100,15 @@ cctx export ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --format j
 
 Dumps session analysis as JSONL (one object per session) or CSV (one row per turn) for use in external tools.
 
+### `cctx watch` — live waste signals
+
+```bash
+cctx watch                    # watch the active session in cwd's project
+cctx watch ~/Projects/myapp   # watch a specific project
+```
+
+Tails the active session as it progresses and prints a single-line alert each time a new waste pattern is detected. Exits after 30s of session inactivity or Ctrl+C.
+
 ### `cctx trace` — interactive TUI
 
 ```bash
@@ -134,6 +151,46 @@ Claude Code writes logs to `~/.claude/projects/<encoded-path>/<session-id>.jsonl
 
 `cctx ls` handles discovery automatically — you don't need to navigate the encoded directory structure by hand.
 
+## Using cctx in CI
+
+cctx is primarily a local forensic tool — it reads session logs from `~/.claude/projects/` on your machine. Those logs are personal conversation history and should not be committed to git or uploaded as build artifacts.
+
+**The one case where cctx belongs in CI:** when Claude Code itself runs inside a GitHub Actions job (agentic PR workflows, automated coding steps). In that case the JSONL logs are written on the runner during the job and cctx can analyse them as a post-step.
+
+### GitHub Action (recommended)
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    # ... your agentic workflow config
+
+- uses: jacquardlabs/cctx@v0
+  with:
+    fail_on_findings: false   # set true to gate the job on waste findings
+    github_summary: true      # write findings to the job summary UI
+```
+
+The action auto-discovers the most recent Claude Code session written on the runner. It does not accept arbitrary file paths — that pattern would require committing session logs to the repo, which you should not do.
+
+### Manual step
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    # ... your agentic workflow config
+
+- name: Analyse session
+  run: pipx run cctx-cli autopsy --latest . --github-summary
+```
+
+`--github-summary` appends a markdown findings report to the GitHub Actions job summary UI. Add `--fail-on-findings` to exit 1 when waste patterns are detected.
+
+Commands that make sense as CI steps:
+- `cctx autopsy` — diagnose the session that just ran
+- `cctx export` — archive structured findings as a build artifact
+
+`cctx harvest` requires session logs AND writes to `CLAUDE.md` — neither step maps cleanly to CI. Run it locally after a session.
+
 ## License
 
 MIT

cctx_cli-1.0.0/action.yml

@@ -0,0 +1,39 @@
+name: 'cctx'
+description: 'Analyse Claude Code sessions for waste patterns, cost attribution, and CLAUDE.md recommendations'
+author: 'Jacquard Labs'
+
+branding:
+  icon: 'activity'
+  color: 'blue'
+
+inputs:
+  fail_on_findings:
+    description: 'Exit 1 if the session has waste findings'
+    required: false
+    default: 'false'
+  github_summary:
+    description: 'Write findings to the GitHub Actions job summary'
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install cctx
+      shell: bash
+      run: pipx install cctx-cli
+
+    - name: Analyse session
+      shell: bash
+      env:
+        FAIL_ON_FINDINGS: ${{ inputs.fail_on_findings }}
+        GITHUB_SUMMARY: ${{ inputs.github_summary }}
+      run: |
+        ARGS="autopsy --latest ."
+        if [ "$GITHUB_SUMMARY" = "true" ]; then
+          ARGS="$ARGS --github-summary"
+        fi
+        if [ "$FAIL_ON_FINDINGS" = "true" ]; then
+          ARGS="$ARGS --fail-on-findings"
+        fi
+        cctx $ARGS

{cctx_cli-0.1.0 → cctx_cli-1.0.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"