Commands

You never need to type these: the guides show what to say, and your agent runs the command. This page lets you see exactly what runs, or work without an agent.

Run them from the project root; trace_record.py --help and each subcommand’s --help give the arguments. The form follows the TRACE-OS sources; on macOS use python3 where python is missing, and on Windows py -3.11. The Overleaf guide has no command here, because the release ships no Overleaf script.

Set up a project

python scripts/bootstrap.py --target ../my-research --agent claude --plan    # show the plan; writes nothing
python scripts/bootstrap.py --target ../my-research --agent claude --apply   # set the project up
python scripts/shared_snapshot.py --help                                     # how to take a verified local snapshot of bulk inputs

Connect the shared folder

From 0.1.0-rc21.

python scripts/shared_folder.py status                                   # where the shared files are on this computer, and the next step
python scripts/shared_folder.py find                                     # the sync apps' folders on this computer
python scripts/shared_folder.py connect "<folder>" --plan                # what would change; writes nothing
python scripts/shared_folder.py connect "<folder>"                       # link workspace/shared to the team's folder and keep it out of Git
python scripts/shared_folder.py bucket set <remote>:<bucket>/<folder>    # use a bucket through rclone instead
python scripts/shared_folder.py bucket unset                            # stop using the bucket; the bucket and the local copy are unchanged
python scripts/shared_folder.py pull --plan                              # what a pull would copy; pull and push never delete
python scripts/shared_folder.py check                                    # conflict copies, online-only files, Google Docs shortcuts
python scripts/shared_folder.py inventory                                # write sources/shared-inventory.json, for Git
python scripts/shared_folder.py verify                                   # this computer's copy against that inventory
python scripts/shared_folder.py snapshot <subfolder> --dataset <name>    # a checked local copy under workspace/snapshots/
python scripts/shared_folder.py keep-local "<pattern>"                   # keep a path out of Git, naming files Git already tracks
python scripts/shared_folder.py disconnect                               # remove the link; the shared folder is untouched

Record a session

python scripts/trace_record.py session                     # this session's transcript and the model that executes it
python scripts/trace_record.py keep --subject "<the commit's subject>"   # before each commit: the record routine in one command, and the commit body
python scripts/trace_record.py keep --subject "<the commit's subject>" --cleared <digest>   # after reading every captured turn, with the digest keep printed
python scripts/trace_record.py keep --exclude <turn> "<reason>"   # exclude a turn the summary does not cite, with the reason
python scripts/trace_record.py --help                      # every subcommand, including extract (extract current reads the running session)
python scripts/trace_record.py annotate-input workspace/record-staging/session --input workspace/record-staging/annotation.json --by actual-agent-or-person   # mark a passage's role and origin
python scripts/trace_record.py cover workspace/record-staging/session            # refresh coverage
python scripts/trace_record.py privacy-check workspace/record-staging/session    # screen for credentials
python scripts/trace_record.py publication-review workspace/record-staging/session --by actual-reviewer --scope "Intended repository audience and sharing context"   # record the disclosure review
python scripts/trace_record.py promote workspace/record-staging/session ai/records/session   # move the record to ai/records/
python scripts/trace_record.py verify ai/records/session --strict                # check the promoted record
trace_record.py decision <record> --input <json>           # record a consequential choice, with its reason, when it is made
trace_record.py draft-message <record> --subject "..." --out <file>   # assemble a commit body by hand; keep drafts one itself
git commit --file <file>                                   # commit with that body
trace_record.py view --out ai/TRACE-VIEW.md                # read the decision account
python3 scripts/trace_record.py procedure-version trace-review   # the version of a skill, read off its file

Review work

python3 scripts/agentic_review.py <sha> --backend <codex|claude> --checks --criteria "<the criterion>" --checks-jsonl <the record's checks.jsonl>   # an agent reviews one commit
python3 scripts/agentic_review.py <sha> --backend <codex|claude> --checks --criteria "<the criterion>" --source <file or folder> --checks-jsonl <the record's checks.jsonl>   # against a named source; the report goes to ai/reviews/<run>/
python3 scripts/trace_record.py check --person --by "Full Name" --said "<their words>"   # a check a person made, read back; --confirm --checks-jsonl <file> appends it
python3 scripts/trace_record.py accept --agent             # record a model's review: advisory, never acceptance

Accept, return or refuse work

python3 scripts/trace_record.py queue                      # the table of what waits, then the commits that name no record
python3 scripts/trace_record.py queue --list               # the compact listing
python3 scripts/trace_record.py brief <record-id>          # one record on one screen
python3 scripts/trace_record.py accept --record <record-id> --person --by "Full Name" \
    --recorded-by <model-id> --words "what the person said" \
    --through <sha>                                        # a decision said to an agent, on the version the brief showed
python3 scripts/trace_record.py accept --person --by "Full Name" --decision return \
    --objections "..."                                     # a return, with its objection
python3 scripts/trace_record.py accept --by "<actor>" --authorized-by "Full Name" \
    --authority "<the authorization's words>" \
    --criteria "..." --evidence "..." --independence "..."   # a delegated decision
python3 scripts/trace_record.py review-status              # what stands where

Admit outside material

python3 scripts/trace_record.py intake --what "..." --origin "..." \
    --by "Full Name" --person --checked "what you verified first" --used-for "..." \
    --authority "T3 of ai/records/<id>" --path <file, when it is one> \
    --version "..." --decision admit|return|refuse        # record the decision on what came in, and what was checked

Move a draft into the manuscript

python3 scripts/trace_record.py transition --kind promotion --object paper/sections/<file> \
    --checks ai/records/<id>/checks.jsonl --by <actor> --authority "T4 of ai/records/<id>" \
    --destination paper/ --commits <sha>                   # record the promotion

Change a standing instruction

python3 scripts/trace_record.py transition --kind default-adoption --object AGENTS.md \
    --commits <sha> --later-run ai/records/<later id>      # record the adoption
python3 scripts/trace_record.py later-run TR-023           # list the records that could be its later run
python3 scripts/trace_record.py later-run TR-023 --record ai/records/<later id> \
    --observed "what the revised instruction did in that run" --by "Full Name" --person   # record the observation

Raise, fix and recheck a finding

scripts/defect_ledger.py open --label TEXT --severity high|medium|low   # open a row; add --quote, --source, --by, --object, --affected, --faulty-default
scripts/defect_ledger.py ingest --run ai/reviews/<run> --finding <id> --matches <file>   # a review's reproduced finding, before it is fixed
scripts/defect_ledger.py mark --id ID --note TEXT           # record an answer; the state stays
defect_ledger.py mark --id <ID> --fixed --by <fixer> --note "<the fix>"   # mark it fixed
scripts/defect_ledger.py draft-recheck ID --checker NAME --person   # draft the recheck from the checker's words (--method, --outcome, --limitations, --said); --object for each listed output
scripts/defect_ledger.py verify ID --evidence FILE          # record the confirmed recheck
scripts/defect_ledger.py check                              # fails on a recurred or unresolved defect

Run the checks

python scripts/check_workflow.py --out workflow-check.json                         # the mechanical checks
python scripts/trace_stats.py --report workflow-check.json --out TRACE-STATS.md    # the health snapshot, even after a failure
python3 scripts/trace_report.py                            # the commits with a missing record, per principle
python3 scripts/check_skill_handoff.py                     # whether each skill states its handoff
python scripts/trace_record.py verify-range <range>        # read commit messages; blocks nothing
python -X utf8 -I -S -m unittest discover -s tests -v      # every test, the project's own included

Leave comments while reading

review_inbox.py collect --json                             # gather REVIEW markers into a packet
trace_record.py comments <staging-record> --input <packet>   # capture them in the record

Update TRACE-OS

python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude --plan   # plan the update
python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip \
  --expected-sha256 <digest-from-the-release-sidecar> --update      # apply one release
python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip \
  --expected-sha256 <digest-from-the-release-sidecar> \
  --release-store /path/to/earlier-release-archives --update-chain   # walk several releases
python scripts/bootstrap.py --target . --rollback          # undo the latest completed update
python scripts/bootstrap.py --recover                      # finish or undo an interrupted operation
python scripts/kit_projects.py list --root ~/Developer     # every TRACE project under a folder
python scripts/kit_projects.py update --root ~/Developer --all \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip --sha256-file /path/to/trace-os-0.1.0-rcN.zip.sha256   # update them all

Bring in a skill

python scripts/trace_skills.py list <repository> [--ref <branch, tag or commit>]        # the packages a source holds
python scripts/trace_skills.py show <repository> <path> [--ref <branch, tag or commit>] # every file of one package
python scripts/trace_skills.py adopt <repository> <path> --candidate <candidate.json> \
  --by "Full Name" --words "the person's words" --authority "T3 of ai/records/<id>"     # adopt it, after a yes
python scripts/trace_skills.py status [--offline]          # where every skill stands
python scripts/trace_skills.py update <name> [--ref <branch, tag or commit>]            # offer an upstream update
python scripts/trace_skills.py retire <name> [--drop-base]  # remove an adopted skill
python scripts/trace_skills.py link .trace-os/skill-adoptions/<operation id>.json --commit <sha>   # write the adoption row after the commit
python scripts/trace_skills.py recover                     # finish or undo an interrupted operation
python scripts/bootstrap.py --sync-skills                  # refresh the agent's copies after editing a skill