What Clerk Does
Clerk is a local-first tool that automatically summarizes your Claude Code sessions into plain Markdown files with YAML frontmatter. When you close a Claude Code session, Clerk makes one API call to generate an incremental summary that's stored locally on your machine. No remote services, no accounts, no data leaves your laptop.
The tool creates three types of files:
sessions/- Raw session trackingsummary/- Markdown summaries of each sessionindex/- Searchable indexes
Setup - One Command
clerk install
That's it. Clerk hooks into Claude Code and works silently in the background. Once installed, every session is automatically summarized, indexed, and searchable without any additional commands or habit changes.
How To Use It
Daily Workflow (Automatic)
Nothing changes in your daily workflow. You work in Claude Code as usual. When you close a session, Clerk automatically:
- Captures the session end
- Generates a summary via Claude API
- Stores it as Markdown with YAML frontmatter
- Updates the search index
Weekly Reporting
Instead of trying to reconstruct your week from memory or git logs, run:
clerk report --days 7
This reads all the summaries from the past week and generates a structured report in one shot. No need to manually resume old sessions or burn tokens re-reading entire transcripts.
Session Search and Resume
Clerk includes MCP servers that integrate directly with Claude Code:
/clerk-resume- Resume any past session from your summaries/clerk-search- Search across all your session summaries
These commands work within Claude Code itself, letting you reference past work without leaving your current session.
Why Plain Markdown Matters
Clerk's summaries use plain Markdown with YAML frontmatter, which means:
- No lock-in: If you uninstall Clerk tomorrow, your summaries are still readable
- Universal compatibility: Works with any text editor (vim, VS Code, Sublime)
- Tool integration: Obsidian's graph view and tag pane work out of the box
- Easy import: Import directly into Notion or other tools
- CLI friendly: Search with
grep,ripgrep, or your own scripts
The Token Economics
Without Clerk, looking back at past work requires:
- Finding the right session ID
- Loading it with
claude code --resume <session-id> - Asking Claude to summarize the entire transcript
- Repeating for every session across every project
Each time, Claude re-reads the entire raw transcript, burning tokens to reconstruct what could have been saved in a single markdown file. Clerk's approach uses one API call per session at the moment it ends, producing incremental summaries that are far more token-efficient.
When Clerk Shines
- Weekly reporting - Generate comprehensive reports without manual effort
- Cross-session debugging - Search for when you solved similar problems before
- Architecture decisions - Track trade-off discussions you've already forgotten
- Project handoffs - Share summarized context with team members
- Personal knowledge base - Build a searchable record of your development learning
Installation and Requirements
Clerk is available on GitHub and requires:
- Claude Code installed and configured
- Claude API access (for summary generation)
- Local storage for your session summaries
Since it runs entirely locally, you maintain complete control over your data while getting the benefits of automated session summarization.
