chronicle

name	chronicle
description	Session continuity for coding work. Default to /chronicle to capture, /chronicle catchup to resume, and /chronicle pending to review open threads. Use curate, recap, wrapup, summarize, publish, insights, search, and ui only when the user explicitly needs them.
license	Apache-2.0

Chronicle

Captures and curates session memory so coding context survives across restarts.

Related: For persistent teammate behavior see team-memory. For session title lifecycle see session-titles.

Start Here

Prefer these three workflows unless the user explicitly asks for something else:

/chronicle          # Save current session state
/chronicle catchup  # Restore context for the current project
/chronicle pending  # Show open threads across sessions

Use them like this:

• /chronicle when the user wants to save, checkpoint, or quickly wrap a session.
• /chronicle catchup when the user is returning to a repo and wants to know where they left off.
• /chronicle pending when the user wants a project-spanning open-loops list.

Command Map

Need	Command	How to respond
Quick capture	/chronicle or /chronicle <note>	Summarize current state, write/update today's block, keep output concise.
Return briefing	/chronicle catchup	Load recent blocks for the current project and surface active context first.
Open loops	/chronicle pending	List pending items across blocks; group by project when helpful.
Help	/chronicle help or /chronicle ?	Start with the three primary workflows; expand into advanced commands only if the user asks.
Curated memory	/chronicle curate	Invoke the curator agent for a richer block instead of doing a thin capture.
Session closeout	/chronicle wrapup	Run deliberate closeout: curate, inspect unresolved work, and update backlog only when warranted.
Narrative recap	/chronicle recap	Generate a multi-session narrative, cross-checking git and blocks.
Search/read	/chronicle search, /chronicle blocks, /chronicle stale, /chronicle resolve	Use the matching script and report exact matches or resolution state.
Publish/UI	/chronicle publish, ui, dev	Use the docs/scripts only when the user asks for exported or browser views.
Summaries	/chronicle summarize	Generate time-bucketed AI summaries for human consumption.

For full command behavior, examples, and edge cases, read references/command-reference.md.

Quick Capture

1. Gather the current project, branch, recent edits, key decisions, open work, and any user-provided note.
2. Prefer factual, terse summaries over file-list dumps.
3. Write or update the current day's block through the Chronicle scripts when possible.
4. End with a short confirmation and the most important unresolved next step.

Catchup And Pending

For /chronicle catchup, run the catchup script or manually read recent project blocks, then answer in this order:

• current branch/worktree context
• recent shipped or in-flight work
• unresolved pending items
• likely next action

For /chronicle pending, show active items first. Do not bury stale or resolved material in a long historical dump.

Curate And Wrapup

Use chronicle-curator when the user wants a meaningful checkpoint, retrospective, or session wrap. Curated blocks should include goal, accomplishments, decisions, challenges, and next steps.

/chronicle wrapup is a closeout workflow, not just a summary. Check whether pending work belongs in backlog, whether the session is safe to archive, and whether local processes or branches need cleanup.

Scripts

Run scripts from the Chronicle script directory unless the command reference says otherwise:

bun ~/.claude/skills/chronicle/scripts/catchup.ts
bun ~/.claude/skills/chronicle/scripts/recap.ts <project> --days=14
bun ~/.claude/skills/chronicle/scripts/stale.ts
bun ~/.claude/skills/chronicle/scripts/resolve.ts "<pending item>"
bun ~/.claude/skills/chronicle/scripts/publish.ts --period weekly
bun ~/.claude/skills/chronicle/scripts/dashboard.ts

Use repo-local paths (skills/chronicle/scripts/...) when developing this repo.

Development

For Chronicle implementation work:

• Read docs/development.md for local development workflow.
• Run ./skills/chronicle/tests/run_tests.sh for the browser-backed flow tests.
• Run targeted bun test commands in skills/chronicle/scripts/ for script changes.
• Keep hook behavior fail-open; session start/end must not block normal agent use.

Reference Loading

Load additional context only when needed:

• references/command-reference.md — full command details, examples, schemas, UI/publish/summarize behavior.
• docs/chronicle-design.md — system design.
• docs/dashboard-service.md — dashboard service details.
• docs/development.md — development workflow.