From nothing installed to your runs in the console.
Follow these steps in order. You'll install onetrace, record a tiny example twice, see which step changed, and open both runs in the console on your own machine. Then you'll do the same on your own code.
Three words first
Run
One complete pass of your program, for example answering one question.
Stage
One step inside a run, for example "find the right document" or "write the answer".
Record
What onetrace writes for each run: a folder with a small file per stage, saying what went in and what came out.
Set up
Get Python ready and install onetrace.
You type the commands below into a terminal. On Windows that's PowerShell (search for it in the Start menu). On macOS it's Terminal. Type each line and press Enter.
Check that you have Python 3.12 or newer
Windows (PowerShell)
py --version
macOS or Linux (Terminal)
python3 --version
If it prints Python 3.12 or a higher number, carry on. If it prints an older version or "not found", install Python from python.org/downloads. On Windows, tick "Add python.exe to PATH" in the installer. Then close the terminal, open a new one and check again.
Make a folder, with a private Python space in it
The "virtual environment" (.venv) keeps what you install here separate from the rest of your computer.
Windows (PowerShell)
mkdir onetrace-start cd onetrace-start py -3.12 -m venv .venv .venv\Scripts\Activate.ps1
macOS or Linux (Terminal)
mkdir onetrace-start cd onetrace-start python3 -m venv .venv source .venv/bin/activate
Your prompt now starts with (.venv), and every later command runs inside it. If you close the terminal, come back with cd onetrace-start and the last line again.
Install onetrace and the console
pip install onetrace onetrace-console
This installs onetrace (records your runs), onetrace-verify (checks a record) and onetrace-console (shows runs in your browser). Nothing is sent anywhere; the console only listens on your own machine.
Want to see where you're heading first? onetrace-console demo --open opens the demo in your browser. Press Ctrl+C in the terminal to stop it.
A first example
Record a tiny program twice, and find what changed.
The example answers a question from three short documents. It has two stages: retrieve finds the best document, and answer writes the answer. It needs no AI service and no key.
Create the file app.py
In your onetrace-start folder, create a file named app.py with any text editor (Notepad, VS Code, or TextEdit in plain-text mode) and paste this in. The lines with ot are the only onetrace parts.
import sys
import onetrace as ot
DOCUMENTS = [
"Customers can request a refund within 30 days of purchase.",
"Shipping is free on orders over 50 euros.",
"Support is open Monday to Friday, 9:00 to 17:00.",
]
TOP_K = 1 # how many documents to retrieve
@ot.stage("retrieve", instrument=ot.pkg("word-overlap", "onetrace",
kind="retriever", config={"top_k": TOP_K}))
def retrieve(question):
words = set(question.lower().split())
ranked = sorted(DOCUMENTS, key=lambda d: -len(words & set(d.lower().split())))
return ranked[:TOP_K]
@ot.stage("answer", instrument=ot.pkg("first-passage", "onetrace", kind="model-call"))
def answer(question, passages):
return "Answer: " + passages[0]
@ot.run(stages=["retrieve", "answer"])
def main(question):
passages = retrieve(question)
print(answer(question, passages))
if __name__ == "__main__":
main(" ".join(sys.argv[1:]) or "How long do I have to request a refund?")
Run it, change one word, run it again
The first run is named before:
Windows (PowerShell)
$env:ONETRACE_RUN_ID = "before" python app.py
macOS or Linux (Terminal)
ONETRACE_RUN_ID=before python app.py
It prints the answer and the line onetrace: run written to runs/before. Now open app.py, change 30 days to 14 days, save, and run it again as after:
Windows (PowerShell)
$env:ONETRACE_RUN_ID = "after" python app.py Remove-Item Env:ONETRACE_RUN_ID
macOS or Linux (Terminal)
ONETRACE_RUN_ID=after python app.py
Your folder now has runs/before and runs/after. Each name works once; to record again, pick a new name or delete the old folder.
Check a record, and compare the two
onetrace-verify --require-artifacts runs/after onetrace diff runs/before runs/after
The check ends with PASS: the record is complete, and nothing in it was changed afterwards. The comparison lists each stage. intake (the question going in) is same. retrieve is the FIRST DIFFERENCE, because the document it found now says 14 days. answer is downstream: it changed because the step before it did.
Lines marked NOT-RUN are normal. They name checks this record doesn't use, such as signatures. They aren't errors.
The console
See both runs, and their comparison, in your browser.
Open the console on your runs folder
onetrace-console runs --compare before after --open
Your browser opens on the Overview with your two runs. Comparisons shows retrieve as the first difference, and the text that changed. Click a run to see its stages and what was checked.
The console keeps its own copy of the runs in a store folder beside runs. It listens on 127.0.0.1 only, so only you can open it. Press Ctrl+C in the terminal to stop it. Run the same command whenever you've recorded new runs; leave out --compare before after to just list them.
Your own code
Do the same on your own program.
Two ways. Either works; the first is easier if you use an AI coding tool.
A. Let your coding agent do it
Open your project in Claude Code, Cursor, GitHub Copilot, Windsurf, Cline or Codex, and give it the prompt from the agent kit. It adds onetrace, checks that nothing else changed, and asks you the few questions only you can answer.
B. Add it yourself
Install onetrace in your project's own environment, then make the same three kinds of edit as in app.py:
import onetrace as otat the top.@ot.stage("name", instrument=ot.pkg(...))above each step's function.@ot.run(stages=["name", ...])above the function that does the whole job once, listing your stages in order.
Change nothing else. Then run, check, compare and open the console exactly as above. The quickstart and the manual cover the details.
If something goes wrong
The usual snags, and the fix.
| You see | Do this |
|---|---|
"running scripts is disabled on this system" (Windows, at Activate.ps1) | Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, answer Y, then run the activate line again. |
python or py is "not found" | Install Python from python.org (on Windows, tick "Add python.exe to PATH"), then open a new terminal. |
onetrace or onetrace-console is "not recognized" | The virtual environment isn't active. cd into your folder and run the activate line from step 2. |
| A message that the run folder is already used | Each run name works once. Use a new name, or delete the old folder under runs. |
| The console says it "cannot listen on 127.0.0.1:8080" | Another console is probably still running. Stop it with Ctrl+C in its window, or add --port 8091 (any free number) to the command. |
onetrace-console --version says 0.0.0, or it lists commands such as admin create | An older install answered first. Make a fresh folder and virtual environment as in steps 2 and 3, and install there. where.exe onetrace-console (Windows) or which onetrace-console shows which one answers. |
| You want to run your program without recording | Set ONETRACE_DISABLE=1 (PowerShell: $env:ONETRACE_DISABLE = "1"). Nothing is written. |
Still stuck? Every error onetrace prints has a one-line fix and a link; they're all on Errors and fixes. Questions and bugs go to onetrace-issues.