Noctrace Documentation — Claude Code Debugger & Session Log Viewer

What is Noctrace?

Noctrace is a free, open-source, local-only observability dashboard and Claude Code debugger for AI coding agent workflows — supporting Claude Code, OpenAI Codex CLI, and GitHub Copilot Chat. It reads session logs from each provider and renders them as an interactive waterfall timeline in your browser — no cloud dependency, no telemetry, no database, and zero configuration required. The interface is modeled after Chrome DevTools' Network tab: every tool call is a horizontal timing bar on a shared time axis.

Noctrace runs as a single Node.js process. It starts a local Express 5 server on port 4117, serves a React SPA, and opens a WebSocket connection so the waterfall updates in real time as your session progresses. All data stays on your machine. Install with npm install -g noctrace or try immediately with npx noctrace.

Claude Code Session Log Analysis

Noctrace is the primary Claude Code log viewer for JSONL session files written by Anthropic's Claude Code CLI. Claude Code writes session logs to ~/.claude/projects/<project-slug>/<session-id>.jsonl. Sub-agent session logs are stored at ~/.claude/projects/<project-slug>/<session-id>/subagents/agent-<agent-id>.jsonl.

The Noctrace JSONL parser reads these files incrementally using byte-offset tracking, so only new bytes are parsed on each file change. It supports all Claude Code record types: user, assistant, system, compact_boundary, and tool use/result records. Tool call types supported include Read, Write, Edit, Bash, Task/Agent (sub-agent spawn), Grep, LS, MCP calls, and hook lifecycle events (PostToolUse, SubagentStart, SubagentStop).

Sub-agent rows are parsed separately and attached as children of their parent agent row, enabling full visualization of the Claude Code agent delegation tree. Agent type labels (Explore, core:deep-researcher, senior-software-engineer, etc.) are parsed from the subagent_type field in the JSONL log.

Installation — npm install noctrace

Option 1 — Try without installing (recommended for first use): run npx noctrace in your terminal. This downloads noctrace temporarily and starts the dashboard. Requires Node.js 20 LTS or later and at least one AI coding tool with sessions on disk.

Option 2 — Install globally:

npm install -g noctrace

Then run noctrace --enable to register Noctrace as an MCP server in Claude Code. After this, the dashboard opens automatically whenever a new Claude Code session starts. To stop auto-starting, run noctrace --disable.

Option 3 — Real-time hook events (optional): run noctrace --install-hooks to enable real-time hook streaming (SubagentStart/Stop, PostToolUse, Claude Code context compaction events). Remove with noctrace --uninstall-hooks.

Docker: to trace Claude Code sessions running inside a Docker container, run npx noctrace --docker <container>. Noctrace injects a lightweight watcher and streams JSONL events back to your host. Zero container setup required.

Quick start

Before starting Noctrace, make sure at least one AI coding tool has been used so that session logs exist on disk. Then run npx noctrace. A browser tab opens at http://localhost:4117. Select a project from the left sidebar and pick a session — the waterfall renders immediately. For live updates, keep both your AI coding tool and Noctrace running simultaneously.

If port 4117 is taken, Noctrace tries the next available port automatically and prints the URL it bound to. To pin a port, use the PORT environment variable: PORT=3001 npx noctrace.

Codex CLI Session Monitoring

Noctrace is also a Codex CLI session viewer. It reads OpenAI Codex CLI session logs from ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl. The Codex provider pairs FunctionCall and FunctionCallOutput records by call_id and folds separate TokenCount events into turns, producing waterfall rows with the same structure as Claude Code sessions. Codex sessions show an orange codex badge in the session picker. The CODEX_HOME environment variable is honored for non-standard Codex installations.

GitHub Copilot Chat Visualization

