Noctrace — Claude Code Observability & AI Agent DevTools
AI Coding Agent Observability for Claude Code, Codex CLI, and GitHub Copilot
Noctrace is a free, open-source, local-only observability dashboard for AI coding agent workflows — supporting Claude Code, OpenAI Codex CLI, and GitHub Copilot Chat. It reads session logs and renders them as an interactive waterfall timeline in your browser — with no cloud dependency, no telemetry, no database, and zero configuration required. Install it with a single command: npx noctrace.
The interface is modeled after Chrome DevTools' Network tab. Every tool call — Read, Write, Edit, Bash, Agent, MCP — appears as a horizontal timing bar on a shared time axis. You can see exactly what your AI agent did, how long each step took, how many tokens it consumed, and what it cost in estimated USD. Sub-agents spawned by Claude Code appear as collapsible row groups, letting you drill into nested tool calls across the full agent delegation tree.
What is context rot and why does it matter?
Context rot is the progressive degradation of Claude Code session quality that happens as the context window fills. When context fill exceeds roughly 80%, Claude begins to lose access to early instructions, prior tool outputs, and reasoning chains. The practical result is repeated work, contradictory edits, and an increasing error rate — a session that starts strong but quietly goes off the rails.
Noctrace makes context rot visible. Waterfall rows are tinted red when they executed above 80% context fill. A heat strip along the left edge of each row transitions from green to yellow to red as the window fills. Compaction boundary lines mark where Claude Code triggered automatic context compaction — each one is a lossy memory operation. A drift rate metric (tokens per minute, computed via three-window linear regression) shows how fast the context is growing before health scores catch up. Together, these signals let you see a session degrading in real time and decide when to compact or restart.
Key capabilities
- Waterfall timeline: every tool call and agent spawn on a shared time axis with zoom (1–50x) and click-drag pan. Identical in concept to Chrome DevTools Network tab.
- Context health scoring: an A–F grade computed from five weighted signals — context fill (40%), compaction events (25%), file re-reads (15%), error rate acceleration (10%), and tool efficiency trends (10%). The animated ring badge fills in real time as the session progresses.
- Sub-agent visibility: collapsible agent groups with nested tool call rows. Agent type labels show the named type (Explore, core:deep-researcher, senior-software-engineer, etc.) as a blue badge chip next to each agent row.
- Token cost estimation: estimated USD cost appears on every waterfall row and as a session total in the toolbar. Pricing uses Claude's public rates with automatic per-model detection (Sonnet, Opus, Haiku).
- Context rot detection: red row tinting above 80% fill, a heat strip along the left edge, compaction boundary markers, re-read indicators, and a drift rate metric that shows tokens-per-minute growth.
- Efficiency tips: 8 waste patterns detected per session — re-reads, fan-out, correction loops, repeated commands, token spikes, high context fill, lack of delegation, and post-compaction re-reads. Flagged with an amber lightbulb indicator in the toolbar.
- Security tips: 13 security patterns scanned, including secrets in tool calls, dangerous commands, exfiltration attempts, and prompt injection. Flagged with a red shield indicator.
- Loop detection: three or more consecutive identical tool calls (same tool type and same input) automatically trigger a warning tip.
- Advanced filtering: structured syntax alongside text search —
type:bash, >5s, <100ms, tokens:>1k, error, running. Structured filters are AND-ed; multiple type: filters are OR-ed.
- Session comparison: split-screen view comparing two sessions side by side, with health grades, summary metric deltas, tool mix proportion bars, and context fill trajectory sparklines.
- Real-time streaming: WebSocket byte-offset incremental parsing means only new bytes are read on each file change. Auto-reconnect handles server restarts.
- Docker support:
npx noctrace --docker <container> attaches to a running Docker container and streams its Claude Code session logs to your host. Zero container setup — any image with curl or wget works.
- OTel export: sessions are exportable as OpenTelemetry traces for Grafana, Jaeger, or Datadog via
GET /api/session/:slug/:id/otlp.
- MCP session registry: sessions self-register on start and unregister on exit. The dashboard shows only active sessions with a live count indicator.
- Per-tool latency stats: P50, P95, and Max latency breakdown per tool type in the Stats flyout. Calls exceeding the slow-call threshold (default 5000ms) are flagged with a clock icon on the row.
- Context Startup flyout: shows which CLAUDE.md and instruction files loaded at session start with estimated token counts, so you can see what filled your context before the first tool call.
- Hook lifecycle rows: PostToolUse, SubagentStart, and SubagentStop events from Claude Code hooks render as distinct teal timeline rows.
- Resizable Name column: drag the column header edge to resize, stored in state across sessions.
- GitHub Copilot Chat provider (new in v1.5): sessions from VS Code Copilot Chat appear automatically alongside Claude Code and Codex sessions. 20 internal tool IDs are mapped to familiar names (Read, Write, Edit, Bash, etc.). Copilot projects show a blue "copilot" badge in the session picker.
- Multi-provider session picker (new in v1.4+): Claude Code, OpenAI Codex CLI, and GitHub Copilot Chat sessions all appear in one unified view with per-provider badges. Zero configuration — each provider auto-detects its session directory.
- Per-turn token attribution (new in v1.6): stacked bar chart in the detail panel showing where tokens went each turn — thinking, tool I/O, system prompt, user text, cache reads.
- Cache hit rate metric (new in v1.6): toolbar shows cache hit percentage pill (yellow when >= 50%). Yellow dot on cached rows. Extracted from JSONL
cache_read_input_tokens.
- Cross-session full-text search (new in v1.6): Cmd+Shift+F or "Search all..." in the toolbar. Scans all sessions from all providers (last 30 days). Click results to navigate directly to the matching row.
- Tool-specific detail renderers (new in v1.6): Edit/Write show inline diffs, Read shows syntax-highlighted code with line numbers, Bash shows terminal-styled output with error lines tinted red, Glob/Grep show file lists with icons.
How to install Noctrace
Option 1 — Try without installing (recommended for first use):
npx noctrace
This downloads noctrace temporarily, starts a local server on port 4117, and opens the dashboard in your browser. Nothing is written to disk after you close it. Requires Node.js 20 LTS or later and at least one AI coding tool (Claude Code, Codex CLI, or Copilot Chat) with at least one session logged to disk.
Option 2 — Install globally:
npm install -g noctrace
After installing, run noctrace --enable to register Noctrace as an MCP server in Claude Code. This causes the dashboard to open automatically every time a new Claude Code session starts. To stop auto-starting, run noctrace --disable.
Option 3 — Real-time hook events (optional):
By default Noctrace reads session logs passively with no hooks required. For real-time event streaming (SubagentStart/Stop, PostToolUse, compaction events pushed directly to the dashboard), run noctrace --install-hooks. Remove hooks with noctrace --uninstall-hooks.
How Noctrace works
Noctrace is a single Node.js process. It runs a local Express 5 server on port 4117 that serves a React SPA, exposes a REST API, and upgrades WebSocket connections. The file watcher (chokidar) monitors ~/.claude/projects/ for new or modified JSONL files. When a file changes, the server reads only the new bytes using byte-offset incremental parsing and pushes the parsed rows to the browser over WebSocket. No data ever leaves the machine.
Session logs are JSONL files written by Claude Code at ~/.claude/projects/<project-slug>/<session-id>.jsonl. Sub-agent logs live at ~/.claude/projects/<project-slug>/<session-id>/subagents/agent-<agent-id>.jsonl. Noctrace parses both formats and links sub-agent rows to their parent agent rows. The server is stateless — all persistent state comes from the JSONL files on disk.
The waterfall component is built with positioned div elements and virtual scrolling, rendering only visible rows for sessions with 200+ tool calls. The health scorer runs a weighted average of five signals on every WebSocket push. All colors use CSS custom properties from a single theme file (Catppuccin Mocha).
System requirements
- Node.js 20 LTS or later
- macOS, Linux, or Windows (WSL recommended on Windows)
- Any modern browser (Chrome, Firefox, Safari, Edge)
- At least one of: Claude Code (sessions in
~/.claude/projects/), Codex CLI (sessions in ~/.codex/sessions/), or GitHub Copilot Chat (VS Code workspaceStorage)
Supported AI Coding Agent Providers
Noctrace auto-detects sessions from three AI coding tools. All appear in one unified session picker with per-provider badges. Zero configuration required for any provider.
- Claude Code (Anthropic): reads JSONL session logs from
~/.claude/projects/. Full Claude Code observability — context health scoring, token cost estimation, compaction tracking, sub-agent waterfall, tool call visualization, and OpenTelemetry export. This is the primary Claude Code session viewer and Claude Code log viewer.
- Codex CLI (OpenAI): reads
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl files. Codex CLI observability with per-turn token accounting and full tool-call granularity. Orange codex badge in the session picker. Honors the CODEX_HOME environment variable.
- GitHub Copilot Chat (new in v1.5): reads VS Code workspaceStorage session files from
~/Library/Application Support/Code/User/workspaceStorage/. Copilot agent monitoring with 20 internal tool IDs mapped to familiar names (Read, Write, Edit, Bash, etc.). Blue copilot badge. Token counts are not available since Copilot Chat does not expose them.
License and links
Noctrace is free and open source under the MIT license.