Docs · chapter 1

Which program?

Updated 14 November 2026 · version 0.17

Two programs, in the same zip. ProtoTTD records and debugs: start there. ProtoInsight compiles a recording into an index and answers analysis questions on it, for you or for an agent. Both record the same way, with the same options.

In short

ProtoTTD.exe

The time-travel debugger

A window (or a prompt) that records a program, then debugs the run forward and backward: breakpoints, memory and registers at any instant, source and types from the PDB, Python scripts. An agent can drive the window.

ProtoInsight.exe

The analysis

Compiles a capture into a bundle (functions, loops, calls, strings, data flow) and answers one question per call, in JSON: what the program reads and writes, where a value comes from, which functions matter.

File	Made by	What it is
`app.proto.cap`	Recording (either program)	The capture: every instruction of every thread, with the registers and the memory they touched. ProtoTTD reads it directly.
`app.proto.bundle`	ProtoInsight index	The capture compiled for analysis: the index ProtoInsight's tools read. The capture is only read to make it.
`run.json`	You, or the window	How a run is recorded: the config file.

What do you want to do?

Find your goal on the left; the right says what to use, and where it is explained.

I want to…	Use	Chapter
Record a program from its start	`ProtoTTD: Record, or launch`	Recording
Record a program that is already running	`ProtoTTD: Attach, or attach`	Recording
Record only from a certain call or instruction	`"trace_from"`	The config file
Stop the program on its own after a while	`"stop_after"`	The config file
Keep a library out of the recording	`"exclude_modules"`	The config file
Change what an instruction does	`a patch rule`	Patch and thread rules
Record some threads only	`a thread rule`	Patch and thread rules
Step through the run, forward and backward	`ProtoTTD on the capture`	Debugging
See my source lines and variables	`ProtoTTD + the PDB`	Debugging
Script the debugger	`Python: import protottd`	Debugging
List what the program read, wrote and sent	`ProtoInsight … io`	Analysis tools
Find where a value came from	`ProtoInsight … flow / taint`	Analysis tools
Have an AI agent record, debug or analyse	`the Agent pane, or serve`	Agents and prompts

Every command

The option --config goes before the command. Each program's --help is short and points to these pages.

ProtoTTD.exe                                         # the window: Record, Attach, Open
ProtoTTD.exe record [--config run.json] <program.exe> [args]   # the window, recording it at once
ProtoTTD.exe [--config run.json] launch <program.exe> [args]   # record, headless
ProtoTTD.exe [--config run.json] attach <pid> [<tid>|all]      # record a running process, headless
ProtoTTD.exe gui <capture.proto.cap>                 # the window on a capture
ProtoTTD.exe <capture.proto.cap>                     # the debugger's prompt (.help lists its commands)
ProtoTTD.exe <capture.proto.cap> --ui                # JSON in, JSON out: one {"op":...} per line, for scripts
ProtoTTD.exe serve <capture.proto.cap>               # the daemon alone, for agents
ProtoTTD.exe install                                 # a Start menu shortcut; .proto.cap files open in the window

ProtoInsight.exe [--config run.json] launch <program.exe> [args]
ProtoInsight.exe [--config run.json] attach <pid> [<tid>|all]
ProtoInsight.exe index <capture.proto.cap> [<bundle>]     # compile a capture
ProtoInsight.exe <bundle.proto.bundle> <tool> [json]      # one analysis question
ProtoInsight.exe serve <bundle.proto.bundle> [label]      # the daemon alone, for agents

Option	Effect
`--config <run.json>`	Everything a run is told besides what to run, in one JSON file: The config file.
`-h, --help`	The short help.
`-v, --version`	The version.

Free, with a limit

Everything on your machine is free, up to what a person does in an hour: 3,600 debugger commands and 600 analysis calls. Agents work through MCP, paid per call (0.25 credit). 32-bit programs are recorded with the same commands: the zip carries the 32-bit engine, used by itself.

Quick start

Recording