assist-sessions

assist-sessions

Search and recall context from past Claude Code sessions across machines, via the bundled sessions-axi CLI — a script in this skill's scripts/ directory (not on PATH). Invoke it by its path relative to this skill's base directory:

scripts/sessions-axi                     # home: recent activity + next steps
scripts/sessions-axi --help              # full command list
scripts/sessions-axi <command> --help    # usage for any command

Output is TOON (compact tables); pass --json for raw API JSON. The server defaults to http://localhost:2529; override with the CLAUDE_ASSIST_SERVER environment variable.

Choosing the right command: search vs transcript

This is the most important decision.

User intent	Command
Find sessions about a topic ("what did we discuss about auth?")	search --query ...
Review what happened in a time period ("what did I do today?")	transcript --after ... --before ... (no id)
Check when work happened ("how much time on X?")	activity --days N
Read a specific session	transcript <session-id>

Key rule: if the question names a time period (today, yesterday, this morning, last week, Monday, a date range), use the cross-session transcript (transcript --after --before with no id) — not search. Search finds sessions by topic; the transcript endpoint reconstructs what actually happened in a window.

Recognizing temporal queries

Use cross-session transcript --after --before for: "what did I work on today/yesterday/this week?", "what happened on Monday?", "give me a standup summary", "review my work from March 15–20", "what's been going on across my projects?".

Convert relative time to ISO 8601 (e.g. 2026-06-23T00:00:00Z); date-only 2026-06-23 also works (midnight UTC):

• "today" → --after <today 00:00> --before <now>
• "yesterday" → --after <yesterday 00:00> --before <yesterday 23:59:59>
• "this week" → --after <Monday 00:00> --before <now>

Defaults that matter

• Hide subagent sessions: pass --min-user-messages 2 on search and rely on the transcript default (also 2). Only omit when the user asks about subagent/automated runs.
• Scope to the current project: unless the user asks across all projects, pass --project <repo> using a minimally-unique substring (e.g. --project claude-assist, not the full path). --project matches any substring of the project path.
• Substring filters: --tools, --files-read, and --files-written all match substrings (e.g. --tools mcp__plugin_slack matches every Slack MCP tool).

Searching inside transcripts

grep finds tool calls (by name/target) or message text within transcripts; transcript --around then lets you explore outward from a match. Two modes:

• Per-session: grep <session-id> --tool Bash --match "tofu apply" returns each hit as a window of surrounding messages (the matched line marked >), with head/tail anchors and how many messages remain before/after.
• Cross-session: grep --tool Edit --match routes.ts [--project P] [--days N] (no id) searches the tool-call index across all sessions and returns a compact list of matches, each with a session + anchor you can open. (Cross-session matches on tool name/target only; for cross-session text, use search to find sessions, then grep <id> --in text.)

The exploration loop

Every match carries an anchor uuid. Walk outward from it with the follow-up:

transcript <id> --around <uuid> --before 1 --after 1     # the immediate ±1 (issue's example)
transcript <id> --around <head> --before 30 --after 0    # 30 more messages back
transcript <id> --around <tail> --before 0 --after 100   # a big jump forward

In --around mode, --before/--after are message counts (not dates). Each response prints the window plus ↕ K before · J after and extend back/forward: commands using the window's edge anchors — so you keep ratcheting outward until more_before/more_after hit 0 (the session boundary) or you've found what you need. Oversized ranges are token-capped and return a continuation anchor rather than dumping the whole session.

Commands

Recall

• scripts/sessions-axi search [--query TEXT] [--project PATH] [--days N | --since DATE --until DATE | --forever] [--tools a,b] [--files-read frag] [--files-written frag] [--machine ID] [--min-user-messages N] [--include-empty] [--limit N] [--offset N] — find sessions by topic/tool/file (tools & files are substring matches); defaults to the last 30 days of activity (window & ordering use last activity, not start), hides subagent sessions at --min-user-messages 2
• scripts/sessions-axi transcript <session-id> [--after DATE] [--before DATE] [--include-tools] — compact, token-efficient transcript of one session (optionally trimmed to a time window)
• scripts/sessions-axi transcript --after DATE --before DATE [--group project|time] [--project PATH] [--min-user-messages N] [--include-tools] — cross-session transcript for a time range — the primary tool for "what did I work on ?"
• scripts/sessions-axi grep <session-id> --tool Bash --match "text" [--in target|text|tool] [--context N] — find tool calls / text within a transcript — windowed matches + anchors
• scripts/sessions-axi grep --tool Edit --match routes.ts [--project P] [--days N] — no id → cross-session tool-call discovery over the index
• scripts/sessions-axi transcript <session-id> --around <uuid> [--before N] [--after M] — explore a variable range of messages around an anchor (the grep follow-up)
• scripts/sessions-axi details <session-id> [--raw] — session metadata; --raw adds the parsed raw messages
• scripts/sessions-axi activity [--days N] — when sessions had turns of any kind, human or automated — a timeline feed, not a time measure (default 7 days)
• scripts/sessions-axi engagement --from DATE --to DATE [--tz IANA] [--sessions] — human hands-on time per local day and project — automated turns excluded, parallel sessions counted once; the tool for "how much time on X?"

Overview

• scripts/sessions-axi stats [--days N] [--machine ID] — usage statistics: top tools, models, tokens, per-machine counts
• scripts/sessions-axi machines — list registered machines with sync status

Manage

• scripts/sessions-axi outlines [<session-id>...] — generate AI outlines for sessions missing/stale ones (needs the server's model invoker)
• scripts/sessions-axi outlines progress — check background outline-generation progress
• scripts/sessions-axi sync [--force] — trigger an immediate local session sync (--force re-parses all)
• scripts/sessions-axi share <session-id> — mint a shareable auth code for a session transcript

Common workflows

• "What did I work on today?" → scripts/sessions-axi transcript --after <today 00:00> --before <now> then summarize per project.
• "Standup / what did I do yesterday?" → scripts/sessions-axi transcript --after <yesterday 00:00> --before <today 00:00>.
• "What did we discuss about X?" → scripts/sessions-axi search --query "X" --project <repo> --min-user-messages 2, then scripts/sessions-axi transcript <top-result-id>.
• "Where did we leave off?" → scripts/sessions-axi search --days 7 --project <repo> --min-user-messages 2 --limit 5, then read the most recent transcript.

Notes

• Sessions are stored in PostgreSQL with weighted full-text search; the host syncs ~/.claude/ automatically, satellite machines push via the package CLI.
• AI outlines/titles are generated asynchronously when ANTHROPIC_API_KEY is set; trigger manually with scripts/sessions-axi outlines.
• Transcript output is text ([U] user, [A] assistant, [T] tool); everything else is TOON, with --json for raw JSON and details <id> --raw for full raw messages.