TRACES.md: a plain-text flight recorder for what AI agents did
TRACES.md is an open format for recording what AI agents did. AGENTS.md tells an agent how to behave. TRACES.md is the file where it writes down what it actually did. I run several coding agents (Cursor, Trae, Kiro, Cla
TRACES.md is an open format for recording what AI agents did. AGENTS.md tells an agent how to behave. TRACES.md is the file where it writes down what it actually did.
I run several coding agents (Cursor, Trae, Kiro, Claude Code, Codex) on the same repositories. When something broke, I had no plain record of which agent ran which command and how it ended. TRACES.md came out of that.
The format
A trace is one plain, append-only file per task. One line per operation: when, which tool, what it did, how it ended. It records no reasoning and no story, and it records failures.
A minimal file, .trace/2026-10-12-claude-code-fix-date-parser.md:
task: Fix the failing date parser test
agent: claude-code
started: 2026-10-12T09:14:02-05:00
spec: traces/0.1.0
2026-10-12T09:14:31-05:00 | shell: python -m pytest tests/test_dates.py | run the date tests | fail: exit 1, 1 failed, 11 passed
2026-10-12T09:15:02-05:00 | edit: src/dates.py | change the parse format string to %Y-%m-%d | ok: 1 line changed
2026-10-12T09:15:20-05:00 | shell: python -m pytest tests/test_dates.py | run the date tests | ok: exit 0, 12 passed
Each step is ts | tool | action | result, and the result is ok, fail or partial plus a factual detail. The same trace also exists as JSONL with a JSON Schema, and traces fmt converts between the two without loss.
The CLI
It needs Python 3.9+ and the standard library only.
traces init --agent claude-code --task "fix the date parser"
export TRACES_FILE=.trace/<printed file>
traces run -- python -m pytest
traces append -t "edit: src/dates.py" -a "fix the format string" -s ok -d "1 line changed"
traces validate
traces stats
traces run runs a command and records its real exit code. traces validate exits 1 if a trace is invalid or hides a failure, for example an ok next to a non-zero exit code, or a retry whose failure was never recorded. traces stats reports per agent, per tool, and the failure rate.
One pitfall if you record from hooks
Many hook systems fire their "after tool" event only when a call succeeds. In Claude Code, PostToolUse never sees a failed call. That arrives as PostToolUseFailure. A hook on the success event alone writes a trace that looks clean while every failure is missing. Register the failure event too, then make a command fail on purpose and check that a fail step shows up.
Where it fits
TRACES.md is the observability piece of a larger setup. The sibling project is aisync: Multi-Agent Context Management, Coordination & Observability. aisync keeps shared rules and a journal across every AI coding tool, and coordinates who is editing what. TRACES.md is the per-task record of what each agent did. aisync is a separate repo and tool; TRACES.md works without it.
Limits
This is version 0.1 of the spec, so expect changes. The repo is small and has no adoption numbers I would put in an article. It is not affiliated with AGENTS.md. It borrows that project's shape: one plain Markdown convention any agent can follow with no SDK.
The repository writes its own traces in .trace/, failures included.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.