agent-trace is an open-source command-line transcript utility created by ertygiq. It is designed to inspect, parse, and export execution logs from AI coding agents and harness sessions into uniform, plain-text streams. The tool operates without HTML rendering or rich terminal user interfaces, focusing purely on raw, legible text output. In daily developer workflows, agent-trace reads session transcript files generated by supported agent harnesses (such as Cursor project session logs). It unwraps structured metadata—including user queries, tool execution calls, thinking traces, and timestamps—and prints them sequentially to standard output. Because the tool operates on standard I/O, developers can pipe logs directly into command-line utilities like grep, less, or head, or pass complete execution context to another LLM for code review and auditing. What distinguishes agent-trace from terminal-based interactive agents is its focus as an observability and evaluation harness layer. Instead of generating code or managing interactive loops, it normalizes disparate agent session formats across environments without external runtime overhead. Implemented in Python using only the standard library, it avoids dependency conflicts and includes defensive stream handling such as BrokenPipeError suppression. agent-trace is free and open-source software licensed under the MIT License. It is lightweight and can be installed directly via standard Python tooling or uv.
Pure plain-text output — Formats multi-turn agent sessions directly to stdout without HTML tags, TUI controls, or ANSI clutter. - Multi-harness log parsing — Reads and decodes session formats from agent environments, including Cursor project transcripts. - Zero external dependencies — Implemented strictly in Python using standard library modules for minimal footprint and easy installation. - Selective block filtering — Supports granular inspection flags such as isolating bash outputs, tool invocations, or thinking blocks. - Unix pipeline integration — Designed to pipe seamlessly into downstream CLI tools and handles early-exit stream closures cleanly. - Day boundary markers — Automatically displays date headers at day boundaries across long-running or multi-day agent transcript logs.
Use cases
Use Case: Debugging Agent Run Failures A developer can run agent-trace against a failed agent session to inspect exact tool calls, bash execution logs, and model reasoning steps without navigating nested IDE or JSON files.
Use Case: Multi-Agent Evaluation and Review An engineer can pipe clean agent execution transcripts directly into secondary LLMs or automated evaluation scripts to assess code generation quality, safety compliance, or tool use correctness.
Use Case: Audit Logging and Knowledge Sharing Teams can export plain-text transcripts of complex coding agent sessions to attach to pull requests, issue trackers, or internal documentation for transparent post-mortems.
Who it is for
agent-trace is intended for developers, AI engineers, and evaluators who build, debug, or benchmark AI coding agents across various harnesses. It is particularly suitable for developers who prefer minimal command-line workflows and Unix piping over heavy graphical dashboards. It is not intended for users seeking an interactive coding assistant itself.
Install guide
Installation Install agent-trace via uv or standard Python pip: bash # Install via uv uv tool install git+https://github.com/ertygiq/agent-trace.git # Or install directly with pip pip install git+https://github.com/ertygiq/agent-trace.git
First Run agent-trace inspects local transcript files and requires no external API keys or remote configuration. Verify the installation by checking available commands and options: bash agent-trace --help
Example Session Inspect the latest agent transcript from a project and pipe it through less: bash # View transcript for a session agent-trace # Pipe clean text transcript into another CLI tool or secondary LLM agent-trace | grep -E "(tool_use|error)"
Toad — Toad is an open-source terminal user interface (TUI) coding agent harness developed by Batrachian AI and spearheaded by Will McGugan…
Codel — Codel is an open-source, self-hosted autonomous software engineering agent created by semanser. It combines an execution backend, an interactive web…
Agent Manager — Agent Manager is an open-source Go-based CLI utility and orchestration harness created by Kevin Elliott. It is designed to catalog,…
agent-browser — agent-browser is an open-source browser automation harness and agent tool developed by Vercel Labs. It provides autonomous AI agents with…
Amazon Q Developer CLI — Amazon Q Developer CLI is an open-source command-line coding assistant developed by Amazon Web Services (AWS). Built primarily in Rust,…
SWE-agent — SWE-agent is an open-source autonomous software engineering agent harness built and maintained by researchers from Princeton University and Stanford University.…