> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DevTools

> SDK development tools for telemetry capture

> [!WARNING]
>
> The OpenRouter CLI and its DevTools viewer are retired. The separate `@openrouter/devtools` telemetry package remains available and is currently pre-release. There is no complete supported public client integration yet: `@openrouter/sdk` cannot attach the DevTools hooks through its typed public options, and `@openrouter/agent` `callModel` uses streaming Responses API output that DevTools cannot currently complete or normalize. See [Client Compatibility](#client-compatibility) below. DevTools is designed for development use only and should never be deployed in production environments.

The `@openrouter/devtools` package provides pre-release telemetry hooks for compatible integrations. It stores captured data locally as JSON; it no longer includes a maintained viewer.

## Telemetry capture

For compatible operations that complete successfully, the hooks record:

* Request and response data
* Token usage
* Timing information for performance analysis
* Errors and failure modes
* Model information

## Installation

Install the DevTools package as a development dependency:

```bash title="npm" lines theme={null}
npm install --save-dev @openrouter/devtools
```

```bash title="pnpm" lines theme={null}
pnpm add -D @openrouter/devtools
```

```bash title="yarn" lines theme={null}
yarn add -D @openrouter/devtools
```

```bash title="bun" lines theme={null}
bun add -d @openrouter/devtools
```

```bash title="deno" lines theme={null}
deno add --dev npm:@openrouter/devtools
```

**Important:** DevTools is designed for development only. It will throw an error if `NODE_ENV === 'production'` to prevent accidental production deployment.

## Client Compatibility

> [!WARNING]
>
> Do not attach DevTools to Agent SDK `callModel` and expect complete telemetry. Although `@openrouter/agent` accepts the hooks, `callModel` always uses a streaming Responses API request. DevTools currently attempts to parse the response as JSON, does not parse the SSE stream, and does not normalize the Responses API request or response schema.

The generated `@openrouter/sdk` client is not an alternative setup: its typed public constructor options do not provide a way to attach the plain DevTools hook object. Neither published client currently provides a complete supported public integration.

## How It Works

### Telemetry Capture Flow

With a compatible hook integration:

1. SDK hooks intercept requests before they're sent
2. Hook processing parses the request or response body
3. Data is stored in `.devtools/openrouter-generations.json`
4. An optional notification is sent to the configured local endpoint; notification failures are ignored

### Failure Isolation

* **Request preservation** - Hooks return the original SDK request or response
* **Graceful degradation** - Capture errors are swallowed instead of replacing the SDK result
* **Hook overhead** - Body parsing runs inside the SDK hook lifecycle; capture is not zero-cost
* **Development-only** - Throws error if used in production (`NODE_ENV === 'production'`)

### Storage Location

By default, telemetry is stored in:

```lines theme={null}
.devtools/openrouter-generations.json
```

This file contains:

* **Runs** - Top-level tracking of SDK operations
* **Steps** - Individual request/response pairs within each run
* **Metadata** - Timestamps, status, token usage, errors

## Configuration Options

### Hook Configuration

When calling `createOpenRouterDevtools()`, you can customize:

| Option | Type | Default | Description |
| - | - | - | - |
| `storagePath` | `string` | `'.devtools/openrouter-generations.json'` | Where to store captured telemetry |
| `serverUrl` | `string` | `'http://localhost:4983/api/notify'` | Legacy viewer notification endpoint; no maintained server is provided |

## Recognized Operation IDs

The hooks recognize these internal SDK operation IDs:

* `createResponses` - Responses API calls
* `sendChatCompletionRequest` - Chat completions API calls

This is not a list of working public client integrations. The Agent SDK reaches `createResponses`, but its streaming response is unsupported. The generated Client SDK reaches `sendChatCompletionRequest`, but it cannot attach the plain hooks through its typed public options. All other SDK operations, including embeddings, are ignored.

## Data Captured Per Step

For each compatible operation that completes successfully, DevTools captures:

**Request Data:**

* Model name
* Messages/prompts
* Parameters (temperature, max\_tokens, etc.)

**Response Data:**

* Generated content
* Token usage (prompt + completion tokens)
* Provider and model used
* Finish reason

**Metadata:**

* Start and completion timestamps
* Duration in milliseconds
* Status (success, error, in\_progress)
* Error details (if failed)

## Safety & Best Practices

### Production Environment Protection

Creating DevTools hooks throws an error when `NODE_ENV === 'production'`. Only initialize the package in a development environment and only from a compatible integration.

### Capture Failure Isolation

* Hook body parsing is awaited by the SDK hook lifecycle
* DevTools capture errors do not replace your SDK result
* Failed writes are silently ignored and don't break your application

### Error Handling

DevTools catches failures in request parsing, response parsing, storage, and server notification. A capture failure can leave telemetry missing or incomplete, but it does not replace the SDK request or response.

## Troubleshooting

### Storage Location Issues

If you can't find the telemetry file:

1. Check the default location: `.devtools/openrouter-generations.json`
2. Ensure you have write permissions in your working directory
3. Check for custom `storagePath` configuration

### Common Setup Issues

**Issue:** DevTools package not found

```bash lines theme={null}
Cannot find module '@openrouter/devtools'
```

**Solution:** Install the package:

```bash title="npm" lines theme={null}
npm install --save-dev @openrouter/devtools
```

```bash title="pnpm" lines theme={null}
pnpm add -D @openrouter/devtools
```

```bash title="yarn" lines theme={null}
yarn add -D @openrouter/devtools
```

```bash title="bun" lines theme={null}
bun add -d @openrouter/devtools
```

```bash title="deno" lines theme={null}
deno add --dev npm:@openrouter/devtools
```

***

**Issue:** Accidental production usage

```bash lines theme={null}
Error: DevTools should not be used in production
```

**Solution:** Initialize the hook package only in a development environment and only from a compatible integration.
