Install traces.md

TRACES.md is a simple, open format for recording what AI agents did: objective, append-only, failures included. This package ships the reference CLI. You install it by handing this page to your AI.

For humans

Paste this into your AI coding agent (Claude Code, Cursor, Codex, or any capable agent). It reads this page and sets everything up, asking before it changes anything.

Read https://maxont.github.io/TRACES.md/install and install traces for me.

You need Python 3.9 or newer and an agent that can run shell commands.

Prefer the terminal? One line installs the traces command (it never edits your shell config):

curl -fsSL https://maxont.github.io/TRACES.md/install.sh | bash

Want to read the script first? install.sh. Add --dry-run to see what it would do without changing anything.

FOR YOUR AI

You are the AI agent the user gave this page to. Everything below is addressed to you. Follow it in order. If you cannot do a step, say so plainly instead of pretending.

0. What you are installing

TRACES.md is a simple, open format for recording what AI agents did: objective, append-only, failures included. This package ships the reference CLI. Source: https://github.com/MaxonT/TRACES.md.

1. Capability gate

You must be able to (a) run shell commands and (b) read and write files in the user's home directory. If either is missing, stop and tell the user to paste this prompt into an agent that can, or to run the terminal one-liner above by hand.

2. Preconditions

python3 --version reports 3.9 or newer.
One of uv, pipx or python3 -m pip is available. Prefer them in that order.
Never use sudo. Never install system-wide.

3. Ask before you touch anything

Before running anything that changes the machine, show the user the exact command and wait for a yes. Start with a dry run:

curl -fsSL https://maxont.github.io/TRACES.md/install.sh -o /tmp/traces.md-install.sh
bash /tmp/traces.md-install.sh --dry-run

Read the output to the user. After they agree:

bash /tmp/traces.md-install.sh
traces --version

If traces is not on PATH, do not edit shell config on your own. Tell the user which command fixes it (uv tool update-shell, pipx ensurepath) and ask. Until then python3 -m traces is equivalent.

4. First run

traces --help
traces validate --help

Then, with the user's yes, try it in the repository you are working in. <agent> is your own tool id, lowercase, for example claude-code, cursor, codex, trae:

traces init --agent <agent> --task "set up traces"     # creates .trace/ and a trace file, prints its path
export TRACES_FILE=.trace/<the printed file>
traces append -t "shell: traces --version" -a "check the install" -s ok -d "exit 0"
traces validate

5. How to write traces from now on

For every task you perform, keep one trace file under .trace/. One line per operation: when, which tool, what it did, how it ended. Use traces append for each step, or traces run -- <command> to run a command and record its real exit code. The format is in SPEC.md.

Failures are recorded. A trace with only successes is non-compliant. A failed step stays fail even if a later step repairs it.
Objective only. What tool, what it did, what came back. No reasoning, no opinion, no story.
Append-only. Never edit or delete a recorded step.
Run traces validate before you finish. It exits 1 on a malformed or dishonest trace.

6. Rules you must keep

Additive only. Never overwrite or delete existing user files.
Do not touch shell config, ~/.ssh, ~/.gitconfig or LaunchAgents without an explicit yes for that specific change.
Be honest about failure. If a step failed, say which one and why.

6. Report back

Finish with a short summary: what was installed, whether traces --version worked, what you did not do, and the one next step for the user.

traces.md is MIT licensed. Star it on GitHub if it helps you.