ai-agent-trace

Structured logger and CLI timeline viewer for AI agent traces. Logs LLM calls, tool calls, and reasoning steps to JSONL files, then renders them as a color timeline in your terminal.

No external dependencies — just Node built-ins and raw ANSI codes.

Install

npm install ai-agent-trace
# or globally for the CLI
npm install -g ai-agent-trace

Logger API

import { AgentTracer } from "ai-agent-trace";

const tracer = new AgentTracer({
  outputFile: "trace.jsonl",
  sessionId: "run-001", // optional — auto-generated UUID if omitted
});

// Group events into a step
tracer.startStep("gather context");

// Log an LLM call
tracer.logLLMCall({
  prompt: "Summarize this document...",
  response: "The document covers...",
  model: "claude-sonnet-4-6",
  inputTokens: 1200,
  outputTokens: 340,
  durationMs: 1850,
});

// Log a tool call
tracer.logToolCall({
  toolName: "bash",
  input: { command: "ls -la" },
  output: "total 32\n-rw-r--r-- ...",
  durationMs: 45,
  // error: "ENOENT"  // optional — highlight red in viewer
});

// Log agent reasoning / thinking
tracer.logReasoning({
  text: "I need to read the file before editing it.",
});

tracer.endStep();

Integration example with Anthropic SDK

import Anthropic from "@anthropic-ai/sdk";
import { AgentTracer } from "ai-agent-trace";

const client = new Anthropic();
const tracer = new AgentTracer({ outputFile: "trace.jsonl" });

tracer.startStep("user request");

const start = Date.now();
const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What files are in the current directory?" }],
});

const responseText = message.content
  .filter((b) => b.type === "text")
  .map((b) => b.text)
  .join("");

tracer.logLLMCall({
  prompt: "What files are in the current directory?",
  response: responseText,
  model: message.model,
  inputTokens: message.usage.input_tokens,
  outputTokens: message.usage.output_tokens,
  durationMs: Date.now() - start,
});

tracer.endStep();

CLI

agent-trace view <file.jsonl> [options]

Options

| Flag | Description | | ------- | ----------- | | --full | Show complete prompt/response without truncation | | --filter <type> | Show only: llm_call | tool_call | reasoning | step_start | step_end | | --session <id> | Filter to a specific session ID |

Example output

┌─ STEP: gather context ──────────────────────────────────
12:00:01 ◆ LLM claude-sonnet-4-6  1.85s  tokens: 1200↑ 340↓
  prompt: Summarize this document...
  response: The document covers...
12:00:02 ⚙ TOOL bash  45ms  ✓
  input: {"command":"ls -la"}
  output: "total 32\n-rw-r--r-- ..."
12:00:02 ◎ think I need to read the file before editing it.
└─ end gather context  1.90s

════════════════════════════════════════════════════════════
SUMMARY
  sessions:   run-001
  llm calls:  1
  tool calls: 1
  errors:     0
  tokens in:  1200
  tokens out: 340
  duration:   1.90s
════════════════════════════════════════════════════════════

JSONL Schema

Each line is one JSON event:

interface BaseEvent {
  id: string;          // UUID
  timestamp: string;   // ISO 8601
  sessionId: string;
  type: "llm_call" | "tool_call" | "reasoning" | "step_start" | "step_end";
  payload: LLMCallPayload | ToolCallPayload | ReasoningPayload | StepStartPayload | StepEndPayload;
}

See src/types.ts for full type definitions.

Development

npm run build       # compile with tsup
npm test            # run vitest suite
npm run typecheck   # tsc --noEmit

License

MIT