# Agent History

> Historical local Codex, Claude Code, Pi, or Prime Agent session evidence: retrieve prior prompts, goals, corrections, tool calls, child-agent briefs, and timelines. Supports natural-language history requests with bundled JSONL/SQLite helpers. Not for live agent status, streaming output, or session control; use the runtime's live interface for those. Defaults to the current project/runtime and last 24 hours.

- Skill: `aelaguiz/agent-history` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/agent-history`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/agent-history/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/agent-history

---


# Agent History

Use this skill when the user wants to find, explain, or summarize past local
agent-session evidence. Live status, streaming, and session control belong to
the runtime's live interface. The user may speak casually: "what prompt did I run
here", "what goal commands did I run today", "where did I have to correct the
agent", or "find where I was struggling with the agent last night".

This skill is a retrieval and evidence skill. It ships helper scripts so agents
do not hand-roll fragile JSONL and SQLite parsing, but the scripts are not a
query language for the user. Interpret the user's words, run the helper to get
candidates, inspect the evidence, and answer like an investigator.

If a neighboring request actually needs another model agent, apply
`../_shared/agent-orchestration-policy.md` before routing it. This history
skill remains read-only and does not dispatch that agent itself.

## When To Use

- The user asks about prior Codex, Claude Code, Pi, or Prime Agent prompts,
  turns, commands, goals, tool calls, corrections, confusion, or session
  timelines.
- The user asks what happened in the current project during recent agent work.
- The user asks what a Prime child agent was told to do or what it reported
  back.
- The user wants to search local session history by natural-language clues.
- Another skill needs grounded history evidence before deciding what happened.

## When Not To Use

- The user wants Git commit history rewritten. Use `$commit-history-authoring`.
- The user wants a fresh second opinion rather than historical evidence.
- The user wants another agent to do work. Use the active host's native child
  for ordinary same-host work; use `$agent-delegate` only when a deliberate
  external worker/session provides the needed benefit.
- The user wants to search current repo files rather than past agent-session
  evidence. Use normal repo search.
- The user asks for history from a runtime whose local store is absent and no
  exported history is provided.

## Non-Negotiables

- Use the current agent runtime by default. In Codex, search Codex history. In
  Claude Code, search Claude history. In Prime Agent or Pi, search that
  runtime's history. Search another runtime only when the user asks for it or
  clearly implies it. Map "prime", "prime agent", and "prime-agent" to
  `--runtime prime`. If the current runtime is genuinely ambiguous, pick the
  store with recent activity for this project and say which one you assumed.
- Pi and Prime Agent have no global prompt store and no goal store. Prompts and
  `/goal` text come from transcripts only, so say that plainly instead of
  reporting a clean absence.
- Never read `auth.json` in any runtime home, and never run daemon lifecycle
  commands. This skill only reads history.
- If the user does not name a project, default to the current working
  directory. If they do not name a time range, default to the last 24 hours.
  If they say "today", use the local calendar day.
- Interpret natural language with judgment. Do not force flags, templates, or
  a canned command vocabulary onto the user.
- Run `scripts/agent_history.py` before inventing ad hoc parsers for common
  Codex or Claude history stores.
- Treat helper output as evidence, not the final answer. Drill down when the
  summary is ambiguous or when the user's question needs surrounding context.
- Preserve privacy. Quote only short, relevant snippets unless the user asks
  for raw history.
- Label evidence quality. Use `exact` for directly stored text, `inferred` for
  durable effects, `best_effort` for logs or partial traces, and
  `not_found_after_search` when the searched stores did not contain a match.

## First Move

1. Read `references/retrieval-playbook.md`.
2. Read `references/helper-script.md`.
3. Read `references/storage-map.md` only as needed for the runtime and evidence
   type in the user's request.
4. Convert the user's ask into a search intent: runtime, project scope, time
   window, evidence target, and answer shape.
5. Run the bundled helper with the current runtime and the smallest useful
   scope. Use follow-up helper calls for drill-down instead of dumping raw logs.

## Workflow

1. **Resolve defaults.** Use the current runtime, current cwd, and last 24h
   unless the user supplied a different runtime, project, or time range.
2. **Choose evidence.** Start with metadata and indexes, then transcripts, then
   logs only when logs are the right or only source.
3. **Run helpers.** Use `agent_history.py sessions`, `prompts`, `commands`,
   `goals`, or `search` to get bounded candidates and artifact handles.
4. **Inspect context.** Use `agent_history.py show` or targeted file reads for
   the few hits that matter. Do not summarize a whole transcript from a search
   result row alone.
5. **Synthesize.** Answer the user's real question, not the helper command.
   Include assumptions, evidence paths, confidence, and any storage limitation.
6. **Stop cleanly.** Stop when the answer is supported enough for the user's
   question. If the store cannot answer exactly, say what was searched and why
   the remaining uncertainty exists.

## Output Expectations

- Lead with the direct answer.
- State assumed runtime, project, and time window when they were not explicit.
- For each meaningful hit, include runtime, timestamp, session/thread id, cwd
  or project, source path, short evidence, and confidence.
- Keep snippets short. Prefer path/session handles over raw transcript dumps.
- If no match is found, say which stores were searched and whether the absence
  is strong evidence or only best-effort.

## Reference Map

- `references/retrieval-playbook.md` - natural-language interpretation,
  evidence selection, examples, and answer shape
- `references/storage-map.md` - Codex and Claude local stores, formats, and
  command/goal persistence limits
- `references/helper-script.md` - helper commands, output contract, artifact
  layout, and drill-down behavior
- `scripts/agent_history.py` - self-contained read-only history parser