code-yeongyu/oh-my-openagent / packages/shared-skills/skills/coding-agent-sessions
coding-agent-sessions
VerifiedFinds, 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.
AGENTS.md
View on GitHub# coding-agent-sessions — Cross-Platform Session Finder (Python)
**Generated:** 2026-08-24 (f3642fcda)
## OVERVIEW
The only shared skill besides `ultimate-browsing` carrying a real sub-project: a Python package + CLI that finds, lists, searches, and reads local coding-agent session transcripts across ~25 platforms (Codex, Claude, OpenCode, OMO/Senpi/pi, and a long tail), normalizing them into one `Session` model. Earned this file: 33 files, 23 Python modules, own test suite, own `pyrightconfig.json`, own `.npmignore` (ships in the npm package minus tests/caches).
## STRUCTURE
```
coding-agent-sessions/
├── SKILL.md # router: platform table → references/<platform>.md
├── references/ # codex, claude, opencode, senpi, all-platforms (store layouts per platform)
├── agents/openai.yaml # Codex agent role declaration
├── scripts/
│ ├── find-agent-sessions.py # thin shebang entry (PEP 723, >=3.11); runpy → agent_sessions.cli
│ ├── agent_sessions/ # the package (12 modules)
│ └── tests/ # 6 pytest modules
└── pyrightconfig.json # extraPaths scripts/, excludes scripts/tests
```
## PUBLIC API (`scripts/agent_sessions/`)
| Module | Key exports |
|--------|-------------|
| `scanners.py` | `scan`, `DEFAULT_PLATFORMS`, `PLATFORM_SCANNERS`, per-platform `scan_*` (codex, claude, opencode, senpi, oh_my_pi, gajae_code, …) |
| `types.py` | `Session`, `Options`, `Json`, `JsonMap` — imported by nearly every module and test |
| `transcript.py` | parallel file reads, normalization, timestamps, session ids; `recent`, `MAX_PLATFORM_FILES` |
| `cli.py` | command parsing, filtering, payload construction, JSON emission (283 LOC — behavioral hotspot) |
| platform adapters | `file_scanners.py` (file-backed providers), `opencode.py` (CLI/SQLite/storage fallbacks), `sqlite_scanners.py`, `sqlite_optional_scanners.py`, `pi_family.py`, `aside_scanner.py`, `kiro_scanner.py` |
## CLI CONTRACT
`python3 -B scripts/find-agent-sessions.py <command>`; aliases `find`=`search`, `read`=`get`. Commands: `list`, `find`/`search` (repeated `--query` lanes, `--from 7d`, repeated `--platform`, `--workers`, `--cwd/--model`, `--include-subagents`, `--limit`), `get`/`read <session-id>`. Output is JSON with `match_reasons` and reconstructed first/last user prompts — that JSON shape is the stable contract.
## CONVENTIONS
- Stdlib-only Python (`>=3.11`), `from __future__ import annotations`, pathlib everywhere; no third-party deps at runtime.
- Probe-first, bounded discovery: platform-specific roots checked before broad globbing; optional platforms excluded from default search when they cannot reconstruct user prompts.
- Main sessions hide subagent children by default but report child counts; `--include-subagents` flips it. Parent/child linkage preserved and records deduplicated.
- Tests are pytest with `tmp_path` + `MonkeyPatch` isolation; in-file `# pyright: ignore[reportMissingImports]`-style relaxations for import diagnostics only.
- `.npmignore` strips `scripts/tests/`, `pyrightconfig.json`, and caches from the shipped skill.
- The shipped skill must never write next to itself (#11373): `find-agent-sessions.py` sets `sys.dont_write_bytecode` before importing `agent_sessions`, and every documented command passes `-B`. `packages/shared-skills/bundled-skill-scripts-write-nothing.test.ts` runs every bundled entry and fails on any new file.
## ANTI-PATTERNS
- NEVER answer from normalized previews alone — pull the raw transcript (`read`/`get`) for exact evidence.
- Usage-only stores are NOT transcript sources.
- A Claude subagent's embedded `sessionId` is NOT its identity — use its `agentId` + parent-directory linkage.
- Don't add a platform by globbing blindly; register it in `PLATFORM_SCANNERS`/`DEFAULT_PLATFORMS` with a bounded root probe.
## COMMANDS
```bash
# from packages/shared-skills/skills/coding-agent-sessions/
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 read <session-id>
pytest scripts/tests
```
- Parent (source checkout only, not shipped with the installed skill): `packages/shared-skills/AGENTS.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |