---
name: check-agent-logs
description: Search past Claude Code, Codex, Cursor CLI, Droid, OpenCode, and Pi session logs to recover context from earlier work across the current project and sibling checkouts. Use when a bug, topic, or decision was handled in a previous session but its agent or checkout is unknown; when the user says "we fixed/discussed this before", "find the session where", "recover prior context", "check agent logs", "check Claude projects", "search past sessions/transcripts", or "which checkout was that in". Do not use for aggregate failure-pattern analysis; use review-logs for that.
---

# Check Agent Logs

Recover prior context by searching stored agent transcripts, reading the relevant
session, and continuing from its diagnosis or decision.

## Instructions

### 1. Choose a query and agents

Use a distinctive regex such as an error string, symbol, ticket ID, or unusual
phrase. With no agent selector, the script searches all agents. Selectors compose:

```bash
python3 scripts/search_agent_logs.py "QUERY" [--claude] [--codex] [--cursor] [--droid] [--opencode] [--pi] [--current] [--all]
```

- `--current` selects the harness running the skill.
- `--all` and no selector both select all six agents.
- `--scope siblings` is the default project scope. `--scope current` searches
  only the current checkout; `--scope all` searches every recorded project.
- `--app NAME` searches session cwd values containing `NAME` and overrides scope.
- `--days N` limits the search to recently updated sessions.
- **`--kind message` is the highest-value filter.** Every entry is classified as
  `message` (what was said), `tool` (calls and their output), or `meta`
  (reasoning and summaries). Tool traffic dominates raw match counts — a real
  session here matched 5117 times, of which 4668 were tool output — so search
  conversation first and widen to `--kind tool` only when hunting a command or
  a stack trace.
- Results are ranked by weighted score (`message` 3, `meta` 2, `tool` 1, title 5),
  highest first. `--sort recent` restores newest-first ordering.
- `--format json` emits the same results as a machine-readable document; prefer it
  when a script or another agent consumes the output rather than a human.

Run `--help` for case, snippet, cwd, and result-limit controls.

### 2. Read the candidate

Results are newest-first and include a stable ref, title, cwd, branch when known,
timestamps, source, and snippets. Read the most likely session:

```bash
python3 scripts/search_agent_logs.py --read AGENT:SESSION_ID [--mode lite|full|log]
```

`--mode lite` is the default and prints conversation only; `full` adds reasoning
and summaries, `log` adds all tool traffic. Sessions reach hundreds of thousands
of characters, so reads are capped at `--max-chars` (200000 by default) and report
what they withheld:

```
… truncated: 50000 of 374819 chars from offset 0. Continue with --offset 50000,
  or --mode log for tool traffic.
```

Continue with the reported `--offset` rather than re-reading, and stay in `lite`
unless the answer is genuinely in the tool output — `log` was 4.8x larger than
`lite` on the same session.

**For one specific answer, distill instead of reading.** When the question is
narrow (what was the fix, what was decided, why something was rejected) and
`distill` is on PATH, pipe the whole transcript through it. A cheap model reads
the session and only its answer enters your context; a 113k-char session came
back as six lines in about two seconds.

```bash
python3 scripts/search_agent_logs.py --read AGENT:SESSION_ID --max-chars 2500000 \
  | tee "${TMPDIR:-/tmp}/session-ID.txt" \
  | distill "What did this session conclude about TOPIC? Quote the decisive sentences verbatim."
```

The answer can paraphrase while looking like a quote. Before acting on a
recovered command, path, or fix, grep the saved file for the quoted sentence and
read around it; delete the saved copy once you have what you need. `NO_RELEVANT_CONTENT` means this session is not the one: move to
the next candidate rather than re-asking in other words. Read the transcript
directly when you need the whole arc of the work rather than one answer.
`distill` sends the transcript to OpenRouter, so skip it for sessions likely to
hold credentials or data the user would not send to a third party.

**Cursor transcripts are thinner than the others.** The Cursor CLI's transcript
holds prompts, replies and tool calls but no tool output, so `--mode log` and
`--kind tool` show what was run, never what it returned. Its cwd and title come
from the CLI's chat metadata; subagent transcripts take their parent's cwd. Chats
from the Cursor IDE are not searched.

Read more than one when attribution is ambiguous. Trust the printed `cwd` over
encoded storage paths. Transcripts can contain secrets or PII; use them as
context without repeating sensitive values to the user or writing them elsewhere.

### 3. Apply the recovered context

Continue the task using the prior diagnosis, fix, or decision. Cite the session's
agent, title, and date when summarizing what was recovered.

### When sessions ran

`--timeline` lists sessions active in a window instead of searching, oldest first,
in local time. It takes the same agent and scope selectors and no query:

```bash
python3 scripts/search_agent_logs.py --timeline --since 2026-11-02 [--until 2026-11-03] [--idle-minutes 30] [--format json]
```

Each session is split into active spans wherever its log goes quiet for longer than
`--idle-minutes`; a span's prompt count covers only human prompts, so a span with
none was driven by another session, a scheduled wake-up or a compaction. A bare
`--until` date includes that whole day, and `--days N` can stand in for `--since`.
The footer merges overlapping sessions into one active total per day. Claude
subagent transcripts are skipped, since their parent session already covers them.
Cursor records only each prompt's minute and the chat's last update, so its spans
miss the time spent between prompts and its active time is a lower bound.

### 4. Widen only as needed

If nothing matches, try an alternate query, remove `--days`, use `--app NAME`,
then use `--scope all`. Do not make an aggregate claim when the script reports an
incomplete search because an agent source was unavailable.

## Examples

### Find a regression without knowing the agent

User: "The KeyboardShortcut crash is back; didn't we fix it before?"

1. Run `python3 scripts/search_agent_logs.py "KeyboardShortcut" --app juggler`.
2. Read the best hit with `--read codex:019...`.
3. Apply the recovered fix and cite that session.

### Search only the invoking harness

User: "Find the session where this agent discussed the schema migration."

Run `python3 scripts/search_agent_logs.py "schema migration" --current --scope all`.

## Troubleshooting

### `--current` cannot identify the harness

Run through the repository's normal agent wrapper, which sets `AGENT_HARNESS`, or
replace `--current` with an explicit agent selector.

### A provider is unavailable

Use another selector only if the user intends a narrower search. An all-agent
search reports missing stores as incomplete; do not treat an empty result as proof
that the context never existed.

### Results are noisy

Use a more distinctive query, `--days N`, or `--app NAME`. The current session may
match because it contains the user's search phrase; prefer an older result whose
title and snippets describe the actual prior work.
