AI R

ai-r

English | Русский | 中文 | 日本語 | Español

An agent reported "done." There's nothing to check it against.

ai-r reads the session history of any of the five coding agents and lets a fresh agent cold-check what git can't answer:

• did it lie, did it break anything — did it keep its word, did it run anything dangerous (and roll it back if it did), what it actually changed, what it cost;
• why it went that way — under which plan, with what intent, and whose hand was behind the edit.

Across our own corpus — 1600+ sessions of five agents in 20+ projects — that's

how we found 312 risky commands (rm -rf, curl|sh, git push --force): the

agent caught and rolled back two itself; the other 310 ran silently — git

won't show them.

git shows what made it into the code; ai-r shows whether you can trust how the agent got there. Read-only: no LLM calls, no network.

Quick example — an agent asks about history

The primary mode is MCP: an agent (Claude, Codex, …) calls ai-r directly and asks about history in plain language. For example — pull the plan the previous agent settled on, drafts discarded:

Show me the plan from the last session — final only, no intermediate revisions.

→ plan(session=…, kind="final") → get_body(id, shallow=true)

plan: "Migrate auth to JWT: 1) extract the check…" dropped_drafts: 2 ← two drafts the agent threw away along the way session: a3f… (claude)

Fast edit attribution — one terminal command, across every agent at once:

ai-r find-file-edits auth.py --since 2026-06-01

2026-06-03  codex   auth.py  "add a refresh token"                 edit

2026-06-07 claude auth.py "extract the check into middleware" edit

What hurts

• "Done, I did X per plan Y" — with nothing to check it against: the agent keeps the plan in one shape, the edits in another.
• You switched agents mid-task and lost the thread. There's nowhere to ask "what did the *other* agent already try?"
• An edit shows up in a file — and it's unclear which agent made it, and on what request.

One cause: every agent writes its history its own way — Claude and Codex in JSONL, OpenCode in SQLite, Antigravity in "brain" directories, Pi in per-project JSONL. Five formats, five layouts — together they don't reconcile.

The promise

ai-r folds all five into one read-only interface. Point any agent — or a script, or yourself — at any session, no matter which tool recorded it. One query shape per agent; format differences are normalized inside the parsers.

Even with a single agent it works: you audit your own Claude history (or Codex…). The five formats are so your history doesn't break when you switch tools — not a requirement to have all five.

As a source for RAG

In an "LLM + external data source" setup (RAG), ai-r is the source — more precisely, a retrieval layer over agent sessions. For a query it returns not a slice of log but parsed entities: the plan, the intent, the authorship of an edit — with a reference to the body the agent can pull if it needs it.

It doesn't replace your RAG over code and docs; it adds a source the others can't reach. The usual sources you retrieve from: documentation, commit history, Stack Overflow, internal wikis, code bases, bug reports. Agent sessions aren't on that list — even though only there is it recorded why an edit happened at all.

Retrieval is BM25 (ranked keyword search), with optional semantic re-ranking. No vector database, no second LLM: all local, results reproducible. BM25 here isn't a shortcut — GitHub lists it alongside vector retrievers: "Common retrievers include sparse methods like BM25 and dense vector retrievers using neural networks."

Key features

Each item is a trust question from the first screen and the verb that answers it:

• Did it keep its word — plan vs. reality. Pulls the final plan (separate from the discarded dropped_drafts) and checks it against what actually made it into the edits — catching "did X per plan Y" where Y is no longer that plan. (plan, session_diff)
• Did it run anything dangerous — and roll it back. Flags risky commands (rm -rf, curl|sh, git push --force) and, from the turns that follow, sees whether the agent caught it and rolled back — or it passed silently. (incidents, query tool_kind=bash)
• What it actually changed, and by whose hand. Any edit or call → the agent that made it, plus the request that triggered it; including edits made through the shell (> file under codex) that a plain diff misses. (find-file-edits, find-tool-calls)
• What it cost. Tokens and cost per session — exact where the format recorded the usage, an honest estimate where it didn't, never invented. (session_stats with_tokens, aggregate group_by=model)
• Why it went that way. The intent behind an edit (the request *before* it), under which plan, on which model — "why", not just "what". (query with_intent)
• Small answer, body on demand. A record carries a reference to the content (hash + length); the full text comes as a separate request. A reader, not a guard: read-only, it runs nothing and writes nothing to an agent's history.

