name

history-surfer

description

Use when the user wants to recall, search, or reference their own PAST Claude Code prompts (across this or other projects) — e.g. "what did I ask about X earlier", "find my previous prompt about Y", "show my prompt history", "have I mentioned Z before", "what was that prompt where I pasted the screenshot". Queries the local prompt log via the `surfer` CLI. Do NOT use for searching code or files.

Surfing prompt history

The user keeps a local, searchable log of every prompt they've sent to Claude Code (captured by claude-history-surfer). Answer questions about their past prompts by running the surfer CLI and summarizing real results — never invent prompts.

How to query

Run these with the Bash tool and read the JSON:

Goal	Command
Search current project (default)	`surfer search "<query>" --json`
Recent prompts, current project (default)	`surfer list --limit 20 --json`
Search across all projects (only if asked)	`surfer search "<query>" --all --json`
Recent across all projects (only if asked)	`surfer list --all --limit 20 --json`
ALL prompts, full depth (no recency cap)	`surfer list --limit 0 --json` (add `--all` for every project)
How much history exists (counts + date span)	`surfer stats` (add `--all`)
Full detail + attachments	`surfer show <id> --json`
Only favorites / a tag	add `--favorites` or `--tag <tag>`
Regex search	add `--regex`

Each result object has: id (session:seq), ts, cwd, prompt, tags, favorite, and attachments (each with kind, stored path, bytes).

Guidance

Default to the CURRENT project. surfer scopes to the project you're in (the session's working directory) unless you pass --all. Only add --all when the user explicitly asks about other projects, all/any projects, or "across projects." Never add --all by default.
The full history is stored — go as deep as needed. surfer list shows only the most recent --limit (default 30); it is NOT the whole history. The store holds every prompt back to whenever the user started using Claude Code (often thousands). So:
- To find something, surfer search (it scans the entire history, no cap).
- To see everything, surfer list --limit 0 (oldest→newest, no cap) or surfer tui.
- When the user asks to see/browse "my history," first run surfer stats and tell them the total count and date span (e.g. "894 prompts, 2026-02-23 → today"). Never imply only a handful exist just because list showed a recent slice.
Prefer --json, then summarize concisely (id, date, project, a snippet).
Use surfer show <id> to pull the full text or attachment paths for one prompt.
If surfer is not found, tell the user to install claude-history-surfer (curl -fsSL https://raw.githubusercontent.com/ContextLab/claude-history-surfer/main/install.sh | bash).
The user can also browse interactively with surfer tui.

Surfing prompt history

How to query

Run these with the Bash tool and read the JSON:

Goal

Command

Search current project (default)

surfer search "<query>" --json

Recent prompts, current project (default)

surfer list --limit 20 --json

Search across all projects (only if asked)

surfer search "<query>" --all --json

Recent across all projects (only if asked)

surfer list --all --limit 20 --json

ALL prompts, full depth (no recency cap)

surfer list --limit 0 --json (add --all for every project)

How much history exists (counts + date span)

surfer stats (add --all)

Full detail + attachments

surfer show <id> --json

Only favorites / a tag

add --favorites or --tag <tag>

Regex search

add --regex

Each result object has: id (session:seq), ts, cwd, prompt, tags, favorite, and attachments (each with kind, stored path, bytes).

Guidance

Default to the CURRENT project. surfer scopes to the project you're in (the session's working directory) unless you pass --all. Only add --all when the user explicitly asks about other projects, all/any projects, or "across projects." Never add --all by default.

The full history is stored — go as deep as needed. surfer list shows only the most recent --limit (default 30); it is NOT the whole history. The store holds every prompt back to whenever the user started using Claude Code (often thousands). So:

To find something, surfer search (it scans the entire history, no cap).
To see everything, surfer list --limit 0 (oldest→newest, no cap) or surfer tui.
When the user asks to see/browse "my history," first run surfer stats and tell them the total count and date span (e.g. "894 prompts, 2026-02-23 → today"). Never imply only a handful exist just because list showed a recent slice.

Prefer --json, then summarize concisely (id, date, project, a snippet).

Use surfer show <id> to pull the full text or attachment paths for one prompt.

If surfer is not found, tell the user to install claude-history-surfer (curl -fsSL https://raw.githubusercontent.com/ContextLab/claude-history-surfer/main/install.sh | bash).

The user can also browse interactively with surfer tui.