chsum 1.0.0__tar.gz

chsum-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+.DS_Store

chsum-1.0.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# chsum
+
+Single-file, stdlib-only Python tool (`chsum.py`) turning Claude Code transcripts
+into work logs and reload-ready context. `README.md` is the user-facing doc; this
+is what you need before changing the code.
+
+Installed with pipx (`pipx install --editable .` here), so `chsum.py` in this
+checkout *is* what runs. No shell alias — an alias only exists in an interactive
+shell, and this has to work from scripts, hooks, and agents. `dependencies` stays
+empty; `claude-history` is a runtime requirement but a separate binary.
+
+## Nothing here may invent anything
+
+Every line of output is copied verbatim or computed. **Why:** output gets pasted
+into future sessions, where a plausible-but-wrong sentence becomes ground truth.
+A digest that's merely *usually* right is worse than none, because nothing
+downstream can tell.
+
+**Applying it:** for any new section, ask where each value came from. If the
+answer involves inference or summarising, it belongs behind the `Summariser`
+seam, whose output is additive and sits *beneath* the quotes that would
+contradict it. Transcript text is blockquoted so a quoted `## Summary` can't
+forge a section.
+
+## Two ref schemes, one of them ours
+
+- `ch_<32 hex>` — claude-history's, reimplemented in `ch_ref_for_path` from a
+  versioned internal. Derived values are verified against the uuid they report
+  (`resolve_ref`). If that check fires, their scheme changed.
+- `ch_…/<agent-id>` — chsum's own, for subagents. claude-history has no per-agent
+  ref: `--subagents` inlines agent messages into the parent read untagged.
+
+Never print a chsum agent ref inside a suggested `claude-history agent read`
+command; it won't resolve. Agent digests point at the sidecar path.
+
+## Text sources
+
+`read_messages` shells out to `claude-history agent read` — it strips tool sludge
+and returns `mN` ordinals and durable `ma_` anchors.
+
+`messages_from_jsonl` parses raw JSONL and exists **only** for sidecars. It can't
+mint anchors, so agent digests have none. Don't fix this by generating
+anchor-shaped strings.
+
+`extract_meta` is pure JSONL, no subprocesses — that's what keeps the listing and
+`journal` fast (195 sessions in ~3s). Anything that shells out per session belongs
+in the digest path, not the listing path.
+
+## Layout
+
+```
+~/.claude/projects/<project-dir-name>/
+  <session-uuid>.jsonl                          the conversation
+  <session-uuid>/subagents/agent-<id>.jsonl     one per subagent
+  <session-uuid>/subagents/agent-<id>.meta.json agentType, model, description, spawnDepth
+```
+
+Sidecars can be absent (older/pruned) or outnumber the visible `Agent` calls (an
+agent spawning its own), so `Meta.agent_count` takes the larger count.
+
+## Delegated work is the session's work
+
+Subagent edits and commands fold into the parent's totals. **Why:** otherwise a
+session that delegated everything reads as no activity — usually it was the
+busiest. Prompts stay parent-only. Files no parent turn touched are marked
+`(agent)`.
+
+## Releasing
+
+Version lives in `pyproject.toml` and `skills/chsum/SKILL.md` frontmatter. Both
+ship, so `publish.yml` refuses a tag that disagrees with either.
+
+```sh
+# bump both, then
+git tag v1.0.1 && git push origin v1.0.1
+```
+
+The tag publishes to PyPI via trusted publishing (no stored token) and asks
+[InDate/indate-tools](https://github.com/InDate/indate-tools) to repin. The
+marketplace opens a PR: publishing and pushing an update to installed users are
+separate decisions.
+
+## Conventions
+
+- Comments explain *why*, briefly. Several behaviours look wrong until you know
+  the reason (idle-gap duration, ambiguous anchors, two `outline` shapes).
+- Output is token-budgeted: it lands in future context windows. New sections go
+  through `_plural`/`_bullets`/`_clip`/`_quote` so clipping stays consistent and
+  truncation is always marked, never silent.
+- Widen an existing command before adding one. The surface is deliberately small:
+  `sessions` (default), `last`, `find`, `digest`, `context`, `journal`.

chsum-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: chsum
+Version: 1.0.0
+Summary: Work logs and reload-ready context from Claude Code conversations. Deterministic: no model, nothing invented.
+Author: Joshua
+License: MIT
+Keywords: claude,claude-code,context,transcripts,work-log
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# chsum
+
+Work logs and reload-ready context from your Claude Code conversations.
+
+**Nothing here is generated by a model.** Every line of output is either copied
+verbatim from a transcript or computed from it, so nothing can be invented. That
+matters because the output is designed to be pasted back into a future Claude
+session, where a plausible-but-wrong sentence would become ground truth.
+
+## The idea
+
+Your own prompts already are a faithful record of what you were trying to do.
+Extracted in order they read as the story of the session — most of what a summary
+would have said, without the risk:
+
+```markdown
+**m1**
+> can you open a chrome page to the site, it is running on 3000
+
+**m7**
+> sherpa-onnx-tts.worker.js:267 [Sherpa Worker] Initialization failed…
+
+**m137**
+> when I speed up the text to speech, it ends up sounding like a chipmunk
+
+**m153**
+> The toolbar is no longer working to slow it down or speed it up live
+```
+
+Blockquoting is functional, not cosmetic: a quoted reply containing `## Summary`
+would otherwise forge a section of the digest. Everything else — dates, duration,
+branch, files, commands — is parsed straight out of the transcript.
+
+## Requirements
+
+- [`claude-history`](https://github.com/) on your `PATH`
+- Python 3.10+. No third-party packages, no model, no network.
+
+## Install
+
+```sh
+pipx install chsum            # from a checkout: pipx install .
+```
+
+Or as a Claude Code plugin, which brings the skill with it:
+
+```
+/plugin marketplace add InDate/indate-tools
+/plugin install chsum@indate-tools
+```
+
+The plugin carries the skill; the `chsum` command still comes from pipx.
+
+pipx, not `pip install --user`: chsum is an application, so it gets its own venv
+and one symlink on `PATH`. `pipx install --editable .` while working on it.
+
+A real command rather than a shell alias, because an alias doesn't exist for
+scripts, hooks, or agents.
+
+## Usage
+
+```sh
+chsum                                          # every session in this project, one line each
+chsum -n 5                                     # just the five most recent
+chsum --since 7d                               # only the last week
+chsum --all                                    # across every project
+chsum last                                     # most recent real session, as context
+chsum last -n 2                                # the one before that
+chsum find "text to speech playback speed"     # locate a conversation
+chsum digest <ch_ref>                          # write a digest file
+chsum digest <ch_ref> --stdout                 # print it instead
+chsum digest --file path/to/session.jsonl      # address by file
+chsum context <ch_ref>                         # reload artifact, for pasting into Claude
+chsum context <ch_ref>/<agent-id>              # one subagent's own digest
+chsum journal --since 7d                       # work log for this project
+chsum journal --since 2w --all                 # across every project
+```
+
+Bare `chsum` lists the project's sessions, newest activity first:
+
+```
+ref                                  date        dur    prompts  files  agents         title
+ch_c120431a267b202aebf0b38f6c3c1b69  2026-08-06  5h38m  78       14     -              Plan 3D house model…
+ch_da4e99d42e5efab11ebdedc22fb65145  2026-08-05  3h03m  30       12     5              Set up cdp-tools server
+ch_b99f11b7c257dafc8b93f53480ba3804  2026-08-05  6s     1        0      -       empty  (untitled)
+```
+
+Listing is the default because picking is the common case, and "most recent" is
+often a session you abandoned after one prompt. Those are flagged `empty` rather
+than hidden — knowing a session was a dead end is the answer to "where did that
+work go". Activity means a file edited, a notable command, an agent spawned, or a
+second prompt.
+
+`chsum last` is `chsum context` on the most recent session with activity, ordered
+by last activity so one you resumed yesterday beats one you started last week.
+Run from inside Claude Code, the session doing the running is excluded.
+
+Everything scopes to the current project; `--all` widens. Digests land in
+`~/.claude/chsum/digests/<uuid>.md` (`--out` to change).
+
+### Subagents
+
+A subagent's edits and commands fold into its parent's totals — otherwise a
+session that delegated everything reads as no activity. Files no parent turn
+touched are marked `(agent)`. Each agent gets a line in **Delegated**, and an
+address:
+
+```sh
+chsum context ch_da4e99d42e5efab11ebdedc22fb65145/a728cd49179f1a356
+```
+
+Its task, files, commands, and last message. Everything past the one-line summary
+is fetched on demand, so a heavily-delegated session doesn't produce a digest
+nobody wants to read.
+
+`<parent-ref>/<agent-id>` resolves to `<uuid>/subagents/agent-<id>.jsonl`. chsum's
+own scheme, not claude-history's — see *Notes on correctness*.
+
+### Search modes
+
+`--hybrid` (default) and `--semantic` are best for conceptual recall but are slow:
+tens of seconds warm, and **several minutes on the very first run** while the
+embedding index builds. Use `--lexical` (sub-second) for identifiers, filenames,
+and error strings, or `--exact` for exact tokens.
+
+## What a digest contains
+
+| Section | Source |
+|---|---|
+| Frontmatter — ref, title, project, branch, start, duration, counts | computed |
+| **What I asked for** — your prompts, verbatim, in order | copied |
+| **Files changed** / **Commands run** | parsed from tool calls |
+| **Delegated** — one line per subagent, with its address | parsed from sidecars |
+| **Where I left off** — last prompt and last reply, verbatim | copied |
+| — *found by two separate backward scans, so they may be far apart and are not a Q&A pair* | |
+| **Drill down** — `mN → ma_…` anchor map | computed |
+
+An agent digest has the same shape minus the intent trail — an agent gets one
+instruction, so **Task** is a single block — and no anchor map (see below).
+
+Output is budgeted, because it lands in a future context window: quotes clip,
+lists cap. Every truncation is marked (`[+N chars, read the anchor]`, `…and N
+more`) so you always know when you're seeing a fragment.
+
+## Notes on correctness
+
+Several things here are non-obvious and were established by measuring, not assuming:
+
+- **Duration excludes idle time.** Sessions get resumed hours or days later, so
+  first-record-to-last-record wildly overstates effort — one session in the corpus
+  reads as 92 hours. Gaps over 30 minutes are treated as "walked away".
+- **Anchors are content-addressed, so they can collide.** Two messages with
+  byte-identical text (`[Request interrupted by user]`, say) share one anchor, and
+  `read --anchor` then fails with `ambiguous-ref`. Ambiguous anchors are detected
+  and never published — every anchor a digest prints resolves to exactly one message.
+- **Most "user" records aren't from you.** They're tool results, interrupts, and
+  harness scaffolding. Those are filtered out; `prompts:` counts what you typed.
+- **`outline` has two output shapes** — segment ranges for long conversations,
+  per-message lines for short ones. Both are handled.
+- **Subagent transcripts** aren't conversations in their own right and never appear
+  in the listing, matching `claude-history`'s discovery rules.
+- **`claude-history` has no per-agent ref.** `--subagents` inlines agent messages
+  into the parent read untagged, so they can't be sliced apart. Sidecars are
+  parsed directly, which is why agent digests carry no `ma_` anchors — those are
+  claude-history's to mint, and a fabricated one is worse than none.
+- **An agent's last message isn't necessarily its conclusion**, so the section is
+  *Last thing it said*. An interrupted agent ends mid-thought.
+- **Agent counts take the larger of two sources** — `Agent`/`Task` calls in the
+  parent, and sidecars on disk. Sidecars go missing; an agent that spawns its own
+  outnumbers the visible calls.
+- **Scratch paths** (`/tmp`, scratchpads, plan files) are excluded from "files
+  changed" so the work log shows real project changes.
+
+## Adding prose later
+
+There is a deliberately unimplemented `Summariser` seam at the bottom of
+`chsum.py`. A TL;DR is the one thing extraction can't produce; the intended order
+is Haiku first to set a quality bar and a price, then a local MLX backend measured
+against it.
+
+The rule for any backend: it gets the already-extracted material, and its output is
+**additive** — layered on top of the verbatim record so a wrong sentence can always
+be checked against the quotes beneath it.
+
+If you do go local, note that the model in `mlx-community/DeepSeek-R1-Distill-Qwen-14B-MLX`
+is **139 GB** of unquantised weights. The 4-bit build is `…-14B-4bit` at 8.32 GB. On a
+16 GB machine the binding constraint is KV cache, not context length: this architecture
+costs 192 KB/token at fp16 (96 KB with `kv_bits=8`), so after 8.32 GB of weights you get
+roughly 18k–36k tokens of usable input, not the 131k the config advertises.

chsum-1.0.0/README.md

@@ -0,0 +1,189 @@
+# chsum
+
+Work logs and reload-ready context from your Claude Code conversations.
+
+**Nothing here is generated by a model.** Every line of output is either copied
+verbatim from a transcript or computed from it, so nothing can be invented. That
+matters because the output is designed to be pasted back into a future Claude
+session, where a plausible-but-wrong sentence would become ground truth.
+
+## The idea
+
+Your own prompts already are a faithful record of what you were trying to do.
+Extracted in order they read as the story of the session — most of what a summary
+would have said, without the risk:
+
+```markdown
+**m1**
+> can you open a chrome page to the site, it is running on 3000
+
+**m7**
+> sherpa-onnx-tts.worker.js:267 [Sherpa Worker] Initialization failed…
+
+**m137**
+> when I speed up the text to speech, it ends up sounding like a chipmunk
+
+**m153**
+> The toolbar is no longer working to slow it down or speed it up live
+```
+
+Blockquoting is functional, not cosmetic: a quoted reply containing `## Summary`
+would otherwise forge a section of the digest. Everything else — dates, duration,
+branch, files, commands — is parsed straight out of the transcript.
+
+## Requirements
+
+- [`claude-history`](https://github.com/) on your `PATH`
+- Python 3.10+. No third-party packages, no model, no network.
+
+## Install
+
+```sh
+pipx install chsum            # from a checkout: pipx install .
+```
+
+Or as a Claude Code plugin, which brings the skill with it:
+
+```
+/plugin marketplace add InDate/indate-tools
+/plugin install chsum@indate-tools
+```
+
+The plugin carries the skill; the `chsum` command still comes from pipx.
+
+pipx, not `pip install --user`: chsum is an application, so it gets its own venv
+and one symlink on `PATH`. `pipx install --editable .` while working on it.
+
+A real command rather than a shell alias, because an alias doesn't exist for
+scripts, hooks, or agents.
+
+## Usage
+
+```sh
+chsum                                          # every session in this project, one line each
+chsum -n 5                                     # just the five most recent
+chsum --since 7d                               # only the last week
+chsum --all                                    # across every project
+chsum last                                     # most recent real session, as context
+chsum last -n 2                                # the one before that
+chsum find "text to speech playback speed"     # locate a conversation
+chsum digest <ch_ref>                          # write a digest file
+chsum digest <ch_ref> --stdout                 # print it instead
+chsum digest --file path/to/session.jsonl      # address by file
+chsum context <ch_ref>                         # reload artifact, for pasting into Claude
+chsum context <ch_ref>/<agent-id>              # one subagent's own digest
+chsum journal --since 7d                       # work log for this project
+chsum journal --since 2w --all                 # across every project
+```
+
+Bare `chsum` lists the project's sessions, newest activity first:
+
+```
+ref                                  date        dur    prompts  files  agents         title
+ch_c120431a267b202aebf0b38f6c3c1b69  2026-08-06  5h38m  78       14     -              Plan 3D house model…
+ch_da4e99d42e5efab11ebdedc22fb65145  2026-08-05  3h03m  30       12     5              Set up cdp-tools server
+ch_b99f11b7c257dafc8b93f53480ba3804  2026-08-05  6s     1        0      -       empty  (untitled)
+```
+
+Listing is the default because picking is the common case, and "most recent" is
+often a session you abandoned after one prompt. Those are flagged `empty` rather
+than hidden — knowing a session was a dead end is the answer to "where did that
+work go". Activity means a file edited, a notable command, an agent spawned, or a
+second prompt.
+
+`chsum last` is `chsum context` on the most recent session with activity, ordered
+by last activity so one you resumed yesterday beats one you started last week.
+Run from inside Claude Code, the session doing the running is excluded.
+
+Everything scopes to the current project; `--all` widens. Digests land in
+`~/.claude/chsum/digests/<uuid>.md` (`--out` to change).
+
+### Subagents
+
+A subagent's edits and commands fold into its parent's totals — otherwise a
+session that delegated everything reads as no activity. Files no parent turn
+touched are marked `(agent)`. Each agent gets a line in **Delegated**, and an
+address:
+
+```sh
+chsum context ch_da4e99d42e5efab11ebdedc22fb65145/a728cd49179f1a356
+```
+
+Its task, files, commands, and last message. Everything past the one-line summary
+is fetched on demand, so a heavily-delegated session doesn't produce a digest
+nobody wants to read.
+
+`<parent-ref>/<agent-id>` resolves to `<uuid>/subagents/agent-<id>.jsonl`. chsum's
+own scheme, not claude-history's — see *Notes on correctness*.
+
+### Search modes
+
+`--hybrid` (default) and `--semantic` are best for conceptual recall but are slow:
+tens of seconds warm, and **several minutes on the very first run** while the
+embedding index builds. Use `--lexical` (sub-second) for identifiers, filenames,
+and error strings, or `--exact` for exact tokens.
+
+## What a digest contains
+
+| Section | Source |
+|---|---|
+| Frontmatter — ref, title, project, branch, start, duration, counts | computed |
+| **What I asked for** — your prompts, verbatim, in order | copied |
+| **Files changed** / **Commands run** | parsed from tool calls |
+| **Delegated** — one line per subagent, with its address | parsed from sidecars |
+| **Where I left off** — last prompt and last reply, verbatim | copied |
+| — *found by two separate backward scans, so they may be far apart and are not a Q&A pair* | |
+| **Drill down** — `mN → ma_…` anchor map | computed |
+
+An agent digest has the same shape minus the intent trail — an agent gets one
+instruction, so **Task** is a single block — and no anchor map (see below).
+
+Output is budgeted, because it lands in a future context window: quotes clip,
+lists cap. Every truncation is marked (`[+N chars, read the anchor]`, `…and N
+more`) so you always know when you're seeing a fragment.
+
+## Notes on correctness
+
+Several things here are non-obvious and were established by measuring, not assuming:
+
+- **Duration excludes idle time.** Sessions get resumed hours or days later, so
+  first-record-to-last-record wildly overstates effort — one session in the corpus
+  reads as 92 hours. Gaps over 30 minutes are treated as "walked away".
+- **Anchors are content-addressed, so they can collide.** Two messages with
+  byte-identical text (`[Request interrupted by user]`, say) share one anchor, and
+  `read --anchor` then fails with `ambiguous-ref`. Ambiguous anchors are detected
+  and never published — every anchor a digest prints resolves to exactly one message.
+- **Most "user" records aren't from you.** They're tool results, interrupts, and
+  harness scaffolding. Those are filtered out; `prompts:` counts what you typed.
+- **`outline` has two output shapes** — segment ranges for long conversations,
+  per-message lines for short ones. Both are handled.
+- **Subagent transcripts** aren't conversations in their own right and never appear
+  in the listing, matching `claude-history`'s discovery rules.
+- **`claude-history` has no per-agent ref.** `--subagents` inlines agent messages
+  into the parent read untagged, so they can't be sliced apart. Sidecars are
+  parsed directly, which is why agent digests carry no `ma_` anchors — those are
+  claude-history's to mint, and a fabricated one is worse than none.
+- **An agent's last message isn't necessarily its conclusion**, so the section is
+  *Last thing it said*. An interrupted agent ends mid-thought.
+- **Agent counts take the larger of two sources** — `Agent`/`Task` calls in the
+  parent, and sidecars on disk. Sidecars go missing; an agent that spawns its own
+  outnumbers the visible calls.
+- **Scratch paths** (`/tmp`, scratchpads, plan files) are excluded from "files
+  changed" so the work log shows real project changes.
+
+## Adding prose later
+
+There is a deliberately unimplemented `Summariser` seam at the bottom of
+`chsum.py`. A TL;DR is the one thing extraction can't produce; the intended order
+is Haiku first to set a quality bar and a price, then a local MLX backend measured
+against it.
+
+The rule for any backend: it gets the already-extracted material, and its output is
+**additive** — layered on top of the verbatim record so a wrong sentence can always
+be checked against the quotes beneath it.
+
+If you do go local, note that the model in `mlx-community/DeepSeek-R1-Distill-Qwen-14B-MLX`
+is **139 GB** of unquantised weights. The 4-bit build is `…-14B-4bit` at 8.32 GB. On a
+16 GB machine the binding constraint is KV cache, not context length: this architecture
+costs 192 KB/token at fp16 (96 KB with `kv_bits=8`), so after 8.32 GB of weights you get
+roughly 18k–36k tokens of usable input, not the 131k the config advertises.