Chronicle

Chronicle

A persistent journalist tracking your coding sessions.

Usage

/chronicle help               # Show categorized command list (start here if lost)
/chronicle                    # Quick capture of current session
/chronicle <note>             # Capture with a specific note
/chronicle curate             # Invoke curator to organize memory (interactive)
/chronicle insights           # Deep analysis with Explore subagents
/chronicle insights <project> # Analyze specific project
/chronicle pending            # Show pending threads across sessions
/chronicle blocks             # List recent memory blocks
/chronicle catchup            # Restore context for current project
/chronicle catchup --days=30  # Extend lookback to 30 days
/chronicle recap              # Multi-session narrative for current project (7 days)
/chronicle recap <project>    # Recap for a specific project
/chronicle recap --days=14    # Extend window
/chronicle wrapup             # Deliberate session close-out (curator + conditional backlog)
/chronicle stale              # Show stale pending items (>14 days)
/chronicle consolidate        # Consolidate old blocks (dry run)
/chronicle consolidate apply  # Consolidate and drop stale pending
/chronicle resolve "text"     # Mark pending item as resolved
/chronicle resolve --list     # Show all resolved items
/chronicle resolve --undo "text"  # Undo a resolution
/chronicle search <query>     # Search sessions by text
/chronicle publish            # Generate weekly digest (markdown)
/chronicle publish daily      # Generate daily digest
/chronicle publish month      # Generate monthly digest
/chronicle summarize          # Generate AI summaries (daily + repos)
/chronicle summarize weekly   # Generate weekly AI summaries (Opus)
/chronicle ui                 # Launch interactive web dashboard
/chronicle ui watch           # Run with auto-restart on file changes
/chronicle ui hot             # Run with hot module reloading
/chronicle ui install         # Install dashboard as macOS service
/chronicle ui start           # Start the dashboard service
/chronicle ui stop            # Stop the dashboard service
/chronicle ui status          # Check if dashboard service is running
/chronicle ui logs            # View dashboard service logs
/chronicle ui uninstall       # Remove dashboard service
/chronicle dev                # Start development session for Chronicle itself

Help (/chronicle help)

When the user runs /chronicle help (or /chronicle ?), print a categorized command table — the Usage block above is comprehensive but flat, and the surface has grown enough that grouping helps.

Render it as something like:

Chronicle commands by what they do
===================================

CAPTURE — write blocks
  /chronicle [note]      Quick block from current session state
  /chronicle curate      Editor-style update of today's block (mid-session safe)
  /chronicle wrapup      Deliberate session close-out + conditional backlog/release

READ — synthesize across blocks
  /chronicle catchup     Last session + pending for current project (return-to-work)
  /chronicle recap       Multi-session narrative for a project (Themes/Wins/Threads/Friction)
  /chronicle summarize   Time-bucketed AI summaries (daily/weekly, by repo or global)
  /chronicle insights    Deep cross-referenced analysis via subagents

BROWSE — list and search
  /chronicle blocks      Recent blocks listing
  /chronicle pending     Open threads across all sessions
  /chronicle stale       Pending items >14 days old
  /chronicle search Q    Free-text search across all blocks

MAINTAIN — keep the corpus healthy
  /chronicle consolidate Merge old per-week blocks (also runs monthly via launchd)
  /chronicle resolve T   Mark a pending item as resolved

PUBLISH / EXPLORE
  /chronicle publish     Markdown digest (daily/weekly/monthly)
  /chronicle ui          Interactive web dashboard
  /chronicle dev         Dev server for Chronicle itself

Quick decision guide:
  • "What was I doing yesterday?" → catchup
  • "What's been happening on this project lately?" → recap
  • "I want to mark this moment / chapter break" → curate
  • "I'm done for the day, close it out" → wrapup
  • "Show me everything still open" → pending (or stale for old ones)

For the full details on any command, see its section below in this file
or run /chronicle <command> with no args.

Render the table inline in the response — the user shouldn't have to open a file. Cite section anchors in this SKILL.md when they ask follow-up questions about a specific command.

