Agent Trace

A sample session. On your computer it shows your own sessions.

Install

The easiest way is to ask your agent to install it. Pick your agent, copy the prompt, and paste it in.

Paste this into Claude Code:

Install Agent Trace for me by running this in a terminal:

curl -fsSL https://www.davidfromkansas.com/viz/install.sh | bash -s -- claude

Then tell me in a sentence or two what it changed.

Start a new Claude Code session. The viewer opens in your browser at http://127.0.0.1:4877 and fills in as Claude works.

Or run it yourself

curl -fsSL https://www.davidfromkansas.com/viz/install.sh | bash -s -- claude

Paste this into Codex:

Install Agent Trace for me by running this in a terminal:

curl -fsSL https://www.davidfromkansas.com/viz/install.sh | bash -s -- codex

Then tell me in a sentence or two what it changed.

Quit and reopen Codex. Codex asks you to approve new hooks before they run, so type /hooks and trust the Agent Trace ones.
Start a task. The viewer opens in your browser at http://127.0.0.1:4877 and fills in as Codex works.

Or run it yourself

curl -fsSL https://www.davidfromkansas.com/viz/install.sh | bash -s -- codex

Use both? Replace claude or codex with all. Needs Node.js 18 or newer, on macOS or Linux (on Windows, use WSL).

What it shows

Agent	Actions	Thinking
Claude Code	Every tool it uses, before and after, from its hooks	Claude's thinking text, from its session log
Codex	Every command and edit, before and after, from its hooks	Reasoning summaries, from its session log

Both agents save summaries of their reasoning, not every internal step, so that is what you see. Each entry also has a “Raw data” view showing exactly what was received.

Privacy

Everything stays on your computer. The viewer runs at a local address that only your computer can reach.
Common secrets, like API keys and tokens, are hidden before anything is shown or saved.
A copy of each day's entries is saved in ~/.agent-trace/logs, so you can look back later.
The hooks never change what your agent does. They only pass a copy of each event along.

What gets installed

A small program in ~/.agent-trace (four files, no other downloads).
Claude Code: hooks in ~/.claude/settings.json, plus a skill so you can ask Claude to open the viewer.
Codex: hooks in ~/.codex/hooks.json, and hooks turned on in ~/.codex/config.toml.
Your existing settings are kept, and a backup of each file is saved next to it the first time.

Everyday commands

Open the viewer	`node ~/.agent-trace/agent-trace.js open`
Check it is running	`node ~/.agent-trace/agent-trace.js status`
Stop it	`node ~/.agent-trace/agent-trace.js stop`
Remove it	`node ~/.agent-trace/agent-trace.js uninstall`

It starts on its own when a session starts, and stops itself after two quiet hours.

Source

Four short files you can read before installing: server.js, hook.js, agent-trace.js, viewer.html, and the installer.