Set Up the Laminar Debugger - Laminar documentation

The debugger is controlled almost entirely with environment variables. Once your agent is instrumented, you turn debug mode on and pick a replay boundary by setting variables on the run command. Runs group into a session automatically: the first run writes .lmnr/debug-session.json and every later run in the same directory rejoins it, so you don’t pass a session id around. No code changes are needed in the general case.

General setup

1. Install the CLI

npm install -g lmnr-cli
# or run on demand with: npx lmnr-cli@latest

2. Run setup

lmnr-cli setup

setup logs you in (the debug commands authenticate as you, the signed-in user), links the directory to a project via .lmnr/project.json, writes LMNR_PROJECT_API_KEY to your env file so the SDK can send traces, and installs the Laminar skill into your project so your coding agent knows how to drive the debugger. The CLI itself never uses the project API key; that key is only for the SDK in your agent. See the CLI page for details.

3. Ask your coding agent to instrument your agent

The debugger works on top of normal Laminar tracing. With the skill installed, ask your coding agent to instrument your agent and it will wire up the right integration for you: the Getting Started onboarding prompt is the fastest way to hand it off. Caching is limited to a specific set of integrations (see how caching works), but the record, inspect, and replay loop runs with everything Laminar traces. If you use the AI SDK, see the AI SDK caching note below for one extra wrapper.

4. Ask your coding agent to run the debugger

Once your agent is instrumented, ask your coding agent to run the full debugger loop. It records a run, reads the trace, edits your code, and replays from a checkpoint, all on its own. The debugger process page walks through every step it runs. To drive it yourself instead, add LMNR_DEBUG=true to your run command to record a session. From there, a handful of environment variables control replay:

Variable	Required	Description
`LMNR_DEBUG`	Yes	Set to `true`, `1`, `yes`, or `on` to enable debug mode.
`LMNR_DEBUG_REPLAY_TRACE_ID`	For replay	Trace id of the run to replay from.
`LMNR_DEBUG_CACHE_UNTIL`	For replay	Span id of the last LLM call to replay (inclusive); calls after it run live. Accepts a full UUID, the last two UUID groups, the 16-char OTel id, or any hex suffix.
`LMNR_DEBUG_SESSION_ID`	Optional	Pin a run to a specific session. You rarely need this: after the first run, `.lmnr/debug-session.json` rejoins the same session automatically. Set it to override the file or to join a session created elsewhere.

The first LMNR_DEBUG=true run mints a session, registers it with Laminar, writes .lmnr/debug-session.json, and opens the session in your browser. Later runs in the same directory (or any subdirectory) read that file and rejoin the session silently (no second browser tab). To start a clean session on purpose, run lmnr-cli debug session new, which resets the file. The same variables work for evaluations: run your eval with LMNR_DEBUG=true and it joins the current session as an evaluation card. Notes are attached with lmnr-cli debug session add-note rather than an environment variable. The debugger process page walks through using these variables end to end.

AI SDK caching

For the AI SDK (TypeScript), caching needs one extra step on top of the normal telemetry integration: wrap each model with wrapLanguageModel. The wrapper is what hashes the span input and consults the Laminar backend for a cached response. Without it, your AI SDK calls are traced and replayable as part of the transcript, but they will not serve from cache. The wrapLanguageModel step is the same across AI SDK versions; only the telemetry wiring differs.

AI SDK v7
AI SDK v5 and v6

import { generateText, gateway, registerTelemetry } from 'ai';
// or
import { anthropic } from '@ai-sdk/anthropic';
import { wrapLanguageModel, LaminarAiSdkTelemetry } from '@lmnr-ai/lmnr';

registerTelemetry(new LaminarAiSdkTelemetry());

await generateText({
  // this line is what enables debugger caching
  model: wrapLanguageModel(gateway('openai/gpt-5')),
  // or
  // model: wrapLanguageModel(anthropic('claude-opus-4-5')),
  // ... other params. No per-call telemetry needed.
});

import { generateText, gateway } from 'ai';
// or
import { anthropic } from '@ai-sdk/anthropic';
import { Laminar, wrapLanguageModel, getTracer } from '@lmnr-ai/lmnr';

Laminar.initialize();

await generateText({
  // this line is what enables debugger caching
  model: wrapLanguageModel(gateway('openai/gpt-5')),
  // or
  // model: wrapLanguageModel(anthropic('claude-opus-4-5')),
  // ... other params

  // general Laminar telemetry integration
  experimental_telemetry: {
    isEnabled: true,
    tracer: getTracer(),
  },
});

What’s next

The debugger process

The full loop your coding agent runs: record, inspect, replay, and evaluate.

How caching works

What gets cached, the input hash, and which integrations support it.

End-to-end guide

One real bug taken through the whole loop, with real commands and outputs.

CLI reference

Full reference for the lmnr-cli debug session commands.

​General setup

​1. Install the CLI

​2. Run setup

​3. Ask your coding agent to instrument your agent

​4. Ask your coding agent to run the debugger

​AI SDK caching

​What’s next