Get started

Four steps. You talk to your agent, and it does the typing.

You need a coding agent (Claude Code or Codex, on a paid plan), Git and Python 3.11 or later. Not sure you have them? See Install and troubleshoot, or ask your agent to check.

1. Download TRACE-OS

Get the latest trace-os-<version>.zip from the releases page and unzip it. Keep it out of Dropbox, OneDrive and iCloud.

2. Say one sentence

Open the unzipped trace-os folder in VS Code, open your agent, and say:

Say to your agent

Read SETUP-AGENT.md. Set up the academic profile in a new folder called my-research next to this one, run the checks, and report any remaining configuration.

You should see something like this, with no conflicts:

Setup applied

applied    yes
changes    112 files
conflicts  0

remaining:
  - Run the portable tests and workflow check.
  - Review and commit ai/project.json and any setup changes.
  - Model discovery and permissions require a recorded rehearsal.

From now on, open my-research instead.

3. Say where your shared folder is

Large and bulky files (PDFs, datasets, recordings) live in a shared folder, not in Git. Make a folder for the project in OneDrive or Google Drive and share it with your coauthors there, then say:

Say to your agent

Our shared folder is in OneDrive, called Patent study. Connect it.

For data too large for a sync app, a paid bucket such as Google Cloud Storage works too.

The agent does the rest, and asks you again on any computer where the folder is not connected yet. See Connect your shared folder.

4. Ask for something real

Say what you want in your own sentences, for example:

Say to your agent

Here is our yearly table, filings.csv. Work out the share of non-publication cases in each filing year and the overall share as total cases over total patents. Put the result in workspace/sandbox/shares.md and tell me what you checked.

The agent does the work and shows you a draft record:

1 Your words, verbatim

evidence.json · T1 Miros Zohrehvand

Work out the share of non-publication cases in each filing year from workspace/sandbox/filings.csv, and the overall share as total cases over total patents. Put the result in workspace/sandbox/shares.md and tell me what you checked.

2 What the agent did

summary.md

Computed each year's share from its counts, and the overall share as 239 / 2166 = 11.0%.

3 What it checked

checks.jsonl · claude-opus-5-5 (model, advisory)

summed the five rows and recomputed each share from its counts: totals 239 cases and 2166 patents; every share matches.

4 What it did not check

checks.jsonl · limits

The counts were not checked against the original filing records.

A real draft record from an example project: what you read before saying finalize.

If it is right, say:

Say to your agent

I have read the draft. Finalize it in my name, then commit.

That is your first recorded unit of work, committed with you as its author and the agent named as its executor.

Next

• Where large files go: Connect your shared folder.
• How the work continues: the workflow.
• When someone decides on it: you, a coauthor or another authorized actor says “What is outstanding?”, then accepts, returns or refuses the work. See Accept, return or refuse work.
• Something went wrong? Install and troubleshoot.

What the agent runs

python scripts/bootstrap.py --target ../my-research --agent claude --plan
python scripts/bootstrap.py --target ../my-research --agent claude --apply
python3 scripts/check_workflow.py --out workflow-check.json
python scripts/shared_folder.py connect "<folder>"