longhand: Instructions file for Claude Code

Longhand MCP Tools — Efficient Usage Guide

Quick Decision Tree

When a user asks about past work:

1. "Do you remember when..." → Use recall FIRST. It handles fuzzy time, project matching, and retrieval in one call, returning a narrative built from conversation segments and session timelines — plus high-precision problem→fix episodes when the work left clean evidence.

2. "Find X in session Y" → Use search with session_id + context_events + a natural-language query. Returns matches WITH surrounding conversation. Do NOT paginate get_session_timeline manually.

3. "What happened in session X?" → Use get_session_timeline with summary_only: true first to scan, then search (with session_id + context_events) to drill into specifics. Use tail: N for how the session ended or the latest events.

4. "What file did we edit?" → Use get_file_history or replay_file.

5. "What did we commit?" → Use find_commits — pass a query for cross-session search, or a session_id with no query for one session's chronological git story.

6. "Where did we leave off on X?" → Use recall_project_status with the project name. Returns recent commits, unresolved issues, last session outcome, and conversation context in one call. Git-aware when git data exists, degrades gracefully without it.

Anti-Patterns (AVOID)

• Never paginate get_session_timeline in a loop looking for something. Use search with session_id + context_events instead.
• Never use search without session_id when you know which session to look in. Unscoped search returns noise from all sessions.
• Never skip recall for "do you remember" questions. It was built for exactly this use case.
• Don't call the retired names — search_in_context, get_latest_events, get_project_timeline, get_session_commits, get_episode, match_project left the tool listing at 1.0. They still answer forever (with a migration preamble) so older docs never hard-fail, but the surviving tools take the same parameters directly.