GitHub - DevonPeroutky/agent-profiler

npx @ghostship/agent-profiler
or npm i -g @ghostship/agent-profiler

agent-profiler is a local, open-source trace viewer for agent harness sessions.

Support for Codex, Claude Code and an adapter can be added for any harness

I wrote this because I had a hard time investigating why certain Claude Code subagent/skills were performing poorly. Regular old, boring software has had profilers and debuggers for decades. When a request is slow or a function blows up memory, you have tools that tell you exactly where. In the new world order of agentic development, poor performance is usually due to context bloat - either too many unnecessary tokens or missing relevant ones. I wrote this to help answer questions like:

• Which tool calls ballooned the context window, and on which turn?
• What context was the subagent/skill passed when it was spawned?
• What steps were repeated every session that could be lifted into a skill/documentation or cached lookup?

agent-profiler is the tool for just that. It requires zero setup (just node), is fully local, and open-source and can support any agent harness with a local transcript format.

"Why not just use Langfuse/LangSmith/Arize/etc?"

Those are great for tracing LLM API calls inside a deployed application, however coding agent sessions on your laptop have completely different shapes. They're enormously long, most of the "work" is local tool use (Bash, Read, Edit) rather than model calls, and the harness writes a pile of structure — turns, subagents, prompts, per-turn token splits, slash commands that a generic LLM-observability tool has no concept of and drops on the floor.

agent-profiler is purpose-built for profiling and debugging local coding agents and only that. Single binary, no SDK to wire in, no account, no collector, nothing leaves your machine.

Quickstart

Installing and running agent-profiler

agent-profiler runs entirely on your computer. It reads local harness transcripts on demand, serves a local UI, and does not upload traces, prompts, tool output, or usage data anywhere.

Requirements:

• Node.js 20+
• npm 10+
• Local transcript data from Codex or Claude Code

Run with npx:

npx @ghostship/agent-profiler

Or install globally:

npm install -g @ghostship/agent-profiler
agent-profiler

The app opens http://localhost:5173/ by default.

Using local harness data

agent-profiler is deliberately local-first:

• No hooks or background collector.
• No hosted service or telemetry.
• No data leaves your computer.
• The server only reads local transcript files when the UI requests them.

The Claude Code adapter reads session transcripts from ~/.claude/projects/*/. Codex support follows the same adapter model: discover local session files, parse them into the shared trace shape, and render them in the same waterfall UI.

CLI options

agent-profiler [options]

  -p, --port <n>     Port to listen on (0 = pick a free one). Default 5173
      --no-open      Do not open a browser tab
  -v, --verbose      Log every HTTP request to stderr
  -V, --version      Print version and exit
  -h, --help         Show this message

Developing locally

git clone https://github.com/devonperoutky/agent-profiler
cd agent-profiler
npm install
npm run dev

Common commands:

npm run build        # builds ui/dist/
npm run test         # node:test unit + smoke tests
npm run typecheck    # tsc --noEmit
npm run lint         # biome check

Docs

• Architecture
• Contributing
• Documentation Stub: Adding an adapter for a new agent harness

This repository is licensed under the Apache-2.0 License.