How ai-r knows

Deterministically, with no second LLM guessing — and honest about the edges:

• dangerous command — a pattern over the call string (rm -rf, curl|sh, git push --force, …). Anything obfuscated (exec(input())) the pattern won't catch — that's a declared boundary, not a silent miss.
• rollback — marked "confirmed" ONLY when a regret/apology marker from the agent sits nearby (within the window of following turns; the marker itself is a bilingual ru/en pattern, not an LLM sentiment call). No marker → it stays an unconfirmed candidate: ai-r won't infer a silent rollback, it honestly says "not confirmed".
• lied about the plan — ai-r doesn't decide for you. It lays the plan entity next to the session's reconstructed edits (session_diff) — the mismatch is visible to you or a reviewing agent. That's evidence assembly, not a semantic verdict.

Zero LLM calls, read-only — the numbers are reproducible and "confirmed" is never guessed.

What you use it for

• Audit sessions with a fresh pair of eyes. A new agent with an empty context coldly checks past sessions on three axes: were promises and requirements met; are the decisions sound and well-judged; how deeply was the question explored — what the agent missed. This catches agents that finished the task but misled on the planning — something a live chat hides, and that steers you into wrong decisions.
• Continue past a spent context — without losing detail. /compact erases the specifics. Instead, open a fresh session: it reads the previous session's logs and continues from its conclusions, without re-burning context on what's already been worked out. The original session stays intact — for audit and search. The new session can run in any agent: the history reconciles regardless of the tool.
• Feeds your memory system. Keeping memory and summaries à la Karpathy, or your own method? ai-r gives you, for AI chats, what you already do with message history — parsed entities to build a lasting memory of the details that matter.
• Recall what you did and why. Why was this file edited? Why was this rule added? Find the session where the file changed and read the request *before* the edit.

How it differs from session-search tools

A handful of cross-agent tools now read more than one agent's history (jazzyalex/agent-sessions, Dicklesworthstone/coding_agent_session_search, hacktivist123/agent-session-resume). Almost all are about search and timeline: find a *session*, scroll the history.

ai-r goes deeper: it extracts the plan, intent, and authorship as ready-made entities you build memory on. Search finds text — ai-r answers why. Technically a search tool could also dig a plan out of a session's text, but it doesn't hand it back parsed into a single, normalized shape — with ai-r that's the primary surface.

*Competitor columns reflect their public docs as of 2026-07; where a capability is unclear we under-state rather than over-claim.*

We deliberately don't compete on agent breadth, speed, or TUI richness. ai-r's wedge is extracting the "why" and structured entities for machine consumption.

Proven in practice

ai-r already reads its own development history — across all five agents. Real tools run on it (they live separately, on top of its read-only API):

• auditor — a fresh agent coldly checks what the previous one actually did and decided. This caught agents that quietly fibbed about the plan.
• summarizer (export rounds) — renders a session into a ready handoff doc.
• ai-local-reader — a read-only skill: audits past sessions from disk across all agents.

These tools are workflow-side, outside this repo. ai-r itself only reads and returns data.

Supported agents

Not your agent? Adding a sixth is one parser module; the read-only pattern ports to any tool in minutes. See CONTRIBUTING.md.

Surfaces

ai-r gives the same reading power three ways:

• MCP server (ai-r-mcp) — 15 tools over JSON-RPC, so any MCP agent calls it directly (recommended). Default is stdio; optionally a shared http server (one warm process for all agents instead of a per-agent stdio swarm), see the http extra under Quick start. Registration — see docs/mcp-registration.md.
• CLI (ai-r) — subcommands for scripts and manual use (list / read / search / find-file-edits / find-tool-calls / file-frequency / detect-agent / export rounds). Search operators — docs/search-operators.md.
• Python SDK (from ai_r.parsers import ...) — parsers, typed Session/message models, and the event verbs, to build your own tools.

Method vocabulary

The full dictionary of public verbs and presets (signatures, parameters, behaviour) lives in it