What Is AgentTM? The Beginner's Guide to Recording Codex Runs with Workspace Checkpoints
CodexFuse Team · 2026-11-05T10:00:42.612Z · 19 min read min read
What Is AgentTM, the Time Machine for Codex Runs?
What is AgentTM? It is a local Go command-line tool that records Codex runs so you can inspect what an AI coding agent changed, when it changed it, and what the workspace looked like before and after. This guide is AgentTM explained in plain English, for developers who run Codex and want a replayable record of each run.
AgentTM works like a flight recorder for coding agents. You launch a Codex run through AgentTM, and it logs the run events to SQLite while taking snapshots of your workspace. Later you can open a local web UI, browse the history of a run, compare file versions, and restore any checkpoint into a separate Git worktree.
One fact belongs at the top, because this project is three days old. AgentTM launched on November 2, 2026, as version 0.1, and by November 3, 2026, the latest release was already version 0.3.4. Every version claim in this guide carries its date, because a project moving this fast can change under you.
The launch record is short. The repository was created on November 2, 2026, the Show HN post followed about four hours later, and a VibeHacker write-up followed about nine hours after that. The Show HN thread itself had 1 point and 0 comments when checked on November 5, 2026, so the launch reached developers through the write-up rather than through discussion on Hacker News.
In one sentence, AgentTM is a DVR for Codex runs. It does not write your code, and it does not replace Git. It watches a run you launched through it, keeps the timeline, and lets you rewind to any checkpoint it captured.
The snapshot idea is easy to see in miniature. AgentTM deduplicates identical file contents with SHA-256 blobs, so unchanged files are stored once instead of once per checkpoint.
A SHA-256 hash generator shows how a hash can stand in for file contents without revealing them. If you run tools like this on your own machine, VPS hosting gives you a server you control, which is a natural home for a local-first recorder like this one.
Why Do Codex Runs Need a Recorder?
A Codex run can touch dozens of files, run commands, and call tools, and when it finishes you are left with a changed workspace and a scroll of terminal output. If something broke halfway through, you often cannot tell which step broke it, or what the files looked like before that step.
Git helps, but only at commit boundaries. A commit records the state you chose to save, not the state between each tool call inside a run. If the agent edited a file five times in one run and you committed once at the end, the four intermediate states are gone.
That gap is what AgentTM fills. It records the run as a timeline of events with workspace observations attached to each step, so you can inspect a run between commits. The README puts it plainly: AgentTM complements Git, and it does not replace commits, branches, or code review.
The gap matters more as runs get longer. Codex can now work for hours on a task, and a long run produces a long trail of edits that no human can hold in memory. A recorder turns that trail into something you can search, diff, and restore from, instead of something you have to reconstruct from memory.
How Do You Record Your First Codex Run?
You record a run in four commands, run from inside the Git project you want to inspect. The quick start comes from the project README, and it assumes you have installed AgentTM and logged in to Codex already.
- Register the project. Run
agenttm initfrom inside your Git project, which sets up the local.agenttmdirectory where recordings live. - Check the Codex setup. Run
agenttm codex doctor, which verifies that the Codex CLI is installed, authenticated, and reachable. - Launch a recorded run. Run
agenttm run codex -- "Explain this project", which wraps a non-interactive Codex run and records it from start to finish. - Open the timeline. Run
agenttm ui, then open the printedhttp://127.0.0.1:7331address in your browser and choose Sessions to inspect the recording. - Inspect and restore. Open a recording, look at its Timeline, Operations, Files, or Changes views, and fork any checkpoint into a worktree when you want to reuse an earlier state.
The wrap command is the heart of the tool. The agenttm run codex command launches Codex in non-interactive mode and records the run, so only runs you launch through AgentTM are captured. A run you start directly in the Codex terminal is invisible to it.
A coding-task example from the README shows the permission model. The command agenttm run codex --sandbox workspace-write --snapshot-after-tool=true -- "Implement a small function and test it." gives Codex permission to write inside the workspace and takes a snapshot after each tool call. Codex keeps its own rules and approval policy, and model access still depends on your account.
Two practical details are worth knowing before you start. New recordings need an installed and authenticated Codex CLI, plus Git version 2.42 or newer and a Git working tree. The UI server binds to loopback only, and if port 7331 is already taken you can run agenttm ui --port 7332 instead.
If you already use an AI coding assistant from the terminal, the shape will feel familiar. How to use Claude Code covers the same kind of terminal-first workflow, where the agent works inside your project and you review the diff it produces.
What Is Inside an AgentTM Checkpoint?
An AgentTM checkpoint is a workspace observation tied to a moment in a run, not just a copy of your files. Each checkpoint records which files existed, what each file contained, and which run event it belongs to, so you can compare two checkpoints and see exactly what changed between them.
Recording starts with a baseline. AgentTM captures a baseline observation before a managed run begins, and a final observation after the run exits, including when a run is cancelled and cleanup succeeds. With snapshot-after-tool enabled, supported command executions, file changes, MCP calls, and dynamic tool notifications each trigger their own boundary observations.
Every supported completion gets its own checkpoint, including operations that changed nothing. Before observations may reuse an identical state when nothing changed, and identical file contents share SHA-256 blobs instead of being stored twice. Two scans at each boundary help detect concurrent changes, but the README is honest that they do not guarantee atomicity.
The agenttm codex checkpoints are observations, not proof of authorship. The README states that checkpoints associate observed states with activity, and they do not establish causal line attribution. Recorded activity does not prove which action authored a line, and AgentTM promises no deterministic execution replay or identical AI reasoning.
| Checkpoint layer | What it stores | Why it matters |
|---|---|---|
| Baseline | Workspace state before the run starts | Gives every later diff a starting point |
| Event timeline | Sanitized Codex events in order | Shows what the agent did, step by step |
| Boundary snapshots | File states after each supported tool call | Lets you rewind to the middle of a run |
| Final observation | Workspace state after the run exits | Captures the run result, including cancellations |
| SHA-256 blobs | Deduplicated file contents | Stores unchanged files once, not once per checkpoint |
| SQLite index | Events, operations, and manifest references | Makes the whole history searchable |
How Does the SQLite Run Log Work?
The agenttm sqlite run log is the index that makes the recordings searchable. AgentTM takes the JSONL event stream from Codex, sanitizes the events through an allowlist, and writes them into a SQLite index with an operation ledger. Workspace scans become immutable manifests plus SHA-256 file blobs, and a Go API with an embedded React UI reads them back for inspection.
SQLite is the right fit for a local recorder. SQLite is an in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine, and unlike most other SQL databases it has no separate server process. A complete database lives in a single disk file, which is why AgentTM can keep a whole run history inside your project folder.
Everything stays on your machine. SQLite, manifests, and blobs stay in your project .agenttm directory, the browser server binds to loopback, and AgentTM implements no telemetry or cloud sync. One nuance matters: Codex still sends prompts and context to its configured service, so the whole product is not offline even though AgentTM itself never phones home.
The log is also honest about its gaps. Missing starts, overlaps, omissions, and capture failures stay visible in the record rather than being filled in with invented history. Force-killed runs can leave pending records or locks, and the README tells you to run agenttm doctor before attempting recovery.
| Recorded item | Where it lives | What it gives you |
|---|---|---|
| Session events | SQLite index | A searchable timeline of the run |
| Operation ledger | SQLite index | Which operations ran, and in what order |
| Workspace manifests | Immutable files in .agenttm | A fixed record of each observed state |
| File contents | SHA-256 blobs in .agenttm | Deduplicated storage with integrity checks |
| Session purge | Explicit cleanup command | Deletes a recording when you no longer need it |
How Do You Diff Checkpoints and Fork One into a Worktree?
Diffing is the point of recording, and it happens in the local UI. You open the printed address, choose Sessions, open a recording, and use the Timeline, Operations, Files, or Changes views to browse historical files and compare a checkpoint against its parent. The historical file browser shows you what a file contained at that moment, even if later steps overwrote it.
Forking turns a checkpoint back into working files. Fork checkpoint restores eligible captured files into .agenttm/worktrees/ without replacing your source workspace, so your current tree, index, and HEAD stay untouched. AgentTM worktrees are isolated copies you can inspect, test, or merge from, while your main checkout keeps whatever state it already had.
A Git worktree is the mechanism underneath. A Git repository can support multiple working trees, allowing you to check out more than one branch at a time, and with git worktree add a new working tree is associated with the repository. AgentTM uses that same mechanism, but it fills the worktree from a recorded checkpoint instead of from a branch.
Forking has clear limits, and the README states them directly. A fork does not rewind the Codex conversation, restore external services, or execute captured code. It restores files, and only files, into an isolated copy.
| Action | What happens | What it does not do |
|---|---|---|
| Browse history | View files as they were at any checkpoint | Change your working tree |
| Compare diffs | See parent-to-checkpoint file changes | Prove which action authored a line |
| Fork checkpoint | Restore files into .agenttm/worktrees/ | Touch your tree, index, or HEAD |
| Continue a conversation | Explicit continuation on desktop only | Rewind or replay the agent reasoning |
| Purge a session | Delete the recording and unreferenced blobs | Delete your Git history or live files |
What Does Codex Already Do Without AgentTM?
Codex already gives you two of the three pieces, and knowing them keeps AgentTM in perspective. Non-interactive mode lets you run Codex from scripts without opening the interactive terminal, using codex exec with a task prompt as a single argument. While it runs, Codex streams progress to standard error and prints only the final agent message to standard output.
Codex exec is built for automation. By default it runs in a read-only sandbox, and in automation you set the least permissions the workflow needs, for example with --sandbox workspace-write when the agent must edit files. With --json, standard output becomes a JSON Lines stream so you can capture every event Codex emits, and with --ephemeral you can skip persisting session files to disk.
Codex also added experimental worktree support in version 0.154.0, shipped on September 9, 2026. The release added --worktree and /worktree, so an agent session can start in its own isolated checkout instead of your main working tree. That is isolation at session start: each task gets a clean lane, and you review the diff before anything lands.
The gap AgentTM fills sits between those two features. Codex exec gives you a run, and the worktree flag gives you isolation, but neither one keeps a replayable record of what happened inside the run. AgentTM adds the timeline, the before-and-after snapshots, and the checkpoint restore, and it arrived 54 days after native worktrees shipped, on November 2, 2026.
AgentTM vs Native Codex Worktrees: What Does AgentTM Add?
Native Codex worktrees and AgentTM solve different halves of the same problem. A native worktree isolates a session before it starts, so a risky task cannot pollute your main checkout. AgentTM records a session while it runs, so you can inspect and rewind what happened after it finishes.
The cleanest way to see the difference is to ask what survives the run. With a native worktree, you keep the checkout and the branch, and you review the final diff. With AgentTM, you keep the whole timeline: every supported tool call, the file state after each one, and the ability to fork any of those states into a fresh worktree.
They also compose well. You can start a Codex run inside a worktree for isolation, and record it through AgentTM for history, and you get both protections at once. The DevelopersDigest guide on Codex worktrees recommends exactly this shape of workflow: start risky work in a separate worktree, let the agent run without polluting the main checkout, review the diff and session state together, and merge only the useful output.
One warning from that guide applies to both tools. Worktrees can still drift, and agents can still touch the wrong files if the scope is loose. Isolation and recording make mistakes easier to find and undo, and neither one makes them impossible.
AgentTM vs AgentsRoom, Not Codex, and Clawdline
AgentTM is not the only tool organizing agent work, but the others do different jobs.
AgentsRoom is a Git worktree manager for Claude Code, Codex, and every agent CLI, built for running several agents in parallel, each in its own prepared worktree. Not Codex is a local-first control plane that brings six agent harnesses into one governed workspace with sessions, worktrees, approvals, and review. Clawdline is an open-source operator that manages Claude Code and Codex sessions across multiple Mac and Linux computers from a single list, with phone control.
The agenttm vs clawdline comparison is the sharpest one, because the two tools point in opposite time directions. Clawdline operates live sessions across machines: a root session on a Mac can start a session on a remote Linux machine, and the remote session notifies the root when it finishes.
AgentTM records past runs on one machine: history, snapshots, and checkpoint restore. One is present-tense orchestration, and the other is time travel.
AgentsRoom differs by scale.
Before an agent starts, AgentsRoom installs dependencies and copies your environment files into the new worktree, so the agent can build and run tests right away, and when it finishes you review, commit, push, and merge from the Changes tab. AgentTM does none of that preparation. It records one Codex run after you launch it, and its work is inspection and restore, not parallel orchestration.
Not Codex differs by breadth.
It translates six different session and event protocols into one durable timeline, so Codex, Claude Code, Cursor, Grok Build, OpenCode, and Pi share one governed workspace. AgentTM is single-harness: Codex only, and additional coding agents are not integrated.
How to use Clawdline is the closest sibling guide on this site, and it covers the live-session side of the lane this page joins. Not Codex is MIT licensed, while AgentTM is proprietary, which is covered in the license section below. Read it if you want to operate sessions across machines while they run, and read this page if you want to inspect them after they finish.
| Tool | Main job | Agent harnesses | License |
|---|---|---|---|
| AgentTM | Record Codex runs, diff and fork checkpoints | Codex only | Proprietary, public source |
| AgentsRoom | Parallel agents in prepared worktrees | Claude, Codex, Copilot CLI, Cursor, and 13 others | Commercial desktop app |
| Not Codex | One governed workspace for six harnesses | Codex, Claude Code, Cursor, Grok Build, OpenCode, Pi | MIT |
| Clawdline | Live sessions across Mac and Linux machines | Claude Code and Codex | Open source, Cloud Pro at 10 dollars a month |
What Are the Honest Limits of AgentTM?
AgentTM is three days old, and its limits are part of the story. The launch version captured only non-interactive Codex runs it launched, so a run you start directly in the Codex terminal, or an interactive chat session, is not recorded by the command-line tool. Interactive Codex chat, model discovery, and supported approval prompts exist only in the native Windows desktop preview, not in the CLI.
Snapshots are not redacted. File snapshot bytes are stored exactly as they were, so secrets embedded in captured files are stored too, and filename exclusions are no guarantee that every embedded secret is excluded. The event log uses an allowlist with payload limits and best-effort credential redaction, reasoning text and raw standard error are not retained, and prompt storage defaults to metadata only, but fragments can still appear in tool output.
Testing so far is narrow. Only Windows end-to-end use is reported as tested in the launch record, even though the repository carries install guides for macOS and Linux as well. Do not assume cross-platform end-to-end verification until the project reports it.
Recording is also narrower than it sounds. AgentTM captures only AgentTM-managed Codex runs and chat, not external sessions or every child-agent action, and it does not rewind the Codex conversation, restore external services, or execute captured code when you fork a checkpoint. Planned features are not implemented features: causal code provenance, checkpoint-based agent conversation forks, additional agent integrations, retry and performance analysis, and cloud sync are all listed as planned, not shipped.
Is AgentTM Open Source?
No, and this is the most commonly misunderstood fact about the project. AgentTM is public source under a proprietary license, which means you can read the code on GitHub, but the project is not offered under an open-source license. The README states that plainly, and the repository page lists the license as Other.
The proprietary license permits personal and internal business use of official binaries, plus installation and backup copies. Original source reuse, redistribution, resale, and third-party hosted services require separate written permission. Public visibility does not grant general source reuse or modification permission, and public source-code pull requests are not the contribution model: bug reports go through Issues, and original implementation contributions need a separate agreement with the owner.
The distinction matters when you compare tools. Not Codex is MIT licensed, so you can inspect the implementation and build it yourself under that license. AgentTM lets you inspect the implementation too, but building a product on its code is a different question, and it needs permission first.
Scale is worth a sober look as well. The repository had 3 stars, 0 forks, and 22 commits when checked on November 5, 2026, against more than 123,000 stars for the openai/codex repository as reported on September 10, 2026.
That gap is normal for a three-day-old project, and it is not a verdict on quality. It is a reminder to check the release notes before you depend on it.
Who Should Use AgentTM, and Who Should Wait?
AgentTM fits developers who run Codex on real repositories and want to inspect what happened. If you launch long non-interactive runs, review agent diffs before merging, or debug a run that went wrong halfway through, a recorded timeline with checkpoint restore saves you from reconstructing history by hand. It also fits teams that want an audit trail of agent work between commits.
It fits less well if your work is interactive. If you mostly chat with Codex in the terminal, the CLI recorder will not capture those sessions, and the desktop preview that supports them is a native Windows preview that is unsigned, so Windows reputation warnings may appear. Wait for the CLI to support interactive recording, or test the desktop preview on a disposable project first.
It also fits less well if you need multi-agent coverage. AgentTM records Codex only, so a workflow that mixes Claude Code, Cursor, or other CLIs needs a different tool for the other harnesses. AgentsRoom and Not Codex cover that ground, and Clawdline covers live sessions across machines.
One practical rule covers the rest. Treat AgentTM as a recorder, not a backup: keep committing to Git, keep secrets out of files the agent touches, and review any recording before you share it. If you want to run recorded agent workloads in an isolated machine instead of your laptop, how to use E2B covers sandboxed cloud environments built for exactly that kind of agent work.
Sources
All sources were fetched on November 5, 2026. Product details are as stated on those pages on that date.
- AgentTM launch record, VibeHacker, November 2, 2026 — vibehacker.com
- AgentTM repository, README, feature table, and license — github.com
- AgentTM releases, versions 0.3.3 and 0.3.4, November 3, 2026 — github.com
- Show HN thread, item 50334503, November 2, 2026, via the Hacker News Algolia API — hn.algolia.com
- Codex CLI worktrees, DevelopersDigest, September 10, 2026 — developersdigest.tech
- Codex non-interactive mode, codex exec — codex-docs.com
- Codex exec behaviour, checked against Codex CLI 0.157.1 and 0.162.1 — developertoolkit.ai
- AgentsRoom Git worktree manager — agentsroom.dev
- Not Codex control plane for coding agents — notcodex.bpro.dev
- Clawdline, Show HN coverage, October 31, 2026 — wpnews.pro
- SQLite definition — sqlite.org
- Git worktree documentation — git-scm.com
Frequently Asked Questions
What is AgentTM, in one sentence?
AgentTM is a local Go command-line tool that records Codex runs into a SQLite log with before-and-after workspace snapshots, so you can browse the history, diff checkpoints, and fork any checkpoint into a separate Git worktree.
Does AgentTM replace Git?
No. Git records the states you choose to commit, while AgentTM records what happened inside a Codex run between commits. The README says AgentTM complements Git, and it does not replace commits, branches, or code review.
Does AgentTM record interactive Codex sessions?
Not with the command-line tool at launch. Version 0.1 captured only non-interactive Codex runs it launched, and interactive chat, model discovery, and approval prompts are desktop-preview features. Use the non-interactive wrap command for recording until CLI support arrives.
Is AgentTM open source?
No. The repository is public, but AgentTM is offered under a proprietary license, not an open-source license. Personal and internal business use of official binaries is permitted, while source reuse, redistribution, resale, and hosted services need separate written permission.
Can AgentTM leak secrets from my snapshots?
Yes, if secrets sit in files the agent touches. Snapshot file bytes are not content-redacted, so embedded secrets are stored in the recording, and filename exclusions are no guarantee that every embedded secret is excluded. Review a recording before you share it, and keep secrets out of files your agent runs touch.