Noctrace v1.5 added a GitHub Copilot Chat provider. It reads VS Code Copilot Chat session files from ~/Library/Application Support/Code/User/workspaceStorage/ (macOS) or the equivalent path on Linux and Windows. The Copilot parser maps 20 internal Copilot tool IDs to human-readable names (Read, Write, Edit, Bash, etc.) so they appear consistently alongside Claude Code and Codex tool calls. Copilot sessions show a blue copilot badge. Token counts and cost estimates are not available for Copilot Chat sessions since Copilot Chat does not expose token usage data.

New in v1.6.0

Per-turn token attribution: stacked bar chart in the detail panel showing where tokens went each turn — thinking, tool I/O, system prompt, user text, cache reads. Estimates based on content block sizes.
Cache hit rate metric: cacheReadTokens extracted from JSONL cache_read_input_tokens. Toolbar shows a cache hit percentage pill (yellow when >= 50%). Yellow dot on cached rows. Works for Claude Code and Codex; Copilot shows nothing (no cache data exposed).
Cross-session full-text search: "Search all..." input in the toolbar (or Cmd+Shift+F). GET /api/search?q= scans all sessions from all providers (last 30 days). Results flyout with click-to-navigate jumps to the session and highlights the matching row.
Tool-specific detail renderers: Edit/Write show inline diffs with red/green background. Read shows syntax-highlighted code with line numbers. Bash shows terminal-styled command + output with error lines tinted red. Glob/Grep show file lists with icons. Unknown tools fall back to the existing plain text/markdown rendering.

Context Health Monitoring and Context Rot Detection

Noctrace computes a real-time A–F context health grade for every Claude Code session. The grade appears as a ring badge in the toolbar. Click it to expand the signal breakdown panel with per-signal sub-scores and actionable recommendations.

The five weighted signals driving the context health score are: context fill (40%) — how full the context window is relative to the model's size; Claude Code context compaction events (25%) — each compact_boundary is a lossy memory operation that permanently discards context; re-reads (15%) — duplicate Read calls on the same file path indicate retrieval failures caused by context degradation; error rate acceleration (10%) — comparing the error rate in the second half of the session to the first half; and tool efficiency (10%) — whether the proportion of Write and Edit calls is declining, which signals the agent is stuck in a loop rather than making progress.

Context rot is the progressive degradation of Claude Code session quality as the context window fills. Noctrace makes it visible through red row tinting on high-fill tool calls, a heat strip along the left edge of each row, compaction boundary lines, re-read indicators, and a drift rate metric (tokens per minute, computed via three-window linear regression with labels: stable, rising, accelerating, critical).

Context health grades: A (85–100, healthy), B (70–84, good), C (55–69, consider running /compact), D (40–54, degraded — run /compact now), F (0–39, critical — /clear recommended).

OpenTelemetry Export for Claude Code Sessions

Noctrace exports Claude Code session data as OpenTelemetry (OTel) traces via GET /api/session/:slug/:id/otlp. The response is a zero-dependency OTLP JSON trace format compatible with Grafana, Jaeger, and Datadog. Each tool call becomes a span with attributes for tool type, duration, token counts, context fill percentage, and cost. Sub-agent hierarchies are represented as parent-child span relationships. This makes Noctrace a bridge between Claude Code session logs and professional observability stacks.

Waterfall View — AI Agent Tool Call Visualization

The waterfall renders every tool call as a horizontal bar on a shared time axis. Columns show row number, tool name and target (file path, command, agent name), tool type badge (Read, Write, Edit, Bash, Task, Grep, MCP), wall-clock duration, cumulative token count, estimated USD cost, context fill percentage, and a timing bar whose position and width map to start time and duration.

Agent hierarchy: when Claude Code spawns a sub-agent using the Task or Agent tool, it appears as a collapsible row group. Click the chevron to expand and see the agent's child tool calls nested inside. Each sub-agent row shows the agent's named type as a blue badge chip (for example: Explore, core:deep-researcher, senior-software-engineer).

Filtering: use the filter bar to search by tool name, file path, or text. Special keywords include error (show only failed calls), running (show only in-progress calls), and agent (show only agent rows). Structured syntax: type:bash, >5s, <100ms, tokens:>1k, success. Multiple type: filters are OR-ed; others AND.

