---
title: Lapdog
description: >-
  Run an LLM Observability dashboard locally to inspect coding-agent and
  application traces in your browser without a Datadog account.
breadcrumbs: Docs > LLM Observability > Lapdog
---

# Lapdog

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ().
{% /alert %}

{% /callout %}

## Overview{% #overview %}

Lapdog is a local development tool for LLM Observability. It runs an agent on `localhost:8126` that captures every span, prompt, tool call, and cost from your LLM application, or from a coding agent like Claude Code, Codex, or Pi, and streams them into a browser dashboard at [lapdog.datadoghq.com](https://lapdog.datadoghq.com). No Datadog account is required.

Lapdog is built on the open-source [Datadog APM test agent](https://github.com/DataDog/dd-apm-test-agent/blob/master/lapdog/README.md). It can also forward captured telemetry to Datadog so the same data appears in LLM Observability alongside your production traffic.

## What you get{% #what-you-get %}

- Per-session traces with prompts, tool calls, and responses
- Token usage and estimated cost, broken down by input, output, and cache hits
- Permission friction: gated tool calls and wait times
- Context window usage and cache hit rate over the session
- Live status of the running coding agent (running, idle, blocked)

## Install{% #install %}

{% tab title="Homebrew (macOS)" %}

```shell
brew install datadog/lapdog/lapdog
```

{% /tab %}

{% tab title="pip / pipx" %}

```shell
pipx install ddapm-test-agent
# or: pip install ddapm-test-agent
```

{% /tab %}

For Docker, from-source, and other install paths, see the [Lapdog install guide](https://github.com/DataDog/dd-apm-test-agent/blob/master/lapdog/README.md).

## Run a coding agent{% #run-a-coding-agent %}

Lapdog instruments coding agents end-to-end. Each prompt, tool call, and permission request becomes a span in a session you can replay from the dashboard.

{% tab title="Claude Code" %}

```shell
lapdog claude
```

Starts the local agent, installs the Claude Code lapdog plugin, and launches Claude Code.
{% /tab %}

{% tab title="Codex" %}

```shell
lapdog codex
```

Starts the local agent, then launches Codex with an OpenAI-compatible proxy and JSONL watcher that capture every LLM request, tool call, and step into a session.
{% /tab %}

{% tab title="Pi" %}

```shell
lapdog pi
```

Starts the local agent, installs the Pi lapdog extension, and launches Pi with `LAPDOG_URL` configured.
{% /tab %}

{% tab title="Other" %}

```shell
lapdog python my_app.py
```

Run any command with `ddtrace` auto-instrumentation pointed at the local agent. Useful for instrumenting your own LLM-powered application during development.
{% /tab %}

**Note**: `lapdog claude` and `lapdog codex` are proxy-backed: the local Lapdog agent sits in the live model-request path. Keep Lapdog running until the coding agent exits. If you stop or kill Lapdog mid-session, the launched coding agent can stop making progress on model calls. Restart the coding agent after restarting Lapdog. `lapdog pi` and hook-only setups fail open if Lapdog goes down: the coding agent keeps running, but capture data is lost.

## View sessions{% #view-sessions %}

While a session is running, open [lapdog.datadoghq.com](https://lapdog.datadoghq.com). The dashboard reads directly from your local agent on `localhost:8126`; no login or Datadog account is needed.

If you've changed the local port, override it from the Collecting sessions badge in the dashboard header.

## Forward events to Datadog{% #forward-events-to-datadog %}

To dual-ship captured events to LLM Observability in Datadog, set your API key and pass `--forward`:

```shell
DD_API_KEY=<YOUR_API_KEY> lapdog --forward claude
```

Forwarded spans are tagged `source:lapdog` so you can distinguish development sessions from production traffic.

## Useful commands{% #useful-commands %}

| Command                | What it does                                                  |
| ---------------------- | ------------------------------------------------------------- |
| `lapdog claude`        | Launch Claude Code with capture wired up                      |
| `lapdog codex`         | Launch Codex with the OpenAI proxy and JSONL watcher wired up |
| `lapdog pi`            | Launch Pi with the lapdog extension installed                 |
| `lapdog python app.py` | Run any application with tracing instrumentation              |
| `lapdog start`         | Start the local agent in the background                       |
| `lapdog stop`          | Stop the background agent                                     |
| `lapdog status`        | Show whether the agent is running                             |

For the full list of options, run `lapdog --help`.

## Uninstall{% #uninstall %}

Follow these steps to remove Lapdog and the state it writes to your home directory. Your package manager (Homebrew, pip, or pipx) cleans up only what it installed; it does not touch `~/.lapdog/`, the Claude Code plugin, or the pi extension.

1. Stop the local agent:

   ```shell
   lapdog stop
   ```

1. Remove the Claude Code plugin (if installed):

   ```shell
   claude plugin uninstall lapdog@lapdog
   claude plugin marketplace remove lapdog
   ```

1. Remove the pi extension (only if you ran `lapdog pi`):

   ```shell
   rm -f ~/.pi/agent/extensions/lapdog.ts
   ```

1. Remove the Lapdog working directory:

   ```shell
   rm -rf ~/.lapdog
   ```

1. Uninstall the package:

   {% tab title="Homebrew (macOS)" %}

   ```shell
   brew uninstall lapdog
   brew untap datadog/lapdog
   ```

   {% /tab %}

   {% tab title="pip / pipx" %}

   ```shell
   pipx uninstall ddapm-test-agent
   # or: pip uninstall ddapm-test-agent
   ```

   {% /tab %}

## Further reading{% #further-reading %}

- [Lapdog README on GitHub](https://github.com/DataDog/dd-apm-test-agent/blob/master/lapdog/README.md)
- [Instrument your application with the LLM Observability SDK](https://docs.datadoghq.com/llm_observability/instrumentation/sdk.md)
- [Auto-instrumentation for LLM Observability](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation.md)