/recap

name: recap
description: Show recent Claude Code sessions across all projects, so the user can re-enter work after a reboot or context switch. Lists per session the absolute project path, a short summary, where the session stopped, last activity, turn count, git branch, model, and a ready-to-paste resume command; can search sessions by what was said in them, flag projects with uncommitted or unpushed work, and re-open every session at once in new terminal tabs. Use when the user asks "what was I working on", "which projects did I touch recently", "where did I leave off", "list my recent sessions", "how do I get back into that session", "open all my sessions again", "which session did I fix X in", "where do I still have uncommitted work", or invokes /recap. Reads only local files; the default run is instant and offline.
license: MIT
metadata:
  version: "1.3.0"
  author: noluyorAbi
  source: https://github.com/noluyorAbi/claude-code-recap

recap: re-entry radar for Claude Code sessions

One command, full overview of recent sessions across every project on this machine. Built for the post-reboot moment: which projects, what was each session about, and the exact command to jump back in.

How to run it

Personal or project install (the skill directory is on disk next to this file):

python3 ~/.claude/skills/recap/recap.py [flags]

Plugin install (Claude Code exports the plugin root):

python3 "$CLAUDE_PLUGIN_ROOT/skills/recap/recap.py" [flags]

Nothing to install beyond Python 3 (stdlib only, no third-party packages).

| Flag | Meaning | |------|---------| | (none) | last 15 sessions, newest first, instant, no network | | `--since 7d` | only sessions active in the window (`30m`, `24h`, `7d`, `2w`) | | `--project foo` | filter by substring of the absolute project path; separators are interchangeable (`my_app`, `my-app`, `work/my_app`) | | `--grep PATTERN` | only sessions whose conversation matches PATTERN (regex, case-insensitive); the matching excerpt replaces the `↳` line | | `--dirty` | annotate each row with its project's uncommitted and unpushed counts (read-only git calls) | | `--limit N` | max rows (default 15) | | `--json` | machine-readable output with full session ids and resume commands | | `--no-tail` | hide the `↳` line that says where each session stopped | | `--smart` | real one-sentence summaries via ONE `claude -p` haiku call (network, ~10s) | | `--pick` | choose a row interactively, then `cd` + `claude -r` into it directly | | `--open` | open EVERY listed session in its own new terminal tab and resume it there | | `--claude-flags "..."` | extra flags for each resumed `claude` (e.g. `"--chrome --dangerously-skip-permissions"`); also shown in the printed resume lines and `--json` | | `--terminal NAME` | which terminal `--open` drives: `iTerm2`, `Terminal`, `tmux`, `wezterm`, `kitty`, `gnome-terminal`, `konsole` (default: auto-detected) | | `--yes` / `-y` | skip the `--open` confirmation prompt (required when stdin is not a TTY) | | `--dry-run` | with `--open`: print the tabs and commands, open nothing | | `--color` | force ANSI colors when output is piped (e.g. inside Claude Code) | | `--plain` | no ANSI at all (also honors NO_COLOR / FORCE_COLOR env) |

Usage examples

# after a reboot: what was I doing?
python3 ~/.claude/skills/recap/recap.py

# everything in one repo this week
python3 ~/.claude/skills/recap/recap.py --since 7d --project my-repo

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

# where did I leave work uncommitted?
python3 ~/.claude/skills/recap/recap.py --dirty --since 7d

# jump straight back into a session
python3 ~/.claude/skills/recap/recap.py --pick

# re-open yesterday's whole working set in terminal tabs, browser enabled, no permission prompts
python3 ~/.claude/skills/recap/recap.py --since 24h --limit 12 \
  --open --yes --claude-flags "--chrome --dangerously-skip-permissions"

# preview first, open nothing
python3 ~/.claude/skills/recap/recap.py --open --dry-run

# feed into other tooling
python3 ~/.claude/skills/recap/recap.py --json --limit 50

The `--open` flag

Restores a whole working set at once. It opens one new tab per listed session and types the resume command into it. Rules:

• The session recap itself runs in is skipped automatically (matched on `CLAUDE_CODE_SESSION_ID`), so it never re-opens itself.
• Sessions whose project directory no longer exists are skipped and reported, never opened.
• Scope comes from the normal filters, so `--limit` / `--since` / `--project` decide exactly which tabs appear. Check with `--dry-run` before committing.
• Without `--yes` it asks for confirmation; with piped stdin (Claude Code's Bash tool) it refuses to open unless `--yes` is passed.
• `--claude-flags` is passed through verbatim to every tab. `--dangerously-skip-permissions` disables all permission checks in each opened session; the script prints a warning before doing it.
• The terminal is auto-detected: tmux when running inside it (even on macOS), else iTerm2/Terminal on macOS via `osascript`, else wezterm, kitty, gnome-terminal or konsole. `--terminal NAME` forces one. Where none can be driven, `--open` says so and opens nothing; `--open --dry-run` needs no terminal and still prints the commands.
• Every opened tab outlives `claude`: quitting a resumed session leaves a shell in that project instead of closing the restored window.

When Claude runs this skill

Run the script with Bash, ALWAYS with `--color` (tool output is piped, auto-detection would strip the colors; Claude Code renders ANSI). Add `--since`/`--project` if the user narrowed the question, then relay the table. Quote the resume command (`cd <path> && claude -r <id>`) for any session the user wants to re-enter. Only add `--smart` if the user explicitly asks for better summaries; it makes a network call.

Reach for `--grep` when the user is looking for a session by