claude-code-recap

<div align="center"> <img src="assets/banner.png" width="100%" alt="recap — get back into every Claude Code session">

<b>See every recent Claude Code session across every project on your machine, and get the exact command to jump back into any of them.</b>

<br> <br> <a href="https://github.com/noluyorAbi/claude-code-recap/stargazers"> <img src="https://img.shields.io/badge/%E2%98%85%20Star%20this%20repo-0b0b0b?style=for-the-badge&logo=github&logoColor=white&labelColor=0b0b0b" height="54" alt="Star claude-code-recap on GitHub"> </a> &nbsp;&nbsp; <a href="https://www.npmjs.com/package/claude-code-recap"> <img src="https://img.shields.io/badge/Install-npx%20claude--code--recap-d97757?style=for-the-badge&logo=npm&logoColor=white&labelColor=0b0b0b" height="54" alt="Install via npx"> </a> &nbsp;&nbsp; <a href="https://www.adatepe.dev/blog/resume-claude-code-sessions-across-projects"> <img src="https://img.shields.io/badge/Read%20the%20write--up-adatepe.dev-3a3a3a?style=for-the-badge&logo=readme&logoColor=white&labelColor=0b0b0b" height="54" alt="Read the write-up on adatepe.dev"> </a> <br> <br>

<code>npx claude-code-recap</code>  then  <code>/recap</code>

<br> <br>

<a href="https://www.npmjs.com/package/claude-code-recap"><img src="https://img.shields.io/npm/v/claude-code-recap?style=for-the-badge&logo=npm&logoColor=white&label=npm&labelColor=0b0b0b&color=d97757" alt="npm version"></a> <a href="https://www.npmjs.com/package/claude-code-recap"><img src="https://img.shields.io/npm/dm/claude-code-recap?style=for-the-badge&logo=npm&logoColor=white&label=downloads&labelColor=0b0b0b&color=3a3a3a" alt="npm downloads per month"></a> <a href="https://code.claude.com/docs/en/skills"><img src="https://img.shields.io/badge/Claude_Code-skill_%2B_plugin-d97757?style=for-the-badge&logo=claude&logoColor=white&labelColor=0b0b0b" alt="Claude Code skill and plugin"></a> <a href="package.json"><img src="https://img.shields.io/badge/dependencies-zero-3a3a3a?style=for-the-badge&labelColor=0b0b0b" alt="zero dependencies"></a> <a href="https://github.com/noluyorAbi/claude-code-recap/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/noluyorAbi/claude-code-recap/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=ci&labelColor=0b0b0b" alt="ci"></a>

<br>

<a href="assets/demo.mp4"><img src="assets/demo.gif" alt="recap listing recent Claude Code sessions across several projects, then re-opening them in terminal tabs" width="100%"></a>

_{The GIF above is a downsampled loop. Full-quality recording: <a href="assets/demo.mp4"><code>assets/demo.mp4</code></a>.}

</div> <br>

Claude Code's built-in /resume only lists sessions for the directory you are standing in. After a reboot, a crash, or a week of jumping between five repos, there is no way to answer "what was I working on, and where did I leave off". recap answers that in one command, and can re-open a whole working set in terminal tabs.

The full story behind recap, why it reads exactly two files and writes nothing, the shlex.quote safety in --open, and the zero-dependency stance: Resume Claude Code Sessions Across Every Project on adatepe.dev.

---

<img src="assets/icons/clock.svg" width="16" align="center"> What it does

recap reads the session logs Claude Code already writes to disk and prints a day-grouped timeline of your recent sessions. Per session: last activity, the absolute project path, a short summary, where the session stopped, an approximate turn count, the git branch, the model, the session id, and a ready-to-paste cd <path> && claude -r <id> resume command.

• Every project on the machine, not just the current directory.
• Every row says where that session stopped, so you re-enter on the open question rather than the opening prompt.
• --pick jumps straight into one session.
• --open re-opens all of them, each in its own terminal tab, already resumed. iTerm2, Terminal, tmux, wezterm, kitty, gnome-terminal, konsole.
• --grep finds the session you solved something in. --dirty shows which projects you left work sitting in.
• Pure Python 3 standard library. No dependencies, no build step.
• Offline and read-only by default. The only network path is the opt-in --smart flag.

<img src="assets/icons/download.svg" width="16" align="center"> Install

Three ways in, all live. The plugin marketplace is the native path; npx and curl | sh install the same skill into ~/.claude/skills/recap.

1. Plugin marketplace (recommended)

The repo is its own Claude Code marketplace. Two lines inside any Claude Code session:

/plugin marketplace add noluyorAbi/claude-code-recap
/plugin install claude-code-recap@noluyorabi-plugins

Then /reload-plugins, and invoke it as:

/claude-code-recap:recap

Plugin skills are namespaced plugin-name:skill-name, so this cannot collide with anything else you have installed. Add the marketplace by repo (owner/repo), not by a direct URL to marketplace.json: a URL-added marketplace downloads only that one file, and the entry's relative source (./) would not resolve.

2. npx

Installs the skill into your Claude Code skills directory (~/.claude/skills/recap, or $CLAUDE_CONFIG_DIR/skills/recap):

npx claude-code-recap

Then invoke it as /recap. The package has no postinstall hook; it writes only when you run the command. It records a sha256 manifest of the files it wrote and refuses to clobber a directory it did not install or files you have edited, unless you pass --force.

npx claude-code-recap --force      # overwrite local edits
npx claude-code-recap --uninstall  # remove what it installed

3. curl

Same install, no Node:

curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh

Same guarantees as the npx path: sha256 manifest, no silent overwrite, --force and --uninstall supported.

curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh -s -- --uninstall

4. skills CLI

