Install and troubleshoot

Everything Get started leaves out: what to install, how to check it, and what to do when setup does not go as planned.

What to install

You need	Why	Check it
A coding agent: Claude Code (a paid Claude plan) or Codex (a paid ChatGPT plan)	It does the work and runs the commands	Ask it “What model are you?”
Git, with your own name and email set	It keeps the project’s history	Ask your agent “Is Git installed, and what name and email is it set to?”
Python 3.11 or later	The checks are small Python scripts	Ask your agent “Which Python version do I have?”
A sync app with a folder for the project: OneDrive or Google Drive, or Dropbox, SURFdrive or SURF Research Drive	It holds the large and bulky files your team shares, outside Git	Ask your agent “Is the shared folder connected?”

A coding agent is a chat assistant that can also read and change the files in one folder on your computer and run programs there. LaTeX is optional until you build a paper or slides. The checks need no other account or subscription.

macOS

1. Git: open Terminal, paste xcode-select --install, and press Return.
2. Python: install 3.11 or later from python.org. If there is no python command afterwards, your agent uses python3.
3. The agent: install VS Code, then the Claude Code or Codex extension, and sign in.

Windows

1. Git: install Git for Windows with the default options.
2. Python: install 3.11 or later from python.org, and tick “Add python.exe to PATH” in the installer. If python finds an older version, your agent uses py -3.11.
3. The agent: install VS Code, then the Claude Code or Codex extension, and sign in.

What success looks like

After setup, the agent runs the checks. Every line reads pass or info:

The workflow check

  pass        portable test suite
  pass        installed skill parity
  info        skill handoff
  pass        trace records
  pass        registries
  info        review status
  info        defect ledger
  info        governing actions
  pass        build configuration
  info        shared folder
mechanical checks passed; 12 skipped, 0 warning(s)

Before it writes anything, the agent shows a plan and stops if a file would be overwritten. A new folder gets its own Git history; an existing Git project keeps its history.

If something goes wrong

What you see	What to say
Python is too old, or not found	Install 3.11 or later (above), then “Run the checks again.”
Git has no name or email	“Set my Git name to Your Name and my email to you@example.org.” Setup never invents an author.
The plan lists conflicts	Existing files would be overwritten, so nothing was changed. “Show me the conflicting files.”
The first commit fails	“Show me Git’s error and the staged files.” Setup never commits work that was already staged.
The project is in a synced folder	Move it out of Dropbox, OneDrive or iCloud before you go on.
The shared folder is not connected	“Our shared folder is in OneDrive, called Patent study. Connect it.” See Connect your shared folder.

Things to know

• Setup never invents an author, installs software, creates service accounts, configures a remote, pushes, or adds a commit hook.
• An existing project keeps its history, its instruction files and its research registries; conflicts are reported before anything is written.
• Keep the project outside a folder a cloud service keeps in sync. Its large files go in the shared folder, which is the synced one.

What the agent runs

An agent adds --execution-agent <model-id>, the model ID that python scripts/trace_record.py session reads off a running Claude Code or Codex session; choose claude, codex, cline or none for --agent. On macOS use python3 when there is no python; on Windows, py -3.11.

python scripts/bootstrap.py --target ../my-research --agent claude --plan
python scripts/bootstrap.py --target ../my-research --agent claude --apply
python scripts/check_workflow.py --out workflow-check.json
python scripts/trace_stats.py --report workflow-check.json --out TRACE-STATS.md

The setup receipt is .trace-os/receipts/latest.json. It records what setup did, not that the tests passed.