Quick Capture (/chronicle or /chronicle )

Captures current session state as a memory block:

• Project and branch context
• What you're working on
• Key actions taken
• Pending work

Blocks stored in ~/.claude/chronicle/blocks/.

Want a thoughtful synthesis instead of a raw snapshot? Use /chronicle curate — it invokes the curator agent which updates today's block with editor-level reasoning (continuation vs new vs resolution, cross-block linking). Quick capture is the fast path; curate is the considered path.

Instructions for Quick Capture

1. Gather context:

   • Project name (from working directory)
   • Git branch (if in a repo)
   • Primary request from conversation
   • Accomplishments so far
   • Unfinished work

2. Write block to ~/.claude/chronicle/blocks/{date}-{descriptive-name}.json:

{
  "timestamp": "ISO date",
  "project": "project name",
  "branch": "git branch",
  "summary": "1-2 sentence summary",
  "accomplished": ["list", "of", "completions"],
  "pending": ["unfinished", "work"],
  "notes": "user-provided notes"
}

3. Confirm with brief summary of what was captured.

Curate Mode (/chronicle curate)

Invokes the Chronicle Curator agent for intelligent memory management. Safe to call mid-session as a chapter-break checkpoint — the curator updates today's block thoughtfully and idempotently. For end-of-session close-out with backlog/release housekeeping, use /chronicle wrapup instead.

How to Use

When user runs /chronicle curate:

1. Analyze the conversation to infer goal, challenges, and next steps
2. Propose your observations for confirmation:

Based on this session, here's what I observed:

• Goal: [inferred from conversation]
• Challenges: [any blockers mentioned or encountered]
• Next Steps: [logical next actions]

Adjust any of these, or confirm to curate?

3. User can confirm, adjust specific items, or provide different context
4. Then invoke the curator with the confirmed context

Then Invoke the Curator Agent

The curator can be resumed within a session to maintain memory continuity.

Flow:

1. Check if $CHRONICLE_CURATOR_ID is set (run echo $CHRONICLE_CURATOR_ID)

2. If set - Resume the existing curator:

