/recap — Session Orientation & Awareness

Goal: Orient yourself fast. Rich context by default. Mid-session awareness with --now.

Usage

/recap           # Rich: retro summary, handoff, tracks, git, pulse
/recap --quick   # Minimal: git + focus only, no file reads
/recap --now     # Mid-session: timeline + jumps from AI memory
/recap --now deep # Mid-session: + handoff + tracks + connections

DEFAULT MODE (Rich)

Run the rich script, then add suggestions:

bun ~/.claude/skills/recap/recap-rich.ts

Script reads retro summaries, handoff content, tracks, git state. Then LLM adds:

What's next? (2-3 options based on context)

Step 2: Git context

git status --short
git log --oneline -1

Check what's appropriate from git status:

Uncommitted changes? → show them, suggest commit or stash
On a branch (not main)? → git log main..HEAD --oneline to see branch work
Branch ahead of remote? → suggest push or PR
Clean on main? → just show last commit, move on

Only read what matters — don't dump 10 commits if status is clean.

Step 3: Read latest ψ/ brain files

Sort all ψ/ files by modification time, read the most recent:

find ψ/ -name '*.md' -not -name 'CLAUDE.md' -not -name 'README.md' -not -name '.gitkeep' 2>/dev/null | xargs ls -t 2>/dev/null | head -5

Read those top 5 files. This recovers the same context /compact restores — handoffs, retros, learnings, drafts, whatever was touched last.

Step 4: Dig last session

PROJECT_BASE=$(ls -d "$HOME/.claude/projects/"*"$(basename "$(pwd)")" 2>/dev/null | head -1)
export PROJECT_DIRS="$PROJECT_BASE"
python3 ~/.claude/skills/dig/scripts/dig.py 1

Include in recap:

📡 Last session: HH:MM–HH:MM (Xm, N msgs) — [topic]

Need more? /dig 5 or /dig --timeline.

Also check pulse context:

cat ψ/data/pulse/project.json 2>/dev/null
cat ψ/data/pulse/heartbeat.json 2>/dev/null

If pulse data exists, add one line after the script output:

⚡ Session #X of Y | Streak: N days | Week: ±X% msgs

If pulse files don't exist, skip silently.

Total: 1 bash call + optional pulse read + LLM analysis

QUICK MODE (`/recap --quick`)

Minimal, no content reads:

bun ~/.claude/skills/recap/recap.ts

Script outputs git status + focus state (~0.1s). Then LLM adds:

What's next? (2-3 options based on git state)

"What's next?" Rules

If you see...	Suggest...
Handoff exists	Continue from handoff
Untracked files	Commit them
Focus = completed	Pick from tracks or start fresh
Branch ahead	Push or create PR
Streak active	Keep momentum going

Hard Rules

ONE bash call — never multiple parallel calls (adds latency)
No subagents — everything in main agent
Ask, don't suggest — "What next?" not "You should..."

NOW MODE (`/recap --now`)

Mid-session awareness from AI memory — no file reading needed. Use when user asks "where are we", "now", "status", "what are we doing".

AI reconstructs session timeline from conversation memory:

## This Session

| Time | Duration | Topic | Jump |
|------|----------|-------|------|
| HH:MM | ~Xm | First topic | - |
| HH:MM | ~Xm | Second topic | spark |
| HH:MM | ongoing | **Now**: Current | complete |

**Noticed**:
- [Pattern - energy/mode]
- [Jump pattern: sparks vs escapes vs completions]

**Status**:
- Energy: [level]
- Loose ends: [unfinished]
- Parked: [topics we'll return to]

**My Read**: [1-2 sentences]

---
**Next?**

Jump Types

Icon	Type	Meaning
spark	New idea, exciting
complete	Finished, moving on
return	Coming back to parked
park	Intentional pause
escape	Avoiding difficulty

Healthy session: Mostly sparks and completes Warning sign: Too many escapes = avoidance pattern

NOW DEEP MODE (`/recap --now deep`)

Same as --now but adds bigger picture context.

Step 1: Gather (parallel)

1. Current session from AI memory
2. Read latest handoff: ls -t ψ/inbox/handoff/*.md | head -1
3. Git status: git status --short
4. Tracks: cat ψ/inbox/tracks/INDEX.md 2>/dev/null

Step 2: Output

Everything from --now, plus:

### Bigger Picture

**Came from**: [Last session/handoff summary - 1 line]
**Working on**: [Current thread/goal]
**Thread**: [Larger pattern this connects to]

### Pending

| Priority | Item | Source |
|----------|------|--------|
| Now | [Current task] | This session |
| Soon | [Next up] | Tracks/discussion |
| Later | [Backlog] | GitHub/tracks |

### Connections

**Pattern**: [What pattern emerged]
**Learning**: [Key insight from session]
**Oracle**: [Related past pattern, if any]

**My Read**: [2-3 sentences - deeper reflection]

**Next action?**

Philosophy: Detect reality. Surface blockers. Offer direction. "Not just the clock. The map."

Version: 8.0 (Merged where-we-are into --now mode) Updated: 2026-02-10

recap