Skip to main content
A handoff brief surfaces the most important context from a session, but sometimes you need to dig deeper. Maybe you remember a decision was made about rate limiting two weeks ago but can’t recall which project it was in. Or you want to find the exact error message that appeared during a debugging session. Handshake’s full-text search lets you search through your entire session history — within a single session or across all of them.

​
Search within a session

When you know which session contains the information you need, use search_session to find specific messages in it. Parameters:
ParameterRequiredDescription
title✅ YesTitle (or part of the title) of the session to search
query✅ YesWords or phrases to search for
limitNoMaximum number of results to return (default 5)
Ask your agent in natural language: 
in my auth refactor session, search for "JWT"
Results show the message role and a content snippet for each match: 
Search: "JWT" in "auth refactor" — 3 result(s)

[user]
Should we use JWT or server-side sessions for the auth tokens?

[assistant]
Given the stateless API requirement, JWT is the better fit here. We'll sign
tokens with RS256 and keep them short-lived (15 minutes) with a refresh token [...]

[assistant]
JWT middleware is now wired into all protected routes. The token is verified
against the public key loaded at startup [...]

​
Search across all sessions

When you’re not sure which session covered a topic, use search_all_sessions to search everywhere at once. Parameters:
ParameterRequiredDescription
query✅ YesWords or phrases to search for
limitNoMaximum number of results to return (default 10)
agentNoFilter results to a specific agent: claude-code, opencode, hermes, or codex
Ask your agent: 
search all sessions for "rate limiting"
Results include the session title, agent, and message role alongside the content snippet: 
Search: "rate limiting" across all sessions — 4 result(s)

[payment webhook integration / hermes / assistant]
Added token-bucket rate limiting on the webhook endpoint — 100 requests per
minute per source IP. Anything above that gets a 429 with a Retry-After header [...]

[council budget spending tracker / opencode / user]
We need rate limiting on the export endpoint before going live [...]
To narrow results to a specific agent: 
search all my claude-code sessions for "database migration"

​
What you can search for

Full-text search works across all message content in your sessions. Useful things to search for include:

Error messages

Paste an error you’re seeing to find sessions where it came up and how it was resolved.

File names

Search for a specific file to find every session where that file was discussed or modified.

Decisions

Look up the reasoning behind a past decision — why JWT instead of sessions, why Postgres instead of SQLite.

Library and dependency names

Find every session where a particular library was used, configured, or debugged.

Feature names

Search for a feature name to pull up all related context across projects.

Topics and concepts

Search for any technical topic that was discussed — “caching strategy”, “auth flow”, “background jobs”.
Use search when you know a topic was discussed but can’t remember which session it was in. Start with search_all_sessions to find the right session, then use search_session to dig into the details once you’ve identified it.