Task(
  resume: "{CHRONICLE_CURATOR_ID}",
  prompt: "Continue curating with new context:
    Project: {project}
    Branch: {branch}
    Goal: {user's goal}
    Challenges: {user's challenges}
    Next Steps: {user's next steps}

    Review and update blocks as needed.
    Report what you changed."
)

3. If not set - Spawn fresh curator:

Task(
  subagent_type: "chronicle-curator",
  prompt: "Curate session with context:
    Project: {project}
    Branch: {branch}
    Goal: {user's goal}
    Challenges: {user's challenges}
    Next Steps: {user's next steps}

    Review existing blocks in ~/.claude/chronicle/blocks/
    Update or create blocks as needed.
    Report what you changed."
)

4. After Task returns - Capture the agentId and set for future use:

export CHRONICLE_CURATOR_ID={returned agentId}

This allows the curator to accumulate context across multiple /chronicle curate calls within the same session.

The curator will:

1. Read all existing memory blocks
2. Find the most recent block
3. Analyze: continuation, new work, or resolution?
4. Update recent block with new context
5. Check if older blocks need updates (resolved threads, connections)
6. Report changes made

Pending (/chronicle pending)

Show all pending work across sessions:

1. Read all blocks from ~/.claude/chronicle/blocks/
2. Extract pending arrays from each
3. Group by project
4. Display with recency info

Blocks (/chronicle blocks)

List recent memory blocks:

ls -lt ~/.claude/chronicle/blocks/ | head -10

Show filename, date, and first line of summary for each.

Catchup (/chronicle catchup)

Restore context when returning to a project — last session + aggregated pending. Optimized for "what was I doing yesterday."

Want the longer view across the last several sessions? Use /chronicle recap instead — it produces a Themes / Wins / Open threads / Friction narrative across a window of sessions, not just the last one. Catchup is for return-to-work; recap is for orienting after days away or producing a teammate handoff.

bun ~/.claude/skills/chronicle/scripts/catchup.ts [--days=N]

Options:

• --days=N - Look back N days (default: 7)

Shows:

1. Current project/branch/worktree context
2. Last session's summary and pending items
3. Aggregated pending work (deduplicated, with age)
4. Patterns: session frequency, focus areas

If no data found, suggests /chronicle to capture current session.

Auto-Resolution via Claude Code

The script can output resolution candidates for semantic matching:

bun ~/.claude/skills/chronicle/scripts/catchup.ts --candidates

This outputs JSON with pending/accomplished pairs scored by keyword overlap. When running /chronicle catchup with resolution checking:

1. Run catchup.ts --candidates to get JSON candidates
2. Spawn a haiku agent to evaluate each candidate semantically:

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: "For each candidate, determine if the accomplished item resolves the pending item.
    Return JSON array of resolved items: [{pendingText, accomplishedText, resolved: boolean}]

    Candidates: {candidates JSON}"
)

3. Save confirmed resolutions:

bun ~/.claude/skills/chronicle/scripts/resolve.ts "pending text"

Recap (/chronicle recap)

Generate a multi-session narrative recap for a project — the shape "returning to a repo after a few days and wanting to scan what happened," not "what was I doing in my last session."

recap.ts is a thin wrapper that calls summarize.ts with format=narrative. The synthesis logic, fallback handling, and context-gathering all live in summarize.ts — recap is just the friendly entry point with project-and-window argument parsing.

bun ~/.claude/skills/chronicle/scripts/recap.ts [project] [--days=N] [--stdout-only]

Options:

• project — positional, defaults to current project from detectContext()
• --days=N — time window (default: 7)
• --stdout-only — skip writing to ~/.claude/chronicle/recaps/

You can also call summarize directly for the same result, plus --md to print markdown to stdout:

bun ~/.claude/skills/chronicle/scripts/summarize.ts --repo=<project> --days=14 --format=narrative --with-context --md

What it produces

A Markdown recap with exactly four sections:

1. Themes — what the user has been pushing on (clustered into arcs, not listed day-by-day)
2. Wins — what shipped, cross-referenced with git log for PR numbers and feature names
3. Open threads — unfinished or deferred work, pulled from pending items + curated project memory
4. Friction — recurring gripes and preferences, pulled from curated feedback memory

Data sources

• Chronicle blocks for project within the window (from queries.ts)
• git log --oneline --since=<window> from the local project path (best-effort — skipped if the repo isn't found under ~/code/<project> or cwd)
• Curated memory at ~/.claude/projects/<slug>/memory/feedback_*.md and project_*.md

Behavior

• Output goes to stdout and to ~/.claude/chronicle/recaps/{project}-{YYYY-MM-DD}.md (unless --stdout-only)
• If fewer than 2 blocks in window: prints a "not enough data" message with pointers to raw session JSONLs under ~/.claude/projects/<slug>/ and exits 0
• If the API call fails: falls back to a raw-facts dump (sessions + git log + memory file counts) so the command is still useful offline
• Model: Opus (claude-opus-4-5-20251101) — recap is lower-frequency than summarize, quality matters more than cost

When to use it

• Returning to a project after a few days
• Producing a handoff for a teammate
• Before /chronicle wrapup on a long-running branch, to see the full arc

/chronicle catchup remains the right tool for "what was I doing yesterday" — recap is for the longer view. For time-bucketed summaries on a schedule (yesterday, last week, last month) rather than session-window narratives for a specific project, use /chronicle summarize — it's automated via launchd and feeds the dashboard.

Quality note

Recap fidelity is bounded by block fidelity. The SessionEnd hook auto-extracts blocks with thin, file-list summaries like "Worked on X: modified a.ts, b.ts and 14 more". Opus synthesizes what it can from those, but the Themes section is only as good as the inputs. Running /chronicle wrapup at the end of focused sessions writes richer blocks via the curator, which makes future recaps materially better. Over time the block pool gets denser and recap quality improves.

Wrapup (/chronicle wrapup)

Deliberate end-of-session close-out. Writes a high-fidelity chronicle block via the curator, then conditionally updates backlog/ and backlog/ROADMAP.md only if the session actually touched them. This is the intentional version of what the SessionEnd hook does automatically.

Use at the end of a focused work session when you know the themes, wins, and open threads and want them captured crisply — especially before merging a PR.

Mid-session chapter break? Use /chronicle curate instead — it runs the curator without the close-out housekeeping (no backlog commit, no release suggestion) and is safe to call repeatedly as a session evolves. Wrapup is the deliberate finality version: run it once when you're actually done.

Flow

1. Invoke the curator via /chronicle curate

Follow the Curate Mode section above: propose observations for the session, get user confirmation, then spawn or resume the chronicle-curator agent with goal / challenges / nextSteps. The curator writes or updates today's block.

2. Detect backlog / roadmap involvement

Before touching backlog/ or backlog/ROADMAP.md, confirm the session actually worked on them. Check:

• Were any files under backlog/ created, edited, moved, or deleted this session? (check git status + session edits)
• Was backlog/ROADMAP.md edited, or did the user explicitly reference it in the conversation?

If neither is true → skip step 3 entirely. Do not touch backlog files, do not append to ROADMAP, do not commit. The curator block is the only artifact.

3. Conditional backlog / roadmap update (only if step 2 detected involvement)

For each completed backlog item:

• Set status: done
• Set completed: YYYY-MM-DD
• Add a one-sentence retro_summary
• Set pr: and branch: if not already set
• Optionally set score: (0-5 effectiveness rating)
• Move the file to backlog/done/

For scope discovered but not implemented, create pending entries:

---
status: pending
category: followup  # or: plan, task-list, ideas
pr: null
branch: null
---

If ROADMAP was touched, append to backlog/ROADMAP.md under Learnings:

### YYYY-MM-DD — milestone name (#PR)
- What worked well
- What caused friction
- Anything worth documenting

Stage and commit:

git add backlog/
git commit -m "chore: update backlog for <feature>"

4. Milestone check

If the session completed a milestone (not just a task), suggest /release to bump version, generate changelog, and create a GitHub Release. Milestones often span multiple PRs — suggest release when a meaningful capability is complete, not after every PR.

What this does NOT do

• Does not write handoff.md in the repo. The chronicle block is the handoff. /chronicle catchup at the start of the next session restores context; /chronicle recap synthesizes the longer arc.
• Does not touch backlog/ or backlog/ROADMAP.md unless the session explicitly worked on them. Most sessions will skip step 3.
• Does not emit a copy-pastable next-session prompt. /chronicle catchup replaces that pattern.

Stale (/chronicle stale)

Show pending items that have been open for more than 14 days:

bun ~/.claude/skills/chronicle/scripts/stale.ts

Shows:

1. All pending items older than 14 days
2. Grouped by project
3. Sorted by age (oldest first)

Staleness warnings also appear in /chronicle catchup output with ⚠️ markers.

Consolidate (/chronicle consolidate)

Reduce block bloat by merging per-project, per-week blocks into consolidated summaries.

bun ~/.claude/skills/chronicle/scripts/consolidate.ts                    # Dry run
bun ~/.claude/skills/chronicle/scripts/consolidate.ts --apply            # Execute
bun ~/.claude/skills/chronicle/scripts/consolidate.ts --apply --drop-pending  # Execute + clear stale pending
bun ~/.claude/skills/chronicle/scripts/consolidate.ts --older-than=30    # Only blocks >30 days old (default: 14)
bun ~/.claude/skills/chronicle/scripts/consolidate.ts --project=services # Single project

Consolidation:

• Groups blocks by project + ISO week
• Deduplicates accomplished and pending items (case-insensitive)
• Removes pending items that appear in accomplished
• Cross-week dedup: each project's pending kept only in earliest week
• Archives originals to ~/.claude/chronicle/archive/ (not deleted)

Also runs monthly via launchd (1st of each month at 2am). Install:

~/.claude/skills/chronicle/scripts/install-services.sh install consolidate

Resolve (/chronicle resolve)

Mark pending items as resolved. Resolutions can happen two ways:

Auto-detection: During /chronicle catchup, Claude Code can spawn a haiku agent to semantically match accomplished items against pending items (see Catchup section above).

Explicit resolution: Manually mark items as complete:

bun ~/.claude/skills/chronicle/scripts/resolve.ts "Add unit tests"  # Mark as resolved
bun ~/.claude/skills/chronicle/scripts/resolve.ts --list            # Show resolved items
bun ~/.claude/skills/chronicle/scripts/resolve.ts --undo "text"     # Undo a resolution

Resolutions are stored in ~/.claude/chronicle/resolved.json as an overlay - original blocks remain immutable.

Resolved items:

• Are excluded from pending lists in catchup and stale
• Show with ✓ in the "Recently resolved" section of catchup output
• Can be undone with --undo to make them pending again

Search (/chronicle search )

Search across all Chronicle blocks by text:

1. Read all blocks from ~/.claude/chronicle/blocks/
2. Search in: summary, accomplished items, pending items, project name, branch
3. Return matching blocks sorted by relevance

Example queries:

• /chronicle search oauth - Find sessions mentioning OAuth
• /chronicle search jrnlfish - Find all jrnlfish sessions
• /chronicle search "error handling" - Find sessions with specific phrase

Insights (/chronicle insights)

Generate deep insights by exploring code and memory patterns using subagents.

How to Use

/chronicle insights              # All active projects (max 3)
/chronicle insights <project>    # Specific project

Process

1. Spawn the chronicle-insights agent:

Task(
  subagent_type: "chronicle-insights",
  prompt: "Generate insights for {project or 'all active projects'}.

    Focus on:
    - Stalled work (pending items >7 days with no progress)
    - Tech debt patterns (TODOs, FIXMEs, complex code)
    - Cross-project themes
    - Evolution of focus over time

    For each project, spawn Explore subagents to examine actual code.
    Cross-reference findings with memory blocks.
    Save results to ~/.claude/chronicle/insights/"
)

2. The insights agent spawns Explore subagents to examine actual code in worktrees.

3. Results saved to ~/.claude/chronicle/insights/{date}-{project}.json

Insight Types

Viewing Insights

Insights appear in the Chronicle dashboard under each repo's detail view. You can also read them directly:

cat ~/.claude/chronicle/insights/*.json | jq .

Block Schema

{
  "timestamp": "2026-01-01T00:30:00Z",
  "project": "dotclaude",
  "branch": "feat/chronicle",
  "summary": "Brief description of session focus",
  "goal": "What user is trying to accomplish",
  "accomplished": ["Completed item 1", "Completed item 2"],
  "pending": ["Still need to do X", "Blocked on Y"],
  "challenges": ["Current difficulty"],
  "nextSteps": ["Planned action 1", "Planned action 2"],
  "relatedSessions": ["2025-12-31-oauth-work.json"],
  "notes": "Additional context or observations"
}

Not all fields required - use what's relevant.

Publish (/chronicle publish)

Generate markdown digests of your Chronicle data.

How to Use

Run the digest generator:

bun ~/.claude/skills/chronicle/scripts/publish.ts [period]

Periods:

• weekly (default) - Last 7 days
• daily - Last 24 hours
• month - Last 30 days

Output goes to ~/.claude/chronicle/digests/:

• Weekly: 2026-W01.md (ISO week)
• Daily: 2026-01-04-daily.md
• Monthly: 2026-01.md

Digest Contents

• At a glance metrics
• Project summaries with highlights
• Pending work queue
• Files most modified
• Observations and patterns

Dashboard (/chronicle ui)

Launch an interactive web dashboard for exploring Chronicle data.

bun ~/.claude/skills/chronicle/scripts/dashboard.ts

Opens browser to http://localhost:3456.

Features

• Newspaper-style view - Sessions as stories, grouped by time period
• Worktree sidebar - Active worktrees with status indicators
• Repo-level view - Click repo name to see aggregate stats, worktree cards, and AI summaries
• Usage stats - Tokens used, peak productivity hours (from ai-coding-usage DB)
• Create worktrees - Click + next to repo name
• Archive worktrees - Click 📦 to archive

Run as Service

For persistent background operation, see docs/dashboard-service.md.

Quick start:

/chronicle ui install   # One-time setup
/chronicle ui start     # Start service (port 3457)
/chronicle ui status    # Check if running

Remote Dashboard Sync

Run the dashboard on a remote server with periodic data sync from your Mac.

Setup:

1. Deploy dashboard to remote host (requires Bun runtime + systemd)
2. Configure sync in ~/.claude/.env:

   CHRONICLE_SYNC_TARGET=myserver      # Display name
   CHRONICLE_DEPLOY_DIR=/path/to/deploy # Ansible deploy directory
   

3. Install the reminder service:

   ~/.claude/skills/chronicle/scripts/install-services.sh install sync-reminder
   

How it works:

• Daily popup (9am) if Chronicle blocks changed since last sync
• Click "Sync Now" to rsync data to remote
• Silent when no changes

Manual sync:

~/.claude/skills/chronicle/scripts/sync-reminder.sh           # Interactive
ansible-playbook claude.yml --tags chronicle-sync -e chronicle_sync_enabled=true  # Direct

Development (/chronicle dev)

Start a development session for working on Chronicle itself.

# Stop service to free port, start dev server with auto-reload
~/.claude/skills/chronicle/scripts/install-services.sh uninstall dashboard 2>/dev/null
bun --watch ~/.claude/skills/chronicle/scripts/dashboard.ts

Opens browser to http://localhost:3456

Port Strategy

Running Tests

./skills/chronicle/tests/run_tests.sh

For detailed development workflow, see docs/development.md.

Summarize (/chronicle summarize)

Generate high-quality AI summaries using Claude. Time-bucketed (daily / weekly / monthly), suitable for scheduled launchd jobs and the dashboard's "this week" view.

Looking for a one-shot narrative across N sessions of a single project, not a fixed time bucket? Use /chronicle recap instead. Summarize answers "what happened this week"; recap answers "what's been going on with project X lately." Recap is interactive and ad-hoc; summarize is automated and periodic.

Manual Generation

bun ~/.claude/skills/chronicle/scripts/summarize.ts                          # Daily global + repo summaries (cron path)
bun ~/.claude/skills/chronicle/scripts/summarize.ts --weekly                 # Weekly summaries, Opus (cron path)
bun ~/.claude/skills/chronicle/scripts/summarize.ts --repo=name              # Single repo, structured JSON, daily window
bun ~/.claude/skills/chronicle/scripts/summarize.ts --repo=name --days=14    # Custom window
bun ~/.claude/skills/chronicle/scripts/summarize.ts --repo=name --days=14 --format=narrative --with-context --md
                                                                              # Narrative recap (also exposed as /chronicle recap)

Structured (default) summaries stored in ~/.claude/chronicle/summaries/{global,repos}/ as JSON. Narrative summaries stored in ~/.claude/chronicle/recaps/ as markdown — see the Recap section above.

Flags:

• --weekly — preset for --days=7 with weekly file naming
• --days=N — explicit window override (any positive integer)
• --repo=NAME — restrict to a single project
• --format=narrative — produce 4-section markdown instead of structured JSON
• --with-context — also pull git log and curated memory into the prompt (narrative format only)
• --md — additionally print markdown body to stdout (narrative format only)

Automated Generation (Launchd)

Daily summaries run at midnight, weekly on Sunday 00:05.

Install services:

~/.claude/skills/chronicle/scripts/install-services.sh install summarize summarize-weekly

Check logs:

tail -f /tmp/chronicle-summarize.log
tail -f /tmp/chronicle-summarize-weekly.log

Model Strategy

Philosophy

Chronicle is about learning as we go:

• Start simple, evolve the structure
• Manual curation builds intuition for automation
• Memory blocks are living documents, not archives
• The curator is an editor, not a stenographer

Converted and distributed by TomeVault — claim your Tome and manage your conversions.