Skip to main content
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 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:
Important: DevTools is designed for development only. It will throw an error if NODE_ENV === 'production' to prevent accidental production deployment.

Client Compatibility

There is currently no complete supported public client integration. The generated @openrouter/sdk client cannot attach the plain DevTools hook object through its typed public constructor options.
The Agent SDK is not an alternative Client SDK setup. Although @openrouter/agent accepts the hooks, its callModel method 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.

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:
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:

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
Solution: Install the package:

Issue: Accidental production usage
Solution: Initialize the hook package only in a development environment and only from a compatible integration.