claude-work-tracker

A Claude Code skill + hook that lets you save, list, and resume in-flight work across sessions.

Long-running work gets spread across many Claude Code sessions, worktrees, and branches. It's easy to lose the thread: which session was that? what was the resume command? where did the committed files actually land? This package keeps a small, durable work log in ~/.claude/ and a paste-ready resume command for every work stream — and nudges you to keep it current before a session stops.

What's in here

Component	Path	What it does
`save-session` skill	`skills/save-session/SKILL.md`	Save/checkpoint the current session, list tracked work, or expand/update a single work item.
`save-session-nudge.sh` hook	`hooks/save-session-nudge.sh`	A `Stop` hook that nudges Claude once per session to sync the tracker — but only for sessions whose work is already tracked.
`install.sh`	`install.sh`	Copies (or symlinks) both into `~/.claude` and registers the hook in `settings.json`.

See skills/README.md and hooks/README.md for component detail.

How it works

The system stores work in ~/.claude/:

WORK-INDEX.md — the hub: a ## Tracked work table (one row per work stream) with status, the folder to resume in, and a per-entry paste-ready resume command.
WORK-<slug>.md — one detail doc per work stream: goal, deliverables (repos / branches / worktree paths / commit SHAs), key technical facts, research, and an open-items checklist.

The skill has three modes, picked from how you ask:

You say…	Mode
"save / checkpoint this session", "save my progress"	Save — recover the resume ID + home folder, gather context, write `WORK-<slug>.md`, update `WORK-INDEX.md`
"what work do I have going", "show my current work", "what was I working on"	List — read the hub, present each item with its resume command
"expand the X work item", "update the X tracker", "mark X done"	Expand — enrich a detail doc in place, sync the hub

The hook closes the gap that skills only run when invoked. On Stop, if the session's working directory appears in WORK-INDEX.md, it fires once to remind Claude to sync the tracker before stopping. Untracked sessions are never nudged, so it stays quiet until you've opted a session in by saving it.

Install

git clone <this-repo> claude-work-tracker
cd claude-work-tracker
./install.sh

Then start a new Claude Code session (or run /hooks to reload) to pick up the hook.

Options:

./install.sh --no-hook — install the skill + hook file but don't touch settings.json.
./install.sh --link — symlink the skill/hook from this repo instead of copying, so git pull updates your install.

The installer is idempotent — the Stop hook is registered only once. Requires jq for the automatic settings.json edit; without it the installer prints the entry to add manually.

Manual install

If you'd rather not run the script:

Copy skills/save-session/ to ~/.claude/skills/save-session/.
Copy hooks/save-session-nudge.sh to ~/.claude/hooks/ and chmod +x it.

Add a Stop hook to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/save-session-nudge.sh stop" }] }
    ]
  }
}

Usage

You: save this current session
Claude: <recovers session id + home folder, writes WORK-<slug>.md, updates WORK-INDEX.md>

You: what was I working on?
Claude: <lists tracked work with paste-ready resume commands>

You: mark the docs-screenshots item done
Claude: <updates that WORK-<slug>.md and the hub row>

Uninstall

rm -rf ~/.claude/skills/save-session ~/.claude/hooks/save-session-nudge.sh

Then remove the save-session-nudge.sh entry from the Stop array in ~/.claude/settings.json. Your WORK-INDEX.md and WORK-*.md docs are left untouched.

Requirements

Claude Code
bash, python3 (used by the skill to recover the resume session ID), and jq (used by the hook and the installer)

jimbobbennett/claude-work-tracker

README