@aiplumber/session-recall

Pull context from previous Claude Code sessions. Sessions end, context resets - this tool lets you continue where you left off.

> What is Claude Code? Anthropic's official CLI for Claude - an agentic coding assistant that runs in your terminal. This tool parses Claude Code's conversation logs stored in ~/.claude/projects/.

The Problem

Every Claude Code session starts fresh. Yesterday's breakthroughs, decisions, and momentum - gone. You're left explaining context again, losing the thread of what you were building.

The Solution

session-recall extracts the signal from your session logs, filtering out the noise. Import previous context without blowing your token budget.

Installation

``bash npm install -g @aiplumber/session-recall`

Requires Node.js 16+.

`Quick Start`

`bash

`Check what sessions exist (CWD project)`


session-recall last 3 -d
Pull last session context

session-recall last 1 -f text
List tool calls from last session

session-recall tools
Get specific tool result

session-recall tools --show 014opBVN


What Gets Filtered (Noise)
Session-recall strips out the bloat that eats tokens without adding value:
Tool Artifacts:
- File contents you read (they exist in files, don't duplicate)
- Code you generated (it's in the codebase now)
- Command outputs (already processed, outcome captured)
- Error logs user pasted (dealt with, moved on)

Operational Chatter: - "Let me read that file" (just read it) - "I'll run this command" (just the result matters) - Shell commands without context (ls, cd, npm install) - System reminders and progress updates

Message Types Filtered: -type: progress- tool execution noise -type: system- system messages -type: file-history-snapshot- file state snapshots - Tool results (unless--logisticsmode) - User messages > 200 chars (usually pasted logs)

`What's Kept (Signal)`

The discourse that matters:

Short user messages: - "nooooo" (3 words, massive redirection) - "for real?" (pushback, led to honesty) - "A, B, C" (decisions locked in)

Questions that shaped direction: - "how do you think we will get clarity?" - "what is the workproduct?"

Aha moments: - "did we just discover..." - "YES. Now I see..."

The rule: Short = signal. Long = usually noise.

User's 3-word redirection carries more weight than assistant's 500-word explanation.

`Commands`

`$3`

`bash

`Check what's available (dry run)`


session-recall last 3 -d
Pull last session from current project

session-recall last 1 -f text
Pull last 2 sessions

session-recall last 2 -f text
Scan all projects (not just CWD)

session-recall last 5 --all -d

$3

`bash

`List all tool calls from last session`


session-recall tools
Get specific tool result by ID

session-recall tools --show 014opBVN

$3

`bash

`Create a checkpoint (marker that gets logged)`


session-recall --checkpoint "finished research"
session-recall --checkpoint "starting implementation"
List all checkpoints

session-recall checkpoints
Recall only messages AFTER a checkpoint

session-recall last 1 --after "finished research"


$3
Tag any session content for later recall. Critical items auto-surface.

`bash

`Preview what would be tagged (without tagging)`


session-recall --back 3 toolcall
Tag most recent tool call as critical

session-recall tag toolcall critical "found the root cause"
Tag tool call from 3 calls ago

session-recall tag toolcall --back 3 important "useful data here"
Tag other content types

session-recall tag agentcall critical "minion discovered pattern"
session-recall tag discourse important "user clarified requirement"
session-recall tag checkpoint critical "breakthrough moment"
List all tags

session-recall tags
Filter tags

session-recall tags critical      # Only critical level
session-recall tags toolcall      # Only tool calls

Types: toolcall, agentcall, discourse, checkpoint

Levels: -critical- Auto-injected in recall output (always shown) -important - Shown with --show-importantflag -bookmark - Lookup only, never injected

`$3`

`bash

`Compress with tool calls collapsed (action mode)`


session-recall rinse session.jsonl --gotime
Keep tool results truncated (see what was done)

session-recall rinse session.jsonl --logistics
Check token cost first

session-recall rinse session.jsonl --gotime -d

$3

`bash

`Show session stats`


session-recall state session.jsonl
Compare import costs

session-recall cost session.jsonl
Extract last N exchanges

session-recall hot session.jsonl --last 30
Parse to filtered jsonl

session-recall parse session.jsonl -f text


Use Cases
$3

`bash

`See what you worked on`


session-recall last 1 -d
Pull the context

session-recall last 1 -f text

$3

`bash

`Mark milestones as you go`


session-recall --checkpoint "research complete"
session-recall --checkpoint "design approved"
session-recall --checkpoint "implementation started"
Tomorrow, resume from any point

session-recall last 1 --after "design approved"

$3

`bash

`What did that command output?`


session-recall tools
session-recall tools --show 014opBVN

$3

`bash

`Combine multiple sessions`


session-recall last 3 -f text > context.txt

$3

`bash

`Run commands, discover something important`


Bash: grep "API_KEY" .env
Output: API_KEY=sk-live-abc123...
Realize that was important (2 tool calls ago)

session-recall --back 2 toolcall
Shows: UUID abc123 | grep "API_KEY" .env | API_KEY=sk-...
Tag it

session-recall tag toolcall --back 2 critical "found exposed API key"
Next session - critical items auto-surface in recall

session-recall last 2
[16:42:15] ⚠ CRITICAL [toolcall] grep "API_KEY" .env

           Reason: "found exposed API key"

           Result: API_KEY=sk-live-abc123...


Output Modes

| Flag | Tool Results | Use Case | |------|--------------|----------| |--gotime | [Ran: ls -la]| Action mode - let's move | |--logistics | drwxr-xr-x... (truncated) | Planning - show me the receipts |

`Token Economics`

Session-recall helps you fit more context in less tokens:

| Raw Session | After Rinse | Savings | |-------------|-------------|---------| | 750 messages | ~250 messages | 67% | | ~50k tokens | ~7k tokens | 86% |

The filtering isn't lossy - it's removing redundancy. The signal-to-noise ratio goes up dramatically.

`How It Works`

Claude Code stores conversations in ~/.claude/projects//` as JSONL files. Each line is a message with metadata.

Session-recall:
1. Maps your CWD to the project folder
2. Reads the JSONL conversation logs
3. Filters out noise (tool results, system messages, long pastes)
4. Collapses tool calls to summaries
5. Outputs clean discourse

License

MIT

Author

Hung Nguyen (@aiplumber)

@aiplumber/session-recall

Pull context from previous Claude Code sessions. Sessions end, context resets - this tool lets you continue where you left off.

The Problem

Every Claude Code session starts fresh. Yesterday's breakthroughs, decisions, and momentum - gone. You're left explaining context again, losing the thread of what you were building.

The Solution

session-recall extracts the signal from your session logs, filtering out the noise. Import previous context without blowing your token budget.

Installation

``bash npm install -g @aiplumber/session-recall`

Requires Node.js 16+.

`Quick Start`

`bash

`Check what sessions exist (CWD project)`


session-recall last 3 -d
Pull last session context

session-recall last 1 -f text
List tool calls from last session

session-recall tools
Get specific tool result

session-recall tools --show 014opBVN


What Gets Filtered (Noise)
Session-recall strips out the bloat that eats tokens without adding value:
Tool Artifacts:
- File contents you read (they exist in files, don't duplicate)
- Code you generated (it's in the codebase now)
- Command outputs (already processed, outcome captured)
- Error logs user pasted (dealt with, moved on)

`What's Kept (Signal)`

The discourse that matters:

Short user messages: - "nooooo" (3 words, massive redirection) - "for real?" (pushback, led to honesty) - "A, B, C" (decisions locked in)

Questions that shaped direction: - "how do you think we will get clarity?" - "what is the workproduct?"

Aha moments: - "did we just discover..." - "YES. Now I see..."

The rule: Short = signal. Long = usually noise.

User's 3-word redirection carries more weight than assistant's 500-word explanation.

`Commands`

`$3`

`bash

`Check what's available (dry run)`


session-recall last 3 -d
Pull last session from current project

session-recall last 1 -f text
Pull last 2 sessions

session-recall last 2 -f text
Scan all projects (not just CWD)

session-recall last 5 --all -d

$3

`bash

`List all tool calls from last session`


session-recall tools
Get specific tool result by ID

session-recall tools --show 014opBVN

$3

`bash

`Create a checkpoint (marker that gets logged)`


session-recall --checkpoint "finished research"
session-recall --checkpoint "starting implementation"
List all checkpoints

session-recall checkpoints
Recall only messages AFTER a checkpoint

session-recall last 1 --after "finished research"


$3
Tag any session content for later recall. Critical items auto-surface.

`bash

`Preview what would be tagged (without tagging)`


session-recall --back 3 toolcall
Tag most recent tool call as critical

session-recall tag toolcall critical "found the root cause"
Tag tool call from 3 calls ago

session-recall tag toolcall --back 3 important "useful data here"
Tag other content types

session-recall tag agentcall critical "minion discovered pattern"
session-recall tag discourse important "user clarified requirement"
session-recall tag checkpoint critical "breakthrough moment"
List all tags

session-recall tags
Filter tags

session-recall tags critical      # Only critical level
session-recall tags toolcall      # Only tool calls

Types: toolcall, agentcall, discourse, checkpoint

Levels: -critical- Auto-injected in recall output (always shown) -important - Shown with --show-importantflag -bookmark - Lookup only, never injected

`$3`

`bash

`Compress with tool calls collapsed (action mode)`


session-recall rinse session.jsonl --gotime
Keep tool results truncated (see what was done)

session-recall rinse session.jsonl --logistics
Check token cost first

session-recall rinse session.jsonl --gotime -d

$3

`bash

`Show session stats`


session-recall state session.jsonl
Compare import costs

session-recall cost session.jsonl
Extract last N exchanges

session-recall hot session.jsonl --last 30
Parse to filtered jsonl

session-recall parse session.jsonl -f text


Use Cases
$3

`bash

`See what you worked on`


session-recall last 1 -d
Pull the context

session-recall last 1 -f text

$3

`bash

`Mark milestones as you go`


session-recall --checkpoint "research complete"
session-recall --checkpoint "design approved"
session-recall --checkpoint "implementation started"
Tomorrow, resume from any point

session-recall last 1 --after "design approved"

$3

`bash

`What did that command output?`


session-recall tools
session-recall tools --show 014opBVN

$3

`bash

`Combine multiple sessions`


session-recall last 3 -f text > context.txt

$3

`bash

`Run commands, discover something important`


Bash: grep "API_KEY" .env
Output: API_KEY=sk-live-abc123...
Realize that was important (2 tool calls ago)

session-recall --back 2 toolcall
Shows: UUID abc123 | grep "API_KEY" .env | API_KEY=sk-...
Tag it

session-recall tag toolcall --back 2 critical "found exposed API key"
Next session - critical items auto-surface in recall

session-recall last 2
[16:42:15] ⚠ CRITICAL [toolcall] grep "API_KEY" .env

           Reason: "found exposed API key"

           Result: API_KEY=sk-live-abc123...


Output Modes

`Token Economics`

Session-recall helps you fit more context in less tokens:

| Raw Session | After Rinse | Savings | |-------------|-------------|---------| | 750 messages | ~250 messages | 67% | | ~50k tokens | ~7k tokens | 86% |

The filtering isn't lossy - it's removing redundancy. The signal-to-noise ratio goes up dramatically.

`How It Works`

Claude Code stores conversations in ~/.claude/projects//` as JSONL files. Each line is a message with metadata.

License

MIT

Author

Hung Nguyen (@aiplumber)