Token tracking and cost estimation

Every waterfall row shows the cumulative input and output token count at that point in the session. The detail panel (click any row) shows the in/out token split, the context fill percentage at execution time, and the estimated USD cost for that specific call. The session total estimated cost appears in the toolbar. Pricing uses Claude's public rates with automatic per-model detection (Sonnet, Opus, Haiku).

Expensive calls consuming more than 5,000 tokens are highlighted in yellow in the Tokens column. The Stats flyout (toolbar bar-chart icon) shows P50, P95, and Max latency per tool type, and flags calls exceeding the slow-call threshold (default 5,000ms) with a clock icon on the row.

Efficiency Tips and Security Analysis

The efficiency engine detects eight waste patterns per Claude Code session: re-reads (reading the same file multiple times), fan-out (spawning too many sub-agents for simple tasks), correction loops (repeated fix-test-fix cycles), repeated identical commands, token spikes (individual calls with abnormally high token counts), high context fill (session running near capacity), no delegation (long sessions with no sub-agent spawns), and post-compaction re-reads (reading files that were in context before a compaction event). When patterns are found, an amber lightbulb appears in the toolbar. Click it for the tips panel.

The security engine scans thirteen patterns: hardcoded secrets or API keys appearing in tool call inputs or outputs, dangerous shell commands (rm -rf, chmod 777, curl | bash), potential exfiltration (writing sensitive data to public locations), prompt injection attempts in tool outputs, and others. A red shield badge in the toolbar indicates findings. All analysis runs locally in the browser — no data leaves your machine.

CLI options reference

noctrace — start server and open dashboard
noctrace --enable — register with Claude Code for auto-start on every session
noctrace --disable — unregister from Claude Code
noctrace --install-hooks — enable real-time hook events
noctrace --uninstall-hooks — remove hook event listeners
noctrace --docker <container> — stream sessions from a running Docker container
PORT=3001 noctrace — run on a custom port
CLAUDE_HOME=/path noctrace — use a custom Claude config directory

Troubleshooting

"No projects found" on startup: At least one AI coding tool must have been used. Check that ~/.claude/projects/ (Claude Code), ~/.codex/sessions/ (Codex CLI), or VS Code workspaceStorage (Copilot Chat) exists and contains session files.

Waterfall shows no rows: select a session from the sidebar. Sessions containing only system records with no tool calls will render a blank waterfall. Choose a session with coding activity.

Real-time updates not appearing: for live updates, both Claude Code and Noctrace must be running simultaneously. If the session ended before Noctrace started, the completed session renders statically.

Browser doesn't open automatically: some environments (WSL, SSH sessions, headless Linux) cannot open browsers. Noctrace still starts the server — navigate to http://localhost:4117 manually.

Supported providers

Noctrace reads sessions from three AI coding tools automatically. All appear in the same session picker with provider badges.

Claude Code — reads ~/.claude/projects/ JSONL session logs. Full context health scoring, token cost estimation, and all waterfall features.
OpenAI Codex CLI — reads ~/.codex/sessions/ rollout JSONL files. Orange codex badge. Full tool-call granularity with per-turn token accounting.
GitHub Copilot Chat (new in v1.5) — reads VS Code workspaceStorage JSON session files at ~/Library/Application Support/Code/User/workspaceStorage/. Blue copilot badge. 20 internal tool IDs mapped to familiar names (Read, Write, Edit, Bash, etc.). Token tracking not available — Copilot Chat does not expose token counts, so the health grade and cost columns are hidden for Copilot sessions.

System requirements

Node.js 20 LTS or later. macOS, Linux, or Windows (WSL recommended). Any modern browser. At least one of: Claude Code, Codex CLI, or GitHub Copilot Chat. No API keys, no accounts, no cloud.

GitHub repository | npm package — install noctrace | Back to noctrace home — Claude Code observability | Changelog