ccsession

name	ccsession
description	Recover, inspect, and hand off to local agent sessions with the ccsession CLI. Use when the user wants to find prior context, locate a historical Claude Code/OpenCode/Grok/Codex/Pi session, compare candidate sessions, preview a past conversation, or resume work that happened in another agent session.

ccsession

Overview

Use ccsession as a discovery and handoff tool. Inspecting a session is safe and read-only; resuming a session starts or replaces an interactive agent process and requires explicit user confirmation.

Do not duplicate ccsession's search, preview, or resume logic. Drive the CLI, summarize what it returns, and let the user choose before launching anything interactive.

Workflow

1. Gather the search intent: topic, issue number, repository, working directory, source backend, approximate date, or any phrase likely to appear in the transcript.

2. Search before previewing. Prefer content search when the user gives a topic or issue:

   ccsession list --json --grep "<query>" --limit 5
   

   If the intent is a repository, working directory, or time period rather than transcript text, start from the plain list and narrow the candidate set from the metadata:

   ccsession list --json --limit 10
   

   Put global source flags before the subcommand:

   ccsession --codex list --json --grep "<query>" --limit 5
   ccsession --source all list --json --grep "<query>" --limit 5
   

   Repeat the same source selector on preview and resume commands. Global source flags affect only that ccsession process and the fzf children it starts.

3. Present a small candidate set instead of dumping raw output. Include source, session id, locator, cwd or cwd basename, label/title, last activity, why it matched, and a match snippet when the CLI provides one. Current JSON output has no snippet field; use preview to inspect the match text.

4. Preview the selected candidate before recommending resume:

   ccsession preview --query "<query>" "<session-id>"
   ccsession --source all preview --query "<query>" "<session-id>"
   

   If ccsession list --json produced a locator field, preserve it and use:

   ccsession preview --locator "<locator>" --query "<query>" "<session-id>"
   ccsession --source all preview --locator "<locator>" --query "<query>" "<session-id>"
   

5. After previewing, explain whether the session appears relevant. Keep the distinction clear: previewing only reads past context; resuming launches the underlying agent CLI in the recorded working directory.

6. Show the non-launching resume target before asking for confirmation:

   ccsession resume-spec "<session-id>"
   ccsession --source all resume-spec --locator "<locator>" "<session-id>"
   

7. Ask for explicit confirmation before running ccsession resume or the interactive picker (ccsession with no subcommand). Do not infer confirmation from the user's interest in a candidate.

8. Run resume only after confirmation:

   ccsession resume "<session-id>"
   ccsession --source all resume "<session-id>"
   

   With a locator:

   ccsession resume --locator "<locator>" "<session-id>"
   ccsession --source all resume --locator "<locator>" "<session-id>"
   

CLI Shape

Prefer structured JSON for agent workflows:

ccsession list --json --grep "<query>" --limit 5
ccsession resume-spec "<session-id>"

Plain ccsession list output is TSV intended for fzf:

session id<TAB>locator<TAB>last epoch<TAB>relative time<TAB>cwd basename<TAB>label

Use --regex only when the user asks for regex semantics or a fixed-string query is insufficient. Use --exclude-dir <text> when noisy directories obscure the result.