/coding-agent-sessions

name: coding-agent-sessions
description: "Finds, reads, and reconstructs coding-agent sessions across Codex, Claude, OpenCode, OMO/Senpi, and other local agent logs. Use when asked to find or search past sessions, transcripts, or subagent runs, or to recover what an earlier session did."

Coding Agent Sessions

Find local coding-agent sessions across agent products before answering from memory. Prefer the bundled finder for broad cross-platform search, then read the selected session or raw file when you need exact evidence.

PHASE 0 - PLATFORM ROUTER

1. **IF the user names a platform, load its reference first.**

| Platform | Read | |---|---| | Codex / OpenAI Codex CLI | `references/codex.md` | | Claude Code / Claude Desktop histories | `references/claude.md` | | OMO / Senpi / pi coding-agent logs | `references/senpi.md` | | oh-my-pi (`omp`, `~/.omp`) and gajae-code (`gjc`, `~/.gjc`) logs | `references/senpi.md` | | OpenCode / oh-my-openagent (formerly oh-my-opencode) storage | `references/opencode.md` | | OpenClaw, Droid, Amp, Gemini, Kimi, Qwen, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Kiro, Goose, Hermes, Crush, Zed, Aside | `references/all-platforms.md` | | Unknown / "any session" / cross-agent search | `references/all-platforms.md` |

2. **Run the broad finder first unless the user gave an exact file path. For fuzzy recall, expand the query first.**

When the user remembers a task vaguely ("that OpenCode bug", "the dashboard PR", "when did we fix X"), derive 3-6 short query lanes before searching: product/tool aliases, repo/package names, exact error text, issue/PR/session IDs, English/Korean phrasing, and likely verbs such as `fix`, `review`, `plan`, `deploy`, or `merge`. Run the lanes together with repeated `--query` so `match_reasons` shows which wording found the hit.

python3 -B scripts/find-agent-sessions.py list --limit 20
python3 -B scripts/find-agent-sessions.py find "commit" --from 7d --platform senpi --platform opencode
python3 -B scripts/find-agent-sessions.py find "proxy" --platform openclaw --platform droid --platform amp
python3 -B scripts/find-agent-sessions.py find "refactor" --platform oh-my-pi --platform gajae-code
python3 -B scripts/find-agent-sessions.py find --query "deploy" --query "token usage" --workers 64
python3 -B scripts/find-agent-sessions.py find --query "opencode bug" --query "fix opencode" --query "OpenCode parent session" --include-subagents --workers 64
python3 -B scripts/find-agent-sessions.py read <session-id>

Use `python` instead of `python3` on systems where that is the available executable. Keep `-B`: the skill can live inside a signed app bundle, and Python bytecode caches written next to the scripts break its signature.

3. **Use explorer-style parallel lanes when one query batch is not enough.**

If scope is broad (multi-month, many repos/platforms, or a vague "what happened with X"), split independent searches by names/errors, repos/cwds, platforms/models, and time windows. Use available subagent/delegation tools for these lanes when they exist; otherwise run the finder calls in parallel. Merge candidates by `id`/`path`, then read the most likely sessions.

4. **Read details from search results before ad hoc digging.** Search results include `detail_hint`; run that `read <session-id> --platform <platform>` command to see the first user prompt, last user prompt, events, and child sessions together.

5. **Verify by opening raw transcripts for claims.** The finder normalizes formats; the raw `path` remains the source of truth.

Output Contract

The finder prints JSON for stdout and `jq`. Every result includes:

| Field | Meaning | |---|---| | `platform` | Registered platform key such as `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`, `opencode`, `openclaw`, `droid`, `amp`, `kodu`, `cursor-cli`, `aider`, `roo-code`, `kilo-code`, `kilo-cli`, `kiro`, or `aside` | | `id` | Session ID or stable file-derived ID | | `path` | Raw transcript/index file | | `cwd` | Working directory when recoverable | | `created_at`, `updated_at` | ISO-like timestamps when recoverable | | `provider`, `model` | Model metadata when recoverable | | `first_user_message` | First user prompt preview (for subagents: task description + delegated prompt) | | `last_user_message` | Last user prompt preview when recoverable | | `usage` | Token/cost clues when present in the platform log | | `parent_id` | Parent session/thread ID when this is a subagent or child session, else `null` | | `agent` | Subagent label (Claude `agentType`, Codex `nickname (role)`, OpenCode agent name) | | `subagent_count` | Number of child sessions spawned by this session | | `detail_hint` | Ready-to-run `read` command for detailed inspection | | `match_reasons` | Search-only array explaining which field/content matched each query |

Each `match_reasons` entry includes `query`, `platform`, `field`, and `snippet`, so you can tell which platform matched and what content caused the hit without opening every transcript. `field` is `user_message` when the query matched a user prompt that the `first_user_message`/`last_user_message` previews do not cover, such as a prompt in the middle of the session.

Filters

`list` and `search` share these filters:

| Filter | Meaning | |---|---| | `--platform` | Repeatable platform filter; pass one platform per flag | | `--root` | Extra root to scan, repeatable | | `--from`, `--to` | Date bounds: `YYYY-MM-DD`, `YYYY-MM`, `YYYY`, `today`, `yesterday`, `7d` | | `--cwd` | Working-directory substring | | `--model` | Model substring | | `--limit` | Maximum results | | `--workers` | Parallel worker count for platform scans, transcript parsing, OpenCode message joins, and multi-query matching | | `--include-subagents` | Include subagent/child sessions as standalone `list`/`search` results (hidden by default) |

`search` (alias `find`) also takes `--query`: a repeatable search query; multiple queries return