What TRACE-OS is

TRACE-OS is an implementation of the five governing principles for AI-assisted research, made available to other researchers. It sets up a research project so that each unit of work keeps the instructions, checks and decisions that shaped it, whichever coding agent each coauthor uses.

Why it exists

AI-assisted research is research in which a generative AI system produces or evaluates material that enters the work or informs a research decision. When researchers delegate production to such a system, responsibility for the resulting claims stays with them. To exercise it, a team needs an overview of the delegated work: which choices the system made, which were checked and against what, and who accepted the result. Without a record of these choices and checks, the researcher who delegated the work, or a coauthor, has difficulty understanding how a result was produced.

TRACE-OS keeps that record as part of the workflow, in the project’s own repository, where the whole team can read it.

What it provides

• Shared instructions that every agent in the project reads. AGENTS.md is the single source; CLAUDE.md only points to it. These are the project’s standing instructions: they apply to later tasks by default.
• A trace record for each agent session that commits work: a record of human direction and machine execution. It keeps your words verbatim, what the agent chose, what it checked and what it did not.
• Declared decisions. An actor independent of production accepts, returns or refuses a unit of work. A person’s decision is recorded in their name and in their own words, and model review is kept apart from it.
• Records at the boundaries: inputs admitted from outside, drafts moved into the shared manuscript, and instructions adopted as defaults.
• A defect ledger that keeps a finding open until a targeted recheck shows that the correction worked.
• A governing-actions report that says, for every commit and each principle, whether the action is recorded, missing, not applicable or unknown.
• Paper and slide skeletons with a tracked build recipe, so the PDF builds the same way on every machine.
• Six governance routines that agents follow (trace-state, trace-review, trace-acceptance, trace-ctransition, trace-evaluate, trace-check) and four research skills as worked examples of research methods under TRACE: ten skills in all.

What version history alone does not show

Git keeps who committed what, and when. This is an example project’s history, the same in any Git project:

git log

a890336 Miros Zohrehvand  Record Miros's acceptance of the yearly shares
bc7d46a Miros Zohrehvand  Compute the yearly shares of non-publication cases
ea38262 Miros Zohrehvand  Record the setup and the project epochs
f4ac16b Miros Zohrehvand  Initialize research workflow starter

TRACE-OS keeps the rest in the same history. The commit on the second line says what was asked, in whose words, what was checked and what was not, and which model executed the work:

The same commit, with its record

commit bc7d46a
Author: Miros Zohrehvand <[email protected]>

Compute the yearly shares of non-publication cases

Human direction account:
- T1: Miros asked for 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, written to `workspace/sandbox/shares.md`.
  The agent (claude-opus-5-5) computed each year's share from its counts and the overall share as 239 / 2166 = 11.0%.
- T2: Miros read the draft and asked for it to be finalized and committed.

Checks and review:
- 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 [the checker's words, kept in this row]

Record: ai/records/20261007-yearly-shares

Execution-agent: claude-opus-5-5

How the workflow runs

You direct the task in your own words, the agent executes it and drafts the trace record, you read the record and finalize it, and an actor independent of production later accepts, returns or refuses the work. The workflow describes each step, and Get started takes you through it once.

What it does not do

It blocks nothing. There is no commit hook and no gate. The checks report what they find, and work can be committed and shared in any state. What TRACE-OS keeps distinct is unreviewed, reviewed and accepted work, so that one is never mistaken for another.

It does not make an AI an author. Authorship carries accountability, and a model cannot hold it. The person is always the Git author; the model that executed the work is named by an execution marker, which records production, not authorship.

It does not establish quality. A passing check supports only what it examines. The records show which actions were taken and what evidence was retained, and their limits say what was not examined; they do not establish that every required action occurred, that a check was adequate, or that a person understood every implication of a decision. Whether the workflow improves research outcomes remains an empirical question.

It does not need a subscription for its core. The checks are small Python scripts that run on your own machine. A coding agent is how the workflow is meant to be used, but the records and checks work without one.

The terms this site uses are in the glossary.

What you need

Python 3.11 or later and Git. LaTeX is optional until you build the paper or slides. A coding agent (Claude Code or Codex) is how TRACE-OS is meant to be used, and each coauthor can use their own.