Forem: Vulcan Shen

clerk: Auto-Summarize Your Claude Code Sessions

Vulcan Shen — Fri, 17 Apr 2026 06:24:08 +0000

The Friday Afternoon Problem

It's 4 PM on Friday. Your manager asks for the weekly report. You stare at your terminal, trying to remember what you did on Monday. Was it the auth refactor or the API migration? Which project was that even in?

You open git log. Scroll. Scroll. Scroll. Piece together commit messages across 4 repositories. Thirty minutes later, you have a rough draft that still feels incomplete.

Sound familiar?

The Daily Problem

But it's not just Fridays. Every morning, you open Claude Code and realize you forgot to use --resume. Yesterday's session had all the context — the architecture decisions, the debugging steps, the half-finished plan. Now it's gone, buried in a pile of session IDs.

What if your sessions just... remembered themselves?

That's what clerk does. Install once, forget about it. Every session is automatically summarized when it ends.

brew install vulcanshen/tap/clerk
clerk install

No configuration needed. No commands to remember. No habits to build.

clerk runs entirely on your machine — no remote services, no accounts, no data leaving your laptop. All you need is Claude Code.

What You Get

Auto-generated daily summaries

Every time a Claude Code session ends, clerk processes the transcript and saves a structured summary as a markdown file, organized by date and project:

~/.clerk/
├── summary/
│   ├── 20260414/
│   │   ├── projects-my-api.md
│   │   └── work-frontend.md
│   └── 20260416/
│       ├── projects-my-api.md
│       └── work-frontend.md
├── tags/
│   ├── auth.md
│   ├── vue.md
│   └── refactor.md
└── ...

Context recovery

Forgot --resume? No problem. Just type /clerk-resume in Claude Code:

Claude reads your past summaries and transcripts, rebuilds the context, and you're back where you left off.

Semantic search

Need to find that session where you worked on authentication?

Type /clerk-search and say "auth". clerk uses AI-powered semantic matching — it doesn't just string-match tags, it understands that "auth" relates to "jwt", "oauth", "login".

Weekly reports

This is the one that saves Friday afternoons:

clerk report --days 7

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

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

#### my-api-server
Implemented JWT auth with refresh tokens, added rate limiting
middleware, 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**: JWT auth with refresh token rotation
- **frontend-app**: Started Vue 3 migration, updated build config

#### 2026-04-16
- **my-api-server**: Rate limiting middleware, connection pool fix
- **frontend-app**: Vuex → Pinia, 12 store modules migrated

---

### By Project

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

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

Save it, paste it into Slack, attach it to your standup — whatever works for you:

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

Default is --days 1 — great for daily standup summaries.

Need to include sessions that haven't ended yet? Add --realtime:

clerk report --days 7 --realtime

This processes active session transcripts on the spot. Note that it uses additional Claude API calls — without the flag, only completed sessions are included.

Obsidian Integration

If you use Obsidian, clerk's output directory works as a vault out of the box. Summaries include YAML frontmatter tags, and tag files use standard markdown links. Open ~/.clerk/ in Obsidian and you get a graph view connecting tags to summaries across all your projects.

Installation

macOS / Linux

brew install vulcanshen/tap/clerk
clerk install

Other options

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

# Or build from source
go install github.com/vulcanshen/clerk@latest

Then run clerk install to set up hooks, MCP server, and slash commands.

How It Works Under the Hood

clerk install registers SessionStart and SessionEnd hooks in Claude Code
When a session ends, the hook triggers clerk feed in the background
Feed reads only new transcript lines since the last run (cursor tracking)
It calls claude -p to merge new activity into the existing daily summary
Tags are extracted and indexed for search

The whole thing is a single Go binary. No dependencies beyond Claude Code itself.

GitHub: github.com/vulcanshen/clerk

If you have feedback or ideas, issues and PRs are welcome!

I built a CLI to stop explaining what /etc/hosts is

Vulcan Shen — Sun, 12 Apr 2026 11:49:16 +0000

Last month, a PM asked me to point api.staging.local to a new IP. I spent 15 minutes explaining what /etc/hosts is. Then I did it for them anyway.

This happens a lot. So I built hostfile — a CLI that turns hosts file management into copy-pasteable one-liners.

What's wrong with existing tools

Manual editing is risky. One wrong move and DNS resolution breaks. Non-technical users shouldn't be anywhere near vim /etc/hosts.

GUI tools like SwitchHosts exist, but they're overkill when you just need someone to run one command. You can't paste a GUI into Slack.

Other CLIs exist and work fine for developers who know what they're doing. But when you need a non-technical person to run one command without supervision, most fall apart.

What hostfile does differently

Managed block isolation. hostfile only touches entries between its own markers. Your hand-written entries are never modified:

# Your stuff — safe
127.0.0.1  localhost

#### hostfile >>>>>
192.168.1.100  web.local api.local
#### hostfile <<<<<

Enable/disable without deleting. Need to temporarily turn off an entry? hostfile disable api.local. Turn it back on with hostfile enable api.local. No re-typing IPs.

JSON I/O and pipelines. Export your config as JSON, pipe it to another machine, or feed it into scripts:

# Export
hostfile show --json
# {"192.168.1.100": ["web.local", "api.local"]}

# Import via pipeline
echo '{"10.0.0.1":["db.local"]}' | hostfile merge -

# Sync between machines
hostfile show --json | ssh prod hostfile apply -

Automatic privilege escalation. hostfile handles sudo, doas, or gsudo on Windows automatically. Users never need to remember.

Input validation. Bad JSON, invalid IPs, or garbage text gets rejected before touching your hosts file.

Quick start

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.sh | sh

# Add entries
hostfile add 192.168.1.100 web.local api.local

# Save a snapshot before making changes
hostfile save before-migration

# Roll back if needed
hostfile load before-migration

# Done with this setup
hostfile clean

Install

# macOS / Linux
brew install vulcanshen/tap/hostfile

# Windows
irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.ps1 | iex

Also available as .deb, .rpm, and Scoop. See the README for all options.

Real-world use case: Field engineers on customer sites

The PM story is real, but here's an even more common scenario:
field engineers (FAE) and consultants who work across multiple
network environments.

When you're on-site at a customer, you need their internal
domains to resolve correctly. When you're back at the office,
you need your company's internal domains. On Windows, this is
painful — the network adapter DNS settings are buried deep in
the UI, limited to two entries, and you have to redo everything
every single time you switch environments.

The hosts file is actually the most portable solution. With
hostfile, the workflow becomes:

Leaving for customer site

hostfile save company # snapshot your current setup
hostfile clean # clear everything, use customer DNS

Back at the office

hostfile load company # restore in one command

No more digging through network adapter settings. No more
forgetting to reset DNS before connecting to company VPN.
Just two commands.

This isn't a revolutionary tool. It solves one specific problem: making hosts file changes safe and accessible to anyone who can copy-paste a command. If that's a problem you have, give it a try.

GitHub: vulcanshen/hostfile