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 — two binaries, porcelain over plumbing:
  • clast — porcelain (LLM-aware): clast wake, clast brief. See run without Claude Code.
  • clast-plumbing — deterministic core: snapshot, browse, and query your Claude Code session JSONL history.
• Plugin — installs skills (/wake, /brief) that surface recent session context.
• SessionStart hook — quietly snapshots active sessions in the background each time Claude Code starts.

Capture your sessions

clast-plumbing snapshot                       # copy any new sessions into the journal
clast-plumbing snapshot --dry-run --json | jq # preview what would be captured

clast-plumbing snapshot is idempotent and silent on no-op, safe to run from cron or a SessionStart hook. See docs/reference/cli.md#clast-snapshot for the full flag reference.

Read your sessions

clast-plumbing projects                        # which projects had activity today
clast-plumbing sessions --since -7d            # sessions captured in the last week
clast-plumbing show <session-uuid> --full      # metadata + first/last turns

Window flags (--day, --since, --until) accept ISO dates and relative keywords. See docs/reference/cli.md#clast-projects, docs/reference/cli.md#clast-sessions, and docs/reference/cli.md#clast-show for the full flag and output schemas.

Curate an entry

clast-plumbing entries                                            # list curated entries
clast-plumbing entries read 2026-05-30-1430-xesapps-foo.md        # cat a single entry
printf 'Notes...\n' | clast-plumbing entries write \
  --session <session-uuid> --slug short-slug --body-stdin          # write a new entry

clast-plumbing 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/reference/cli.md#entry-frontmatter for the full frontmatter schema and docs/reference/cli.md#clast-entries for the flag reference.

Leave a breadcrumb

clast-plumbing breadcrumb --project xesapps 'check migration before deploy'
clast-plumbing breadcrumb --global 'remember to bump the cache version'

clast-plumbing breadcrumb --read --project xesapps
clast-plumbing breadcrumb --read --global

Breadcrumbs are append-only one-line notes for /brief and /wake. See docs/reference/cli.md#clast-breadcrumb for the full command contract.

Inspect and audit the journal

clast-plumbing stats                          # one-line activity summary for today
clast-plumbing stats --since -7d              # rollup over the last week

clast-plumbing doctor                         # check manifest, registry, snapshots
clast-plumbing doctor --fix                   # rebuild a broken manifest, prune orphans

See docs/reference/cli.md#clast-stats and docs/reference/cli.md#clast-doctor for the contract reference, and clast-plumbing stats --help / clast-plumbing 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:

./install.sh ~/.local

make install wraps the same script; make install-local installs the working tree to ~/.local with no sudo (and make uninstall-local removes it). Use ./uninstall.sh ~/.local (or make uninstall for the default prefix) to remove the installed files. See docs/reference/repo-bootstrap.md#installsh--uninstallsh for the rationale.

Install with Nix

With Nix flakes enabled, you can use clast directly from the public flake:

nix profile install github:procrastivity/clast
nix build .#default && ./result/bin/clast --version       # porcelain
nix build .#default && ./result/bin/clast-plumbing --help # plumbing

For Home Manager or nix-darwin users, overlays.default exposes pkgs.clast. See docs/reference/repo-bootstrap.md#nix-flake for the full overlay wiring.

Install via npm

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:

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-plumbing snapshot, so your journal stays current with zero manual effort. The hook is best-effort and silent: if the clast-plumbing CLI isn't on your PATH yet, sessions still start cleanly. See docs/reference/plugin.md#hook-sessionstart for the hook's design rationale.

/wake

At the start of each day, run /wake 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/reference/plugin.md#skill-1-wake.

/brief

When starting work on a specific project, run /brief (or /brief <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. /brief never writes — it only reads. See docs/reference/plugin.md#skill-2-brief.

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. Publishing to npm uses Trusted Publishing (OIDC) — no NPM_TOKEN secret. Configure the trusted publisher for @procrastivity/clast on npmjs.com before the first release tag; see docs/reference/releasing.md.

Documentation

Start at docs/README.md for the full index. Highlights:

• Explanation — What is clast? · Architecture · Data model · Conventions
• Getting started — Install · First snapshot · Install the plugin
• Guides — curate an entry, use breadcrumbs, automate with cron or systemd, repair the journal, query recipes, run without Claude Code, morning briefing
• Reference — CLI · Plugin · Entry frontmatter · Config · Repo bootstrap · Releasing
• examples/ — cron, systemd-timer, and workflow samples.

License

MIT — see LICENSE.