Your First Trace¶

This guide walks through one simple AgentTrace run.

Step 1: Open A Git Project¶

Go to the project you want to track:

cd path\to\your\project

AgentTrace must be used inside a Git repository.

If your project is not a Git repository yet, run:

git init

Run this once per project:

agenttrace init

This creates the .agenttrace folder.

Start tracking a coding task:

agenttrace start "add input validation to the login form" --tool Codex --model gpt-5

The task text should describe the work in normal language.

The --tool and --model fields are optional, but useful later when reviewing what happened.

Use your normal coding tool or AI assistant.

AgentTrace does not change the code for you. It records what happened around the work.

After files have changed, run:

agenttrace snapshot

This records:

Run a test command and save the result:

agenttrace add-test "python -m unittest discover -s tests"

If you tested manually, record that instead:

agenttrace add-test "manual browser test" --no-execute --note "Checked login with valid and invalid passwords."

Create a small file called review-notes.md:

# Review Notes

- Checked the changed files.
- Tests passed.
- No obvious risk found.

Then add it to the trace:

agenttrace add-review review-notes.md

Run:

agenttrace report

AgentTrace prints the path to the generated report.

The report is saved as:

.agenttrace/runs/<run-id>/report.md

Run:

agenttrace dashboard

This creates:

.agenttrace/dashboard.html

Open that file in a browser to see a summary of your recorded runs.