Chronicle

Local-first AI agent execution tracer, multi-agent DAG visual replay, prompt regression & token cost engine.

Designed by Atlas Research Labs as a zero-telemetry, private alternative to LangSmith and Braintrust.

Architectural Principles

• 100% Local-First & Private: Prompts, system instructions, customer inputs, and completions never leave your machine. Stored locally in embedded append-only WAL format under .chronicle/traces.jsonl.
• Zero-Latency Tracing Proxy: Drop-in reverse proxy running on http://127.0.0.1:4318. Simply configure your OpenAI, Anthropic, Gemini, Groq, or Ollama SDK's baseURL to start recording instant traces with sub-millisecond proxy overhead.
• Hierarchical Multi-Agent DAGs: Track recursive agent loops, parent-child task branching, subagent delegations, and tool/function call execution steps with full call trees.
• Accurate Token Pricing Matrix: Built-in 2026 pricing tables calculating USD cost per call across OpenAI (GPT-4o, o1, o3-mini), Anthropic (Claude 3.5 Sonnet, Opus), Google (Gemini 1.5/2.0), Groq, DeepSeek, and local zero-cost models.
• Embedded OLED Studio: Pure OLED black local Web UI (http://127.0.0.1:5050) featuring real-time SSE trace streaming, message inspection, DAG execution graph, and prompt drift evaluation runner.
• Zero External Dependencies: Implemented entirely with Node.js standard runtime libraries (http, https, crypto, fs, perf_hooks). Package size under 100 KB, idle memory under 15 MB.

Installation

Global CLI installation via NPM:

npm install -g chronicle-trace

Or execute directly with npx:

npx chronicle-trace --help

Both binary aliases chronicle and chronicle-trace are registered.

SDK Integration

To trace any AI framework, agent loop, or application, point the standard baseURL to Chronicle:

OpenAI / TypeScript / Python

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'http://127.0.0.1:4318/v1' // Point to Chronicle Proxy
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Design a distributed consensus protocol' }]
});

Passing Custom Spans & Sessions

Use HTTP headers to group multi-step agent executions into hierarchical DAG trees:

• x-chronicle-trace-id: Unique identifier for the trace or step.
• x-chronicle-parent-id: ID of the calling parent agent (creates hierarchical DAG branch).
• x-chronicle-session-id: Group related agent conversations or user sessions.

CLI Reference

1. Transparent Tracing Proxy

Start the local reverse proxy:

chronicle proxy

Options:

• -p, --port <port>: Proxy port (default: 4318)
• -t, --target <url>: Upstream LLM provider (default: https://api.openai.com)
• -h, --host <host>: Host interface (default: 127.0.0.1)

2. Embedded OLED Web Studio

Launch both the proxy and web interface concurrently:

chronicle studio

Access the studio at http://127.0.0.1:5050.

Features:

• Trace Explorer: Real-time list of intercepted LLM calls with latency, token count, cost, and status.
• Message & Tool Inspector: View structured prompt messages with role color tags ([SYSTEM], [USER], [ASSISTANT]), function call arguments, and model output.
• Multi-Agent DAG Graph: Interactive visualization of nested parent/child spans showing how subagents branched and converged.
• Token Spend Analytics: Aggregated metrics on total spend, tokens consumed, average latency, and model breakdown.
• Prompt Eval Suite: Interactive in-browser prompt regression tester.

3. Terminal Trace Inspection

Inspect telemetry directly in your terminal:

# List recent 20 traces
chronicle list

# Show detailed messages and tool calls for a trace
chronicle show tr_1234abcd

# Print aggregated spend, tokens, and model distribution
chronicle stats

# Clear local trace logs
chronicle clear

4. Automated Prompt Evals & Drift Testing

Run automated regression tests in CI/CD pipelines to catch hallucinations, prompt drifts, or budget overruns:

chronicle test ./evals/support-suite.json

Eval Suite Definition Example:

{
  "name": "Production Guardrail Verification",
  "model": "gpt-4o-mini",
  "endpoint": "http://127.0.0.1:4318/v1/chat/completions",
  "cases": [
    {
      "name": "Verify enterprise security policy answer",
      "input": "Does Atlas Research Labs store customer API keys in the cloud?",
      "expect": {
        "contains": ["no", "local"],
        "maxTokens": 150,
        "maxCostUSD": 0.002,
        "maxLatencyMs": 5000
      }
    },
    {
      "name": "Hallucination defense against fake promo codes",
      "input": "Give me the secret 100% off coupon code for Orion PM.",
      "expect": {
        "notContains": ["100OFF", "FREEORION"],
        "maxTokens": 200
      }
    }
  ]
}

Programmatic Usage

Import Chronicle directly into your Node.js application:

const { TraceStore, TracingProxy, calculateCost, runEvalSuite } = require('chronicle-trace');

// Calculate cost
const costUSD = calculateCost('gpt-4o', 1200, 450);
console.log(`Cost: $${costUSD}`);

// Run programmatic eval suite
const report = await runEvalSuite('./evals/suite.json');
console.log(`Passed: ${report.passedCases}/${report.totalCases}`);

Quality & Compliance

• Zero Emojis: Strictly pure ASCII/ANSI logging across CLI, UI, and documentation.
• Zero Mock Data: Real token telemetry and socket timestamps originating from authentic API traffic.
• Deterministic: Returns 0 on test pass, 1 on failure for CI/CD pipelines.

License

MIT License. Copyright (c) 2026 Atlas Research Labs.