@procrastivity/clast 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "clast",
+  "version": "0.1.0",
+  "description": "Capture, curate, and surface Claude Code session history across all your projects.",
+  "homepage": "https://github.com/procrastivity/clast",
+  "author": {
+    "name": "Beau",
+    "url": "https://github.com/procrastivity"
+  },
+  "license": "MIT"
+}

package/.claude-plugin/skills/day-wakeup/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: day-wakeup
+description: 'Generate curated journal entries from yesterday''s Claude Code sessions across all projects. Use when the user says "/day-wakeup", "day wakeup", "morning briefing", "catch me up on yesterday", "what did I work on yesterday", "review my day", "process yesterday''s sessions", or otherwise signals they want to curate prior work across projects at the start of a new day. Runs `clast snapshot` to ensure fresh data, then walks through each uncurated session from yesterday and proposes a draft entry the user can accept, edit, or skip. Prompts for promotion of decisions, common-issues, and workflows per accepted session. This is the once-per-day curation flow; for per-project briefings use /wakeup; for mid-session pivots use session-brief.'
+---
+
+# Day Wakeup
+
+Process yesterday's Claude Code sessions across all projects. For each session, generate a draft journal entry and walk the user through accepting/editing/skipping it.
+
+## Why this exists
+
+Curation at end-of-session has high friction (the user wants to stop, not summarize). Curation at start-of-next-day has lower friction (fresh eyes, easier to decide what's worth keeping). `/day-wakeup` is that start-of-next-day flow.
+
+The transcripts themselves are captured automatically by the SessionStart hook + cron — the user never has to remember to log anything. What `/day-wakeup` does is **curate the captured transcripts into durable entries the user controls**, and prompt for promotion of decisions, common-issues, and workflows along the way.
+
+## Step 1: Ensure fresh data
+
+Run `clast snapshot` (idempotent; silent on no-op). This guarantees we're not missing anything that ran since the last hook fire.
+
+```bash
+clast snapshot
+```
+
+Errors here are non-fatal — proceed even if it fails, just warn the user.
+
+## Step 2: Enumerate uncurated sessions from yesterday
+
+```bash
+clast --json sessions --day yesterday
+```
+
+Filter to sessions with `curated: false`. If everything from yesterday is already curated, print "Nothing to curate from yesterday — already done." and stop.
+
+Group sessions by project for presentation. Order: most recent project first, sessions chronological within each project.
+
+## Step 3: For each session, generate a draft
+
+For each session in the list:
+
+1. Read session details:
+   ```bash
+   clast --json show <session-id> --full --turns 8
+   ```
+   This returns metadata + first 8 and last 8 turns of the transcript (text only, no tool calls — kept compact).
+
+2. Read breadcrumbs for this project from yesterday:
+   ```bash
+   clast breadcrumb --read --project <slug> --day yesterday
+   ```
+
+3. Generate a draft entry using the **draft generation prompt** (see below).
+
+4. Display the draft to the user inside a fenced markdown code block, with a brief preamble: "Here's a draft for the X session in <project> at HH:MM:".
+
+5. Present the **promotion question** (see below) via AskUserQuestion.
+
+6. Handle the response:
+   - **Accept** (any combination of accept-flavored options): pipe the draft to `clast entries write` via stdin.
+   - **Edit**: prompt the user for what to change, regenerate the draft incorporating their feedback, loop.
+   - **Skip**: do not write.
+   - **Stop here**: end the entire `/day-wakeup` flow, leaving remaining sessions uncurated (user can resume tomorrow).
+
+## Step 4: Final summary
+
+After all sessions are processed (or user stopped early), print a summary:
+
+```
+Day wakeup complete.
+Curated: 3 sessions across 2 projects.
+Skipped: 1 session.
+Remaining uncurated: 0.
+
+Promoted:
+  Decisions: 1
+  Common-issues: 0
+  Workflows: 1
+
+Run `/wakeup <project>` to start working on a specific project today.
+```
+
+## Draft generation prompt
+
+When generating each draft, use this prompt internally (with the placeholders filled in):
+
+````markdown
+You are drafting a journal entry for a Claude Code session that the user just reviewed. The entry will be written to the user's journal and may be read days or weeks later to refresh context on what was happening.
+
+Session metadata:
+- Project: {project}
+- Branch: {branch}
+- Start: {start}
+- End: {end}
+- Approximate messages: {msg_count}
+
+First 8 turns of the session:
+{first_turns}
+
+Last 8 turns of the session:
+{last_turns}
+
+Breadcrumbs the user left during this session's day:
+{breadcrumbs}
+
+Draft a journal entry in this exact markdown structure. Omit any section that has no content (don't write "N/A"):
+
+```
+# Session: <short human-readable title>
+
+## Goal
+One sentence describing what this session was trying to accomplish.
+
+## What shipped
+- Bullet list of what actually got done (files written, features built, fixes landed). Extract from the transcript.
+
+## Issues + fixes
+- **Issue:** what broke. **Fix:** what resolved it.
+
+## Dead ends touched
+- **Tried:** approach. (You can usually see this in the transcript as "tried X then switched to Y".)
+  - Note: if you can't tell *why* an approach was abandoned from the transcript, leave that for the user to fill in. Don't speculate.
+
+## Open threads
+- Anything still unfinished or deferred. Use the breadcrumbs and the last turns of the session as signal.
+
+## Notes
+- Anything else useful for the next session in this project.
+```
+
+Be concise. Prefer bullets over paragraphs. Use the user's terminology (project-specific names, file paths). Don't invent details. If you're uncertain about something, omit it rather than guess.
+
+Suggest tags after the entry, separated by a blank line, prefixed with "Suggested tags:". The user will confirm.
+````
+
+## AskUserQuestion: promotion options per session
+
+After showing the draft, present:
+
+- **question**: "What would you like to do with this draft?"
+- **header**: "Session draft"
+- **multiSelect**: true
+- **options**:
+  - `Accept`
+  - `Accept + promote decision` — also write a decision file
+  - `Accept + promote common-issue` — also write a common-issue file
+  - `Accept + promote workflow` — also write a workflow file
+  - `Edit` — user wants to revise; will prompt for changes
+  - `Skip` — do not write this entry
+  - `Stop here` — end /day-wakeup entirely, leave remaining sessions uncurated
+
+If `Skip` and `Stop here` are both selected, treat as `Stop here`. If `Edit` is selected alongside any accept option, treat as `Edit` first (the user wants to revise before accepting).
+
+When a promote option is selected, prompt the user for the title and content of that promoted item before writing.
+
+## Editing handler
+
+If the user selects `Edit`:
+
+1. Ask "What should change?"
+2. Take their answer as a feedback note.
+3. Regenerate the draft, including their feedback in the prompt as "Revisions requested by user: <feedback>".
+4. Show the new draft.
+5. Present the same promotion options again. Loop until the user stops editing.
+
+## Writing the entry
+
+When the user accepts:
+
+1. Extract the suggested tags from the draft (the user may have edited them).
+2. Pipe the entry body (without the suggested-tags trailer) to `clast entries write`:
+
+```bash
+clast entries write \
+  --session <session-id> \
+  --slug <session-slug> \
+  --tags <tag1>,<tag2>,<tag3> \
+  --title "<title>" \
+  --body-stdin
+```
+
+(Sending the markdown body via stdin, ending with EOF.)
+
+3. If the write succeeds, append a one-line confirmation to the running summary.
+
+For promoted items (decisions, common-issues, workflows): currently these are tracked inside the entry's body for v1. **TODO for v1.1: separate `clast decisions write` / `clast common-issues write` / `clast workflows write` subcommands and a directory structure to match.** Note this in the user-facing summary so the user knows they're folded into the entry for now.
+
+<!-- step-12 addition: v1 promotion section convention --> When folding promoted items into the accepted entry body, append `## Decision`, `## Common issue`, or `## Workflow` (h2, singular, capitalized), each followed by the prompted-for title (h3) and body before invoking `clast entries write`.
+
+## Edge cases
+
+- **No sessions from yesterday**: print "No sessions from yesterday." and stop.
+- **All sessions already curated**: print "All sessions from yesterday already curated." and stop.
+- **`clast snapshot` fails**: warn the user, then attempt to proceed with whatever's already in the manifest.
+- **`clast show` fails for a specific session**: skip that session, note it in the final summary, continue with the rest.
+- **User says "do them all without prompting"**: not a v1 feature. Each session gets its own AskUserQuestion. The friction is intentional — it's where curation happens.

package/.claude-plugin/skills/wakeup/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wakeup
+description: |
+  Synthesize a briefing for the current project (or a named one) so the user can resume work without re-explaining context. Use when the user says "/wakeup", "wakeup", "wake up", "catch me up", "where was I", "what was I working on", "load last session", "resume", or otherwise signals they want prior context for the project they're about to work on. Optionally accepts a project slug like "/wakeup xesapps". Reads recent curated entries and today's breadcrumbs from `~/.claude/journal/` and produces a 2–5k-token briefing. This is the per-project read flow; for cross-project daily curation use /day-wakeup; for mid-session pivots use session-brief.
+---
+
+# Wakeup
+
+Synthesize a briefing for the current (or named) project so the user can resume without re-explaining context.
+
+## Why this exists
+
+`/day-wakeup` curates yesterday's work into entries. `/wakeup` reads those entries back when starting work in a specific repo. The two are complementary: one writes, one reads.
+
+## Step 1: Resolve the project
+
+If the user passed a slug as an argument (`/wakeup xesapps`), use it directly. Otherwise resolve from current working directory:
+
+```bash
+clast registry resolve "$(pwd)"
+```
+
+If `pwd` doesn't resolve and no slug was given: print "Not in a registered project. Run `clast registry add .` first, or invoke as `/wakeup <slug>`." and stop.
+
+## Step 2: Gather data
+
+In parallel:
+
+```bash
+# Recent curated entries for this project (newest first)
+clast --json entries --project <slug> --limit 5
+
+# Today's breadcrumbs for this project
+clast breadcrumb --read --project <slug> --day today
+
+# Today's session activity (if any — user might have started already)
+clast --json sessions --day today --project <slug>
+```
+
+For each entry returned, also read the body if it'll fit (file sizes are typically 1–5KB each):
+
+```bash
+clast entries read <entry-path>
+```
+
+## Step 3: Synthesize the briefing
+
+Using the **synthesis prompt** (see below), produce a briefing of 2–5k tokens. Structure:
+
+```
+## Wakeup briefing — <project>
+
+**Active thread:** <one-line from most recent entry's "Open threads" section, or "None">
+
+**Last session:** <date> on branch `<branch>`: <one-line goal>
+- Work done: <2-3 bullets condensed from most recent entry>
+- Open threads: <bullets, if any>
+- Dead ends to avoid: <bullets, if any>
+
+**Recent sessions:** (up to 5)
+- <date> [<branch>] <slug>: <one-line goal>
+
+**Today's breadcrumbs:** (if any)
+- HH:MM — <text>
+
+**Today's sessions:** (if user has already worked today)
+- HH:MM start: <branch>, <msg-count> messages
+
+**Suggested next step:** <derived from active thread + breadcrumbs>
+```
+
+End with one of:
+
+- "Resume? Active thread: '<thread>'. Suggested next step: <step>."
+- "No active thread. Last session ended cleanly. What are you working on today?"
+
+## Step 4: Don't write anything
+
+Wakeup is read-only. Never invoke write-form subcommands (`entries write`, `breadcrumb '<text>'`, `snapshot`) from this skill.
+
+## Edge cases
+
+- **No entries for project**: print "No curated entries for `<slug>` yet. Run `/day-wakeup` to process recent sessions, or run `clast sessions --project <slug>` to see what's available." and stop.
+- **Slug resolves but no entries and no sessions**: print "Project `<slug>` registered but has no journal activity yet."
+- **Today's session count > 5**: summarize ("worked 12 sessions today, most recent 16:22 on branch `loop-guard-ngram`") rather than listing all.
+
+## Synthesis prompt
+
+<!-- step-13 addition: inlined synthesis prompt with explicit structure re-statement -->
+
+```
+You are synthesizing a project briefing for the user. They are about to start work on the `{slug}` project and want a tight summary of where they left off.
+
+Recent curated entries (newest first):
+{entries_json_with_bodies}
+
+Today's breadcrumbs for this project:
+{breadcrumbs_today}
+
+Today's session activity for this project:
+{sessions_today}
+
+Produce a briefing using this structure (omit any section that has no content):
+
+- Active thread: one-line from most recent entry's "Open threads", or "None"
+- Last session: date, branch, one-line goal, work done (2-3 bullets), open threads, dead ends to avoid
+- Recent sessions: up to 5 entries with date, branch, slug, one-line goal
+- Today's breadcrumbs: timestamped list if any
+- Today's sessions: list if user has already worked today
+- Suggested next step: derived from active thread + breadcrumbs
+
+Be concise. Use the user's terminology. Don't repeat content across sections. The total briefing should be 2–5k tokens — if you're approaching that, summarize rather than list verbatim.
+
+For the "Suggested next step": prefer the most recent entry's "Open threads" content, then the most recent breadcrumb, then a synthesis of the recent work. If nothing concrete, say "No active thread."
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beau (procrastivity)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# clast
+
+Capture, curate, and surface Claude Code session history across all your projects.
+
+> 🚧 Pre-1.0 — APIs may change before v1.0.
+
+## What it does
+
+- **CLI** (`clast`) — snapshot, browse, and query your Claude Code session JSONL history.
+- **Plugin** — installs skills (`/day-wakeup`, `/wakeup`) that surface recent session context.
+- **SessionStart hook** — quietly snapshots active sessions in the background each time Claude Code starts.
+
+## Capture your sessions
+
+```sh
+clast snapshot                       # copy any new sessions into the journal
+clast snapshot --dry-run --json | jq # preview what would be captured
+```
+
+`clast snapshot` is idempotent and silent on no-op, safe to run from cron or
+a SessionStart hook. See [`docs/cli-contract.md#clast-snapshot`](./docs/cli-contract.md#clast-snapshot)
+for the full flag reference.
+
+## Read your sessions
+
+```sh
+clast projects                        # which projects had activity today
+clast sessions --since -7d            # sessions captured in the last week
+clast show <session-uuid> --full      # metadata + first/last turns
+```
+
+Window flags (`--day`, `--since`, `--until`) accept ISO dates and
+relative keywords. See
+[`docs/cli-contract.md#clast-projects`](./docs/cli-contract.md#clast-projects),
+[`docs/cli-contract.md#clast-sessions`](./docs/cli-contract.md#clast-sessions),
+and [`docs/cli-contract.md#clast-show`](./docs/cli-contract.md#clast-show)
+for the full flag and output schemas.
+
+## Curate an entry
+
+```sh
+clast entries                                            # list curated entries
+clast entries read 2026-05-30-1430-xesapps-foo.md        # cat a single entry
+printf 'Notes...\n' | clast entries write \
+  --session <session-uuid> --slug short-slug --body-stdin # write a new entry
+```
+
+`clast entries write` looks up the session in the manifest, composes the
+documented frontmatter from the captured snapshot + registry, and writes
+`entries/YYYY-MM-DD-HHMM-<project-slug>-<session-slug>.md` atomically. See
+[`docs/cli-contract.md#entry-frontmatter`](./docs/cli-contract.md#entry-frontmatter)
+for the full frontmatter schema and
+[`docs/cli-contract.md#clast-entries`](./docs/cli-contract.md#clast-entries)
+for the flag reference.
+
+## Leave a breadcrumb
+
+```sh
+clast breadcrumb --project xesapps 'check migration before deploy'
+clast breadcrumb --global 'remember to bump the cache version'
+
+clast breadcrumb --read --project xesapps
+clast breadcrumb --read --global
+```
+
+Breadcrumbs are append-only one-line notes for `/wakeup` and `/day-wakeup`.
+See [`docs/cli-contract.md#clast-breadcrumb`](./docs/cli-contract.md#clast-breadcrumb)
+for the full command contract.
+
+## Inspect and audit the journal
+
+```sh
+clast stats                          # one-line activity summary for today
+clast stats --since -7d              # rollup over the last week
+
+clast doctor                         # check manifest, registry, snapshots
+clast doctor --fix                   # rebuild a broken manifest, prune orphans
+```
+
+See [`docs/cli-contract.md#clast-stats`](./docs/cli-contract.md#clast-stats)
+and [`docs/cli-contract.md#clast-doctor`](./docs/cli-contract.md#clast-doctor)
+for the contract reference, and `clast stats --help` / `clast doctor --help`
+for the current set of flags.
+
+## Install to a prefix
+
+`./install.sh` installs to `/usr/local` by default; for a non-root local install, run:
+
+```sh
+./install.sh ~/.local
+```
+
+`make install` wraps the same script. Use `./uninstall.sh ~/.local` (or
+`make uninstall` for the default prefix) to remove the installed files. See
+[`docs/repo-bootstrap.md#installsh--uninstallsh`](./docs/repo-bootstrap.md#installsh--uninstallsh)
+for the rationale.
+
+## Install with Nix
+
+With Nix flakes enabled, you can use `clast` directly from the public flake:
+
+```sh
+nix run github:procrastivity/clast -- whereami
+nix profile install github:procrastivity/clast
+nix build .#default && ./result/bin/clast --version
+```
+
+For Home Manager or nix-darwin users, `overlays.default` exposes `pkgs.clast`.
+See [`docs/repo-bootstrap.md#nix-flake`](./docs/repo-bootstrap.md#nix-flake)
+for the full overlay wiring.
+
+## Install via npm
+
+```sh
+npm install -g @procrastivity/clast
+npx -p @procrastivity/clast clast --version
+```
+
+The npm package ships the same install set as `install.sh` and Nix: `bin/`,
+`lib/`, `.claude-plugin/`, `hooks/`, `examples/`, `README.md`, and `LICENSE`.
+After a global install, register the plugin with
+`claude plugin install $(npm root -g)/@procrastivity/clast`.
+
+## Install as a Claude Code plugin
+
+For a local checkout, install the plugin with:
+
+```sh
+claude plugin install <path-to-clast-checkout>
+```
+
+The plugin can be installed from any local checkout, or via `npm install -g`
+(which puts `.claude-plugin/` under `npm root -g`); a centralized marketplace
+listing is a separate distribution channel deliberately not pursued for v1.
+Today the plugin ships a single `SessionStart` hook: every time a Claude Code
+session starts it backgrounds `clast snapshot`, so your journal stays current
+with zero manual effort. The hook is best-effort and silent: if the `clast` CLI
+isn't on your `PATH` yet, sessions still start cleanly. See
+[`docs/skill-prompts.md#hook-sessionstart`](./docs/skill-prompts.md#hook-sessionstart)
+for the hook's design rationale.
+
+### `/day-wakeup`
+
+At the start of each day, run `/day-wakeup` inside any Claude Code session after
+the plugin is installed. It performs once-per-day cross-project curation of
+yesterday's sessions into durable journal entries, walking each uncurated session
+through a draft you can accept, edit, skip, or mark for in-entry promotion. See
+[`docs/skill-prompts.md#skill-1-day-wakeup`](./docs/skill-prompts.md#skill-1-day-wakeup).
+
+### `/wakeup`
+
+When starting work on a specific project, run `/wakeup` (or `/wakeup <slug>` from
+anywhere) to get a per-project read-only briefing synthesized from recent curated entries,
+today's breadcrumbs, and any sessions already started today. `/wakeup` never writes — it
+only reads. See
+[`docs/skill-prompts.md#skill-2-wakeup`](./docs/skill-prompts.md#skill-2-wakeup).
+
+## Development
+
+**With Nix (recommended).** Run `direnv allow` (or `nix develop`) at the repo root. The dev shell provides `bash`, `jq`, `git`, `shellcheck`, and `pre-commit` — everything `clast` needs at runtime plus the dev tooling.
+
+**Without Nix.** Install `bash 5+`, `jq`, `git`, and `shellcheck` via your package manager, then run `make deps-check` to verify they're on PATH.
+
+## CI / Release
+
+Pull requests run lint, tests, version sync, npm pack shape, Nix smoke, flake check, and Nix build automatically.
+Releases trigger on `v*` tags, and the tag version must match `package.json` exactly.
+The release workflow publishes to npm with provenance and creates a GitHub Release with the npm tarball attached.
+Configure the `NPM_TOKEN` repo secret before the first release tag.
+
+## Documentation
+
+- [`docs/overview.md`](./docs/overview.md) — project overview and design.
+- [`docs/cli-contract.md`](./docs/cli-contract.md) — CLI reference.
+- [`docs/skill-prompts.md`](./docs/skill-prompts.md) — plugin reference.
+- [`docs/repo-bootstrap.md`](./docs/repo-bootstrap.md) — repo layout and packaging.
+- [`docs/releasing.md`](./docs/releasing.md) — release runbook.
+- [`examples/`](./examples/) — cron, systemd-timer, and workflow samples.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).