If you use the skills directory CLI, recap resolves straight from this repo and installs across every agent it manages:

npx skills add noluyorAbi/claude-code-recap

Claude Code picks up ~/.claude/skills without a restart. Restart only if that directory did not exist when the session started.

Pick one path. Installing the skill and the plugin gives you /recap and /claude-code-recap:recap side by side; they will not conflict, but you carry two copies of the description in the skill listing.

<img src="assets/icons/terminal.svg" width="16" align="center"> What you see

◆ recap                                         6 sessions · 5 projects   14d ▂▁▄▃▅▂▆█▃▅▇▄▆█

── Today ─────────────────────────────────────────────────────────────────────────────────

  1 ● 14:22 12m ago  Fix the flaky auth test in the checkout flow                a3f91c02
             ↳ claude: Both tests pass now. Shall I squash and open the PR?
             ~/repos/shop-web  ·  ⎇ fix/flaky-auth  ·  opus-4.8  ·  46 turns  ·  ✎ 4 uncommitted  ·  ↑ 2 unpushed
             cd ~/repos/shop-web && claude -r a3f91c02-7b4e-4d19-9c2a-5f83e6d1b704

  2 ● 11:05  3h ago  Rewrite the ingest worker to stream instead of buffer       6d20be14
             ↳ you: hold on, the backpressure case is still wrong
             ~/repos/pipeline  ·  ⎇ main  ·  sonnet-4.5  ·  18 turns  ·  ✎ 1 uncommitted
             cd ~/repos/pipeline && claude -r 6d20be14-0a8f-49c7-8b31-1e4d90c7aa52

  3 ● 09:41  5h ago  Draft the migration plan for the billing schema             c17ff5a9
             ↳ claude: Plan written to MIGRATION.md, nothing applied yet.
             ~/repos/billing-svc  ·  ⎇ chore/migrate  ·  opus-4.8  ·  7 turns
             cd ~/repos/billing-svc && claude -r c17ff5a9-2e6b-4f10-9d55-b0c3e7182f44

── Yesterday ─────────────────────────────────────────────────────────────────────────────

  4 ● 22:58  1d ago  Debug the flexbox overflow in the sidebar                   9b3c0d67
             ↳ claude: The overflow is gone at every breakpoint I tried.
             ~/repos/shop-web  ·  ⎇ fix/flaky-auth  ·  sonnet-4.5  ·  31 turns
             cd ~/repos/shop-web && claude -r 9b3c0d67-58a1-4c02-91ff-6ea27d3b8c19

  5 ● 17:12  1d ago  Set up the release workflow and the version check           40ea8b25
             ↳ claude: CI is green on the tag push.
             ~/.claude  ·  opus-4.8  ·  12 turns
             cd ~/.claude && claude -r 40ea8b25-c934-4d7e-a06b-72f1958e3dd0

 turns ≈ user + assistant messages   ·   ↳ where the session stopped
 --pick jump in   ·   --open all in tabs   ·   --grep search   ·   --dirty unfinished work   ·   --smart AI summaries

In a real terminal this is colored: a day-grouped timeline (Today green, Yesterday amber), a 14-day activity sparkline in the header, and a stable per-project colored dot so the same repo keeps the same color across runs. Color is disabled automatically when the output is piped, and by NO_COLOR. The resume line is indented with spaces only, so a triple-click copies a command that actually runs.

The ↳ line is the part you re-enter on. A session that finished ends on Claude's reply, one you interrupted ends on the prompt it never answered, and the row shows whichever came last. --no-tail hides it. The ✎ and ↑ counts come from --dirty and are the fastest way to spot the project you left work sitting in.

Flags

| Flag | Default | What it does | |------|---------|--------------| | --since SPEC | off | only sessions active within the window: 30m, 24h, 7d, 2w | | --project SUBSTR | off | only sessions whose absolute project path contains SUBSTR (separators are interchangeable, so my_app, my-app and work/my_app all match /work/my_app) | | --grep PATTERN | off | only sessions whose conversation matches PATTERN (regular expression, case-insensitive), with the matching excerpt shown on the row | | --dirty | off | annotate each row with its project's uncommitted and unpushed work | | --limit N | 15 | maximum number of sessions listed | | --json | off | machine-readable output with full session ids and resume commands | | --no-tail | off | hide the ↳ line showing where each session stopped | | --smart | off | replace summaries with real one-sentence descriptions, via ONE claude -p call (network) | | --pick | off | pick a row interactively, then cd and claude -r straight into it | | --open | off | open every listed session in its own new terminal tab and resume it there | | --claude-flags "FLAGS" | "" | extra flags for each resumed claude, passed through verbatim | | --terminal NAME | auto | which terminal --open drives: iTerm2, Terminal, tmux, wezterm, kitty, gnome-terminal, konsole. auto prefers tmux when you are inside it, then the platform default | | --yes, -y | off | skip the --open confirmation prompt; required when stdin is not a TTY | | --dry-run | off | with --open: print the tabs and commands, open nothing | | --color | auto | force ANSI colors even when the output is piped | | --plain | off | disable all ANSI colors |

Environment: CLAUDE_CONFIG_DIR overrides ~/.claude. NO_COLOR, FORCE_COLOR and CLICOLOR_FORCE are honored. CLAUDE_CODE_SESSION_ID is read by --open so it never re-opens the session it is running in.

Run it directly, without the skill layer:

python3 ~/.claude/skills/recap/recap.py --since 7d --project shop-web
python3 ~/.claude/skills/recap/recap.py --json --limit 50 | jq '.[].projectPath'

# where did I solve this before?
python3 ~/.claude/skills/recap/recap.py --grep "connection pool" --limit 5

# which projects am I sitting on unfinished work in?
python3 ~/