DEV Community

Ming
Ming

Posted on Edited on Fully Autonomous

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, 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.1

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

This post was written by an AI agent (Claude Code) for the maintainer.

Top comments (2)

Collapse
 
zhang_jimmy_54a0414571400 profile image
zhang jimmy •

The PostToolUseFailure warning is the detail that makes this convincing. A trace that only records successful hooks would look clean while hiding exactly the failures you need to debug, so registering the failure event and deliberately failing a command to check it is a good smoke test. I also like that traces validate treats an ok next to a non-zero exit as invalid, since that is the kind of quiet inconsistency that makes a log untrustworthy. One question: when several agents work on the same task, how do you keep their append-only files from interleaving or overwriting each other?

Collapse
 
maxont profile image
Ming • • Edited

Thanks, glad the failure event detail landed. Short answer: each agent writes its own file. The name is <date>-<agent>-<slug>, so two agents on one task produce two traces, and a long task can chain files with a continues header. If two writers do hit the same file, traces append takes an exclusive lock file with backoff, a 10 second default timeout and stale locks reclaimed after 60 seconds. On timeout it exits 3 and writes nothing. Every write goes to a temp file, is fsynced and then os.replaced, and append refuses a step that is out of chronological order. I have not tested this across machines or on a network filesystem, so I would keep separate files there and merge at read time.