clerk

 ______     __         ______     ______     __  __    
/\  ___\   /\ \       /\  ___\   /\  == \   /\ \/ /    
\ \ \____  \ \ \____  \ \  __\   \ \  __<   \ \  _"-.  
 \ \_____\  \ \_____\  \ \_____\  \ \_\ \_\  \ \_\ \_\ 
  \/_____/   \/_____/   \/_____/   \/_/ /_/   \/_/\/_/  

繁體中文 | 日本語 | 한국어

Most AI tools are built for AI. clerk is built for humans.

Your Claude Code sessions disappear when you close the terminal. clerk turns them into a searchable knowledge base that you own.

The Problem

It's Friday afternoon. Time for the weekly report. You open git log and try to reconstruct what you actually did across three projects, eight sessions, and five days. Half the work isn't even in git — it was debugging, research, architecture decisions, conversations with Claude about trade-offs you've already forgotten.

Claude Code doesn't remember across sessions. And you shouldn't have to.

Why not just ask Claude?

You could try. Open Claude Code and ask "what did I do last week?"

It doesn't know. It only sees the current session. To look back, you'd need to find the right session ID, load it with --resume, ask for a summary, then repeat 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 takes a different approach: one API call per session, at the moment it ends, producing an incremental summary stored as plain markdown. By Friday, your week is already summarized. clerk report --days 7 reads those summaries and generates a structured report in one shot.

The Solution

clerk install

That's it. clerk runs entirely on your machine — no remote services, no accounts, no data leaving your laptop.

It hooks into Claude Code and works silently in the background:

Install once. Every session is automatically summarized, indexed, and searchable. No commands to remember, no habits to build.

Your data, your tools

clerk writes plain markdown with YAML frontmatter — no proprietary format, no lock-in. Summaries and index files are readable by:

• Any text editor (vim, VS Code, Sublime)
• Obsidian (graph view, tag pane work out of the box)
• Notion (import markdown)
• grep, ripgrep, or any CLI tool
• Your own scripts

If you uninstall clerk and Claude Code tomorrow, your summaries are still yours — organized, searchable, and linked.

How It Works

flowchart LR
    subgraph Claude Code
        A[Session Start] -->|hook| B[clerk punch]
        C[Session End] -->|hook| D[clerk feed]
    end

    subgraph Your Files
        E[sessions/]
        F[summary/]
        G[index/]
    end

    B --> E
    D --> F
    D --> G

    subgraph User Commands
        H["/clerk-resume"] -->|MCP| F
        I["/clerk-search"] -->|MCP| G
        J["clerk report"] --> F
    end

User Journey

sequenceDiagram
    actor You
    participant CC as Claude Code
    participant clerk
    participant Files as Your Files

    Note over You,Files: Daily work (automatic)
    You->>CC: Start coding session
    CC->>clerk: SessionStart hook
    clerk->>Files: Record session ID

    You->>CC: Work, debug, discuss...
    You->>CC: Close session
    CC->>clerk: SessionEnd hook
    clerk->>Files: Generate summary + index

    Note over You,Files: Repeat across days and projects...

    Note over You,Files: Friday afternoon
    You->>clerk: clerk report --days 7
    clerk->>Files: Read all summaries
    clerk->>CC: Send summaries for report generation
    CC-->>clerk: Structured report
    clerk->>You: Weekly report

Lifecycle

Data structure

~/.clerk/
├── summary/YYYYMMDD/slug.md    ← daily summaries per project
├── index/term.md               ← inverted index (tags, dates, projects, keywords)
├── sessions/slug.md            ← session ID history
├── cursor/                     ← incremental processing state
├── running/                    ← active feed process state
└── log/                        ← daily logs

File format

Each summary has YAML frontmatter with all related terms:

---
tags:
  - go
  - auth
  - jwt
  - 20260418
  - my-api-server
---

Each index file contains markdown links to matching summaries:

- [my-api-server+20260418](../summary/20260418/my-api-server.md)
- [my-api-server+20260419](../summary/20260419/my-api-server.md)

Terms naturally overlap — if "api" is both a word from the project slug and an AI-extracted tag, they point to the same file, creating connections across projects and topics.

Report

Friday afternoon, one command:

clerk report --days 7

clerk reads all summaries from the past 7 days, sends them to Claude, and outputs a structured report with three views:

• Summary — high-level overview of the entire period, organized by project
• By Date — what was done each day, broken down by project
• By Project — what was done on each project, broken down by date

Output goes to stdout. Save it, paste it, or pipe it wherever you need:

clerk report --days 7 -o weekly-report.md

Default is --days 1 (today only) — useful as a daily standup summary.

Want to include sessions that haven't ended yet? Add --active:

clerk report --days 7 --active

Note: --active processes active session transcripts on the spot, which uses additional Claude API calls. Without this flag, only completed sessions are included.

Example output:

### Summary (2026-04-14 ~ 2026-04-18)

#### my-api-server
Implemented user authentication with JWT, added rate limiting middleware,
and fixed connection pool leak under high concurrency.

#### frontend-app
Migrated from Vue 2 to Vue 3, replaced Vuex with Pinia, updated all unit tests.

---

### By Date

#### 2026-04-14
- **my-api-server**: Set up JWT auth with refresh token rotation
- **frontend-app**: Started Vue 3 migration, updated build config

#### 2026-04-16
- **my-api-server**: Added rate limiting middleware, fixed connection pool leak
- **frontend-app**: Replaced Vuex with Pinia, migrated 12 store modules

---

### By Project

#### my-api-server
- **2026-04-14**: JWT auth with refresh token rotation
- **2026-04-16**: Rate limiting middleware, connection pool leak fix

#### frontend-app
- **2026-04-14**: Vue 3 migration kickoff, build config update
- **2026-04-16**: Vuex → Pinia migration, 12 store modules converted

Installation

Quick Install

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/vulcanshen/clerk/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/vulcanshen/clerk/main/install.ps1 | iex

Then set up the hooks, MCP server, and skills:

clerk install

Package Managers

Build from Source

go install github.com/vulcanshen/clerk@latest

Commands

Internal commands (called by hooks, not by users):

Configuration

Config files

• Global: ~/.config/clerk/.clerk.json
• Project: .clerk.json in the current or any parent directory (nearest match wins)

Available settings

{
  "output": {
    "dir": "~/.clerk/",
    "language": "en"
  },
  "summary": {
    "model": "",
    "timeout": "5m"
  },
  "log": {
    "retention_days": 30
  },
  "feed": {
    "enabled": true
  }
}

Examples

# Disable feed for a specific project
cd /path/to/unimportant-project
clerk config set feed.enabled false

# Use a cheaper model globally
clerk config set -g summary.model haiku

# Change output language globally
clerk config set -g output.language en

MCP Tools

Available when MCP server is installed (clerk install mcp). These are called by Claude Code through skills — you don't need to invoke them directly.

Skills

Available when skills are installed (clerk install skills):

Troubleshooting

If something isn't working, run diagnosis first — it checks your environment and auto-fixes common issues:

clerk diagnosis

If the problem persists, export error logs and open an issue:

clerk diagnosis error --mask --days 7

The --mask flag redacts personal information (usernames, paths) so the output is safe to paste in a GitHub issue.

Shell Completion

# Zsh
mkdir -p ~/.zsh/completions
clerk completion zsh > ~/.zsh/completions/_clerk
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

# Bash
clerk completion bash > /etc/bash_completion.d/clerk

# Fish
clerk completion fish > ~/.config/fish/completions/clerk.fish

# PowerShell
New-Item -ItemType Directory -Path (Split-Path $PROFILE) -Force
clerk completion powershell | Set-Content $PROFILE

License

GPL-3.0