https://github.com/user-attachments/assets/2a7f474b-ba02-4f01-85b6-4652edecaf76

Don't let agent work become cognitive debt

Cognitive debt may be more dangerous than technical debt in the age of AI.

Your agent finishes an overnight run. You're ready to ship, but its reasoning, tool calls, edits, and outputs are scattered across thousands of records.

Andrej Karpathy argues that we'll spend more time understanding model outputs. Yet under pressure to ship, we have limited time to understand what our agents did and the code they leave behind:

• What approaches did the agent explore?
• Why did it abandon one direction?
• What evidence supports the final version?

Those unanswered questions accumulate as cognitive debt, making the project harder to maintain.

That's why we built TraceVista. Start with the big picture, explore the details, and check the evidence wherever something doesn't add up.

• 🗺️ See the decision map. Follow approaches, failures, pivots, and version history.
• 🔍 Unfold the details. Move from system states to work phases, actions, and original records—then step back without losing your place.
• 💬 Ask questions in context. Ask about a node and follow citations back to the evidence.
• 📄 Inspect the originals. Read the source records alongside the summaries.

Understanding an agent's work shouldn't depend on trusting another AI-generated summary.

TraceVista is open source. Explore a real session, bring your own, and tell us what's still hard to understand.

Explore real agent runs

Open an example and follow its decisions from the overview down to the original records. No sign-up or model key needed.

Example	Inside the run
Pi Agent · Kernel Optimization	DeepSeek Flash optimizes vLLM's multi-LoRA kernels on an A100. Follow grouped Triton kernels, direct launch, an identity-cache regression, and a return to an earlier candidate.
Claude Code · Post Training	Fable 5 Max trains Qwen3-4B for AIME 2025 on an H100. Explore fine-tuning, checkpoint averaging, evaluation, and the choice of the final model.
Codex · Model Serving	GPT-5.5 High tunes a Mistral-7B server on an H100. Follow scheduler experiments, startup recovery, and a rejected sampling change.
OpenHands · Bug Fixing	Qwen3-Coder investigates a Kafka connection retry loop. Trace source edits, revised tests, and the gap between local checks and the benchmark outcome.
Tongyi DeepResearch · Literature Research	A teacher trajectory from LiteResearcher SFT data compares two journal articles to identify the authors’ shared institution. Follow an empty PDF, a switch to journal author blocks, and a broader search after zero results.
Codex · Garden Animation	GPT-6 Astra turns a ruined hall into a Three.js garden of flowers that sway in the breeze. Follow screenshot checks, a recording timeout and a different save path, and the check of a ten-second MP4. A short excerpt of a longer session.

Bring your own trajectory

Two prompts. A complete map. Copy these into your coding agent.

1. Install the skill

Install skills/tracevista-skill from https://github.com/Superone77/TraceVista

Prefer your agent's plugin installer? See agent integrations
for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and Pi, or the
DeepSeek Harness plugin for conversion from a session.

2. Convert and open

Use tracevista-skill to convert [trajectory file or folder] into a complete .agent-state.json,
then open https://tracevista.pages.dev/ in my browser and import it.

Use $tracevista-skill in Codex or /tracevista-skill in Claude Code (/tracevista:tracevista-skill when installed as a plugin). The skill reads the logs, builds the state map and summaries, validates the export, and opens it in the viewer. You can ask the agent to refine the same map as you explore.

Its writing guide borrows from ASD-STE100: concrete verbs, consistent terms, and one idea per sentence. Explanations connect what the agent did, what the evidence showed, and what it chose next, with the technical conditions intact.

Works with Claude Code, Codex, and Pi session logs, InferenceBench traces, and SWE-rebench OpenHands trajectories. Combine main-agent and reviewer sessions in a single export.

The map, annotations, original records, and source attachments travel together in one .agent-state.json. Reopen it with Import trajectory, send it to a collaborator, or keep refining it with your agent. The conversion scripts use Python 3.10+ and its standard library.

Skill guide · Conversion workflow · Multiple agents

See the decision map

See what the agent tried, what it learned, and what happened next. Decision markers highlight discoveries, rejected ideas, pivots, and open questions. Decisions only folds routine steps so the important turns stand out.

Switch between Version tree and Execution order to follow both code ancestry and the sequence of work. Restored versions, abandoned candidates, and final selections stay visible. Measurements sit alongside the states they describe.

Press Play for a guided walkthrough. Story opens the current step while Map moves to the same place. Pause, move backward or forward, change the pace, or open the original evidence. Exit returns to your previous view.

Unfold the details

Explore the same run at four connected levels:

System states → Work phases → Actions → Raw records

Level	What you see
System states	How code and artifacts evolved, where results improved or regressed, and which version was selected.
Work phases	The approaches an agent explored, the alternatives it tried, and where it changed direction.
Actions	Explore, Plan, Edit, Execute, Verify, and Diagnose—with descriptions, outcomes, and who did the work.
Raw records	Original messages, recorded reasoning, tool inputs and outputs, and reviewer feedback.

Pan and zoom through the same canvas, or jump between levels with the toolbar. Select any card to open its path in Story and follow its evidence.

Ask questions in context

Select a node, open Chat, and ask about that step or the run around it:

Why did the agent abandon this approach? What evidence led to the next version?

Smart context first reads node summaries and an index of the raw records, then selects the records to read in full. Answers include clickable citations that take you back to the relevant nodes and events.

Ask how a decision happened to get a linked flow diagram, or compare attempts in a table. Click a claim or its evidence to locate it in Story and Map. The answer distinguishes recorded observations, interpretations, and open questions.

Connect Claude, OpenAI, Gemini, DeepSeek, Kimi, GLM, Qwen, MiniMax, OpenRouter, or your own compatible endpoint. Local models work through Ollama and LM Studio.

Inspect the originals

Expand a card in Story to read the original messages, code, tool calls, and results behind it. The records stay accessible alongside the summaries, so you can check an explanation against its sources and form your own view of what happened.

Bring the main agent and its reviewers into one map. Follow a review request through feedback, revisions, and another round of checks. Inspect skill use, knowledge reuse, TODOs, and measurements in Structure & evidence.

Designed for informed decisions

TraceVista lets you decide whether to trust an agent run, and which steps to check, without reading the whole log.

A single agent run can leave more text than anyone will read. The Pi Agent example ran for about 45 minutes and left 556 events and a session log of 2.26 million characters.

TraceVista turns the session log into a Story that starts with what the run delivered.

Then it gives one sentence per step. Segel and Heer (2010) call this a martini-glass structure. The author leads at first, through the narrow stem; then the reader explores the wide bowl, which here is the map, the raw records and Chat. ▶ Play steps through the story and moves the map with it.

TraceVista lets you unfold any sentence in place.

Click it and its work phases open underneath; click a phase for its actions, and an action for its raw records. Ted Nelson called this StretchText (1967). The rest of the story stays where it was, and the map switches to the same level.

TraceVista keeps the agent's own records word for word, so you can unfold summaries and check their sources.

The records are never translated. Summaries written by a model tend to sound more certain than their sources. In our checks of TextFold's paper summaries, one had turned potentially harmful into harmful. Because the records are always there to check, readers can match their trust to the evidence (Lee & See, 2004).

Run locally

Requires Node.js 24 or newer and pnpm 11 or newer. CI checks Node.js 24 and the latest Node.js release; .nvmrc provides a Node.js 24 default.

git clone --depth 1 --branch main https://github.com/Superone77/TraceVista.git
cd TraceVista
npm install -g pnpm@11
pnpm install --frozen-lockfile --ignore-scripts
pnpm dev

Open localhost:8875 and import a .agent-state.json. The default viewer, build, and tests work without the example library.

The shallow clone downloads the latest main snapshot. Both the standalone viewer and the website use the same viewer and UI source in this repository; the website build adds the separately versioned example data.

Command	Result
pnpm dev	Start the standalone viewer.
pnpm test	Check the viewer and conversion skill with small test fixtures.
pnpm build	Build the standalone viewer in dist/.
pnpm dev:site	Start the showcase with the pinned external example library.
pnpm test:examples	Check the full example exports and their source evidence.
pnpm build:site	Build the showcase in dist-site/.

Browse the six examples on the website. To run the showcase locally, place the separate TraceVista-examples repository beside this checkout or set TRACEVISTA_EXAMPLES_DIR. The viewer pins its data revision and asset hashes in examples.lock.json. See Example library setup and updates for checkout, validation, and release details. Both build outputs can be served by a static host.

Build on TraceVista

TraceVista pairs a React Flow viewer with a trajectory conversion skill. A shared JSON format connects them, so new agents and tasks can bring their own adapters, annotations, and examples.

• Viewer guide — Map, Story, playback, chat, and model connections.
• State graph format — states, actions, transitions, and evidence.
• Reading layer — summaries, turning points, and decision links.
• Contributing — set up, run the checks, add an adapter or example, and send a pull request.
• Security — report vulnerabilities and understand how API keys and chat data are handled.
• Code of conduct — community standards and reporting concerns.

Have an interesting trajectory or an idea for the viewer? Open an issue.

Citation

If you use TraceVista in your work, please cite:

@misc{yang2026tracevista,
  author = {Wanqi Yang and Xia Chen and Qilong Huang and Mei Xie and André Borrmann and Shiwei Liu},
  title = {{TraceVista}: Understanding Agent Trajectories through Hierarchical Exploration},
  year = {2026},
  howpublished = {\url{https://github.com/Superone77/TraceVista}}
}

License

TraceVista's code is released under the MIT License. The external example library keeps its source licenses, such as Apache-2.0 and CC-BY-4.0, and its own notices. See THIRD_PARTY_NOTICES.md for code attribution and the example notices location.

Acknowledgements

TraceVista builds on ideas and code from ThoughtDAG, including its semantic zoom, reading layer, and model connections. The viewer uses React Flow.

Thanks to the teams behind PostTrainBench, InferenceBench, SWE-rebench, and LiteResearcher for publishing agent trajectories. Sources and attribution.