Skip to main content
The DevTools SDK and CLI are currently in pre-release status. There is no complete supported public Agent SDK integration yet: callModel uses streaming Responses API output that DevTools cannot currently complete or normalize. DevTools is designed for development use only and should never be deployed in production environments.
The OpenRouter DevTools include pre-release telemetry hooks and a viewer for compatible telemetry files.

​
Why use DevTools?

Building with AI SDKs requires visibility into what’s happening under the hood. The DevTools viewer helps inspect telemetry produced by a compatible integration. Two main components:
  1. SDK Telemetry Hooks - Normalize supported operations into the DevTools telemetry format
  2. DevTools Viewer - Beautiful web UI for visualizing captured telemetry data

​
Key Features

​
SDK DevTools Viewer

Launch a web-based interface to visualize your SDK telemetry:
  • Run tracking - View operations from an existing compatible telemetry file
  • Detailed step analysis - Inspect request/response data, timing, and errors for each step
  • Token usage insights - Track prompt and completion tokens across all requests
  • Error debugging - Easily identify and debug failed requests with full error details
  • Dark/Light mode - Full theme support with automatic system preference detection
DevTools Interface

​
SDK Telemetry Hooks

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:
Install the CLI that provides the openrouter devtools command:
Important: DevTools is designed for development only. It will throw an error if NODE_ENV === 'production' to prevent accidental production deployment.

​
Client Compatibility

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.

​
Quick Start - DevTools Viewer

From a project containing an existing compatible .devtools/openrouter-generations.json file, launch the DevTools web interface:
This starts a local server on port 4983. Open http://localhost:4983 in your browser to view:
  • All SDK runs with timestamps and status
  • Step-by-step request/response details
  • Token usage
  • Error messages and stack traces
  • Performance timing information
The viewer automatically refreshes when new telemetry data is captured.

​
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. A notification is sent to the local DevTools server (if running)
  5. The DevTools viewer updates in real-time

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

​
DevTools Server Configuration

The DevTools viewer runs on port 4983 by default. Set OPENROUTER_DEVTOOLS_PORT when launching the CLI to use a different port:

​
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

​
Port Already in Use

If port 4983 is already in use:
Solution: Either stop the process using port 4983, or launch the viewer with a different port:
If you maintain a compatible hook integration, update its notification configuration:

​
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

​
DevTools Viewer Not Updating

If the viewer doesn’t show new requests:
  1. Verify the DevTools server is running (openrouter devtools)
  2. Check that serverUrl matches the DevTools server port
  3. Ensure the telemetry file is being written (check .devtools/ directory)
  4. Try refreshing the browser manually

​
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.