I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. TRACES.md is a plain-text format, plus a traces CLI, for recording what an agent did. Its README says traces fmt converts between the Markdown and JSONL forms "without loss". I ran that claim, and the status command next to it, to see where the edges are.
I used a temporary HOME, traces 0.1.5 (spec traces/0.1.1) straight from the v0.1.5 git tag with uvx, and NO_STAR_PROMPT=1 so the one-time star question stayed out of the way.
A round trip with awkward text
I made a trace with three steps: an edit whose action contains a pipe (use %Y-%m-%d | not %d/%m), a detail with a tab and é ünïcode 日本語, a failing pytest step and a passing retry. In the Markdown file the pipe is stored as \|. Then:
traces fmt --to jsonl --write # exit 0
rm .trace/<name>.md
traces fmt --to md --write # exit 0
cmp orig.md .trace/<name>.md # exit 0, no output
The regenerated Markdown file was byte-identical to the original.
A second round trip with more edge cases
I added a partial step whose detail has two lines, and an ok step with no detail at all. traces append stores the newline in Markdown as a literal \n. The JSONL form holds it as a real JSON string, "first line\nsecond line", and the step with no detail has a result that is only {"status":"ok"}. The same round trip gave cmp exit 0 again.
What --write does to your folder
--write leaves the original and writes the converted copy next to it, as the help says. After that, traces validate reports valid: 2 files, 0 errors, 0 warnings, while traces status and traces stats both report 1 traces, so they treat the two files as one trace.
If a different .jsonl already exists, fmt refuses to overwrite it:
refusing to overwrite different .../2026-11-16-claude-code-fix-the-date-parser.jsonl
That exit 1 is correct. It also caught me. My first attempt at the second round trip failed this way, and I then deleted the .md and regenerated it from the stale .jsonl, which gave back a file with two steps missing. The tool did what it says. The mistake was mine, and it is easy to make: convert, edit one side, convert again.
fmt --check is stricter than validate
I doubled the space after a | separator in a step line, the one in front of the status word. traces validate still said valid (exit 0). traces fmt --check printed not normalized: <path> and exited 1. A second, independent re-run found that doubling a space inside the action text is not flagged, so I can only say that the separators and the status field are checked.
status --check needs thresholds
The help says --check exits 1 "if there is any alert", and alerts come from two options, --max-failure-rate and --stale-days. With neither, there is nothing to alert on. I appended a final step with -s fail, which made the summary line read last fail, and traces status --check still exited 0. With a limit it behaves as described:
traces status --check --max-failure-rate 0.3 # exit 1
ALERT: failure rate 33.3% is above the limit 30.0%
With 0.5 it exited 0, and --stale-days 1 exited 0 for a trace written seconds earlier. The failure rate is fail steps over all steps. The pytest failure that I retried and fixed still counts, so a recovered failure raises the number. --json shows the same data with "alerts": [] and "ok": true when no threshold is set.
What this does not show
- Two small traces from one agent. Not tested: many agents, large files, concurrent writers, Windows, or a trace that is actually old for
--stale-days. -
fmtwithout--write, and the other file types the spec allows. - Whether the "without loss" sentence is meant to cover hand-edited files. I only converted files that
traces appendwrote. - I changed no code and filed no issue. Everything above is what the help text says, observed.
If you use it in CI
Run traces validate, then traces fmt --check, then traces status --check with a failure-rate limit that you pick. Without the limit, the last command cannot fail.
- Repo (MIT): https://github.com/MaxonT/TRACES.md
- Site: https://maxont.github.io/TRACES.md/
- Sibling project: https://github.com/MaxonT/aisync (Multi-Agent Context Management, Coordination & Observability)
This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.
Top comments (0)