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 |
--limit N |
max rows (default 15) |
--json |
machine-readable output with full session ids and resume commands |
--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 (macOS) |
--claude-flags "..." |
extra flags for each resumed claude (e.g. "--chrome --dangerously-skip-permissions"); also shown in the printed resume lines and --json |
--terminal auto|iTerm2|Terminal |
which app --open drives (default: iTerm2 when installed) |
--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
# 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.- Tab opening drives iTerm2 or Terminal through
osascript, so it is macOS-only. On other platforms --open exits with a clear message; --open --dry-run still prints the commands so they can be pasted anywhere.
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.
Use --open only when the user explicitly asks to re-open or resume the sessions. Because the Bash tool pipes stdin, --open needs --yes; treat the user's request as the confirmation, and set the scope with --limit/--since so no unwanted session gets a tab. Pass --claude-flags only with flags the user named; state the permission-bypass warning in your reply whenever --dangerously-skip-permissions is among them.
Data sources and guarantees
~/.claude/history.jsonl is the fast index (prompt text, timestamp, project path, session id). CLAUDE_CONFIG_DIR is honored when set.~/.claude/projects/<encoded>/<session>.jsonl transcripts are parsed only for the displayed rows (title, branch, model, turn count). Project paths always come from the cwd/project fields, never decoded from folder names (that encoding is lossy).- Summary preference: Claude Code's own
ai-title line, else the first real user prompt, else (no prompt).
--smart privacy: the only path that leaves the machine. It shells out to the local claude CLI once and sends, for the listed sessions only, each session's 8-character id prefix, its title (first 150 characters), and its first user prompt (first 300 characters). No file bodies, no transcript contents, no other sessions. If claude is not on PATH, --smart is skipped with a warning and the offline summaries are used.- Turn count groups assistant streaming chunks by message id and is labeled approximate.
- Broken or partial JSONL lines are skipped, never fatal. Times shown in the local timezone.
- Display: day-grouped timeline (Today green, Yesterday amber), 14-day activity sparkline in the header, per-project colored dot (stable hash), four-level gray hierarchy with one accent color, per-session resume line indented with spaces only (safe to copy), and a small footer with a GitHub-star CTA and author link (clickable OSC 8 hyperlinks on supporting terminals). Falls back to plain text when piped or when NO_COLOR is set.
- Read-only: the tool never writes or deletes anything. It sees only sessions still on disk (Claude Code prunes old ones).
--open and --pick are the only side-effecting paths: --open drives iTerm2/Terminal via osascript, --pick execs claude -r in the chosen directory. Neither writes or touches session data.
Optional shell alias
alias recap='python3 ~/.claude/skills/recap/recap.py'
1---2name: recap-23description: 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, last activity, turn count, git branch, model, and a ready-to-paste resume command, and can re-open all of them 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", or invokes /recap. Reads only local files; the default run is instant and offline.4license: MIT5---6
7# recap: re-entry radar for Claude Code sessions
8
9One 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.
10
11## How to run it
12
13Personal or project install (the skill directory is on disk next to this file):
14
15```bash
16python3 ~/.claude/skills/recap/recap.py [flags]
17```
18
19Plugin install (Claude Code exports the plugin root):
20
21```bash
22python3 "$CLAUDE_PLUGIN_ROOT/skills/recap/recap.py" [flags]
23```
24
25Nothing to install beyond Python 3 (stdlib only, no third-party packages).
26
27| Flag | Meaning |
28|------|---------|
29| (none) | last 15 sessions, newest first, instant, no network |
30| `--since 7d` | only sessions active in the window (`30m`, `24h`, `7d`, `2w`) |
31| `--project foo` | filter by substring of the absolute project path |
32| `--limit N` | max rows (default 15) |
33| `--json` | machine-readable output with full session ids and resume commands |
34| `--smart` | real one-sentence summaries via ONE `claude -p` haiku call (network, ~10s) |
35| `--pick` | choose a row interactively, then `cd` + `claude -r` into it directly |
36| `--open` | open EVERY listed session in its own new terminal tab and resume it there (macOS) |
37| `--claude-flags "..."` | extra flags for each resumed `claude` (e.g. `"--chrome --dangerously-skip-permissions"`); also shown in the printed resume lines and `--json` |
38| `--terminal auto\|iTerm2\|Terminal` | which app `--open` drives (default: iTerm2 when installed) |
39| `--yes` / `-y` | skip the `--open` confirmation prompt (required when stdin is not a TTY) |
40| `--dry-run` | with `--open`: print the tabs and commands, open nothing |
41| `--color` | force ANSI colors when output is piped (e.g. inside Claude Code) |
42| `--plain` | no ANSI at all (also honors NO_COLOR / FORCE_COLOR env) |
43
44## Usage examples
45
46```bash
47# after a reboot: what was I doing?
48python3 ~/.claude/skills/recap/recap.py
49
50# everything in one repo this week
51python3 ~/.claude/skills/recap/recap.py --since 7d --project my-repo
52
53# jump straight back into a session
54python3 ~/.claude/skills/recap/recap.py --pick
55
56# re-open yesterday's whole working set in terminal tabs, browser enabled, no permission prompts
57python3 ~/.claude/skills/recap/recap.py --since 24h --limit 12 \
58 --open --yes --claude-flags "--chrome --dangerously-skip-permissions"
59
60# preview first, open nothing
61python3 ~/.claude/skills/recap/recap.py --open --dry-run
62
63# feed into other tooling
64python3 ~/.claude/skills/recap/recap.py --json --limit 50
65```
66
67## The `--open` flag
68
69Restores a whole working set at once. It opens one new tab per listed session and types the resume command into it. Rules:
70
71- The session recap itself runs in is skipped automatically (matched on `CLAUDE_CODE_SESSION_ID`), so it never re-opens itself.
72- Sessions whose project directory no longer exists are skipped and reported, never opened.
73- Scope comes from the normal filters, so `--limit` / `--since` / `--project` decide exactly which tabs appear. Check with `--dry-run` before committing.
74- Without `--yes` it asks for confirmation; with piped stdin (Claude Code's Bash tool) it refuses to open unless `--yes` is passed.
75- `--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.
76- Tab opening drives iTerm2 or Terminal through `osascript`, so it is macOS-only. On other platforms `--open` exits with a clear message; `--open --dry-run` still prints the commands so they can be pasted anywhere.
77
78## When Claude runs this skill
79
80Run 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.
81
82Use `--open` only when the user explicitly asks to re-open or resume the sessions. Because the Bash tool pipes stdin, `--open` needs `--yes`; treat the user's request as the confirmation, and set the scope with `--limit`/`--since` so no unwanted session gets a tab. Pass `--claude-flags` only with flags the user named; state the permission-bypass warning in your reply whenever `--dangerously-skip-permissions` is among them.
83
84## Data sources and guarantees
85
86- `~/.claude/history.jsonl` is the fast index (prompt text, timestamp, project path, session id). `CLAUDE_CONFIG_DIR` is honored when set.
87- `~/.claude/projects/<encoded>/<session>.jsonl` transcripts are parsed only for the displayed rows (title, branch, model, turn count). Project paths always come from the `cwd`/`project` fields, never decoded from folder names (that encoding is lossy).
88- Summary preference: Claude Code's own `ai-title` line, else the first real user prompt, else `(no prompt)`.
89- `--smart` privacy: the only path that leaves the machine. It shells out to the local `claude` CLI once and sends, for the listed sessions only, each session's 8-character id prefix, its title (first 150 characters), and its first user prompt (first 300 characters). No file bodies, no transcript contents, no other sessions. If `claude` is not on PATH, `--smart` is skipped with a warning and the offline summaries are used.
90- Turn count groups assistant streaming chunks by message id and is labeled approximate.
91- Broken or partial JSONL lines are skipped, never fatal. Times shown in the local timezone.
92- Display: day-grouped timeline (Today green, Yesterday amber), 14-day activity sparkline in the header, per-project colored dot (stable hash), four-level gray hierarchy with one accent color, per-session resume line indented with spaces only (safe to copy), and a small footer with a GitHub-star CTA and author link (clickable OSC 8 hyperlinks on supporting terminals). Falls back to plain text when piped or when NO_COLOR is set.
93- Read-only: the tool never writes or deletes anything. It sees only sessions still on disk (Claude Code prunes old ones). `--open` and `--pick` are the only side-effecting paths: `--open` drives iTerm2/Terminal via `osascript`, `--pick` `exec`s `claude -r` in the chosen directory. Neither writes or touches session data.
94
95## Optional shell alias
96
97```bash
98alias recap='python3 ~/.claude/skills/recap/recap.py'
99```
majiayu000