# How to Use OmniRoute with Coding Agents like Claude Code and Cursor: Complete Setup Guide

> Integrate OmniRoute with coding agents like Claude Code and Cursor. Follow this guide to set up API keys or OAuth and send requests to the chat completions endpoint for seamless integration.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-31

---

**To use OmniRoute with Claude Code or Cursor, register the provider in the OmniRoute dashboard, add your API key or complete OAuth, then send requests to `/api/v1/chat/completions` with the model identifier (`claude-3.5-code` or `cursor-code`).**

OmniRoute is a unified AI proxy and router that streamlines access to over 300 LLM providers through a single endpoint. According to the `diegosouzapw/OmniRoute` source code, both Claude Code and Cursor integrate into this architecture via the provider registry at [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), sharing the same request pipeline while using distinct authentication flows.

## Setting Up Claude Code with OmniRoute

### Register the Claude Code Provider

Claude Code is pre-registered in the provider registry at [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), so no code changes are required. To activate it:

- Open the dashboard and navigate to **Settings** → **Claude Fast Mode** (defined in `src/app/(dashboard)/dashboard/settings/components/ClaudeFastModeTab.tsx`).
- Click **Import Claude Auth** to open the modal at `src/app/(dashboard)/dashboard/providers/[id]/components/modals/ImportClaudeAuthModal.tsx`.
- Paste your Claude Code API key to enable authentication.

### Send Your First Request

Once configured, route coding requests through the unified endpoint:

```http
POST /api/v1/chat/completions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_OMNIROUTE_TOKEN>

{
  "model": "claude-3.5-code",
  "messages": [
    { "role": "user", "content": "Write a TypeScript function that formats a date." }
  ],
  "max_tokens": 1024,
  "temperature": 0.2
}

```

OmniRoute validates the payload using Zod, selects the Claude Code executor via `getExecutor()`, and streams the response through `handleChatCore()` in `open-sse/handlers/`.

### Enable Combo Routing for Resilience

For production workloads, enable combo routing in the dashboard to implement automatic fallbacks. The combo service ([`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) will attempt Claude Code first, then switch to alternatives like GPT-4 Code if the circuit breaker ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) detects failures.

## Integrating Cursor with OmniRoute

### Connect Cursor via OAuth

Cursor requires OAuth authentication rather than API keys. The flow uses:

- **UI Component**: [`src/shared/components/CursorAuthModal.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/components/CursorAuthModal.tsx) renders the connection interface.
- **Persistence**: [`src/lib/oauth/services/persistCursorConnection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/oauth/services/persistCursorConnection.ts) securely stores the OAuth token.
- **Configuration**: OAuth endpoints are defined in [`src/lib/oauth/providers/kimi-coding.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/oauth/providers/kimi-coding.ts).

In the dashboard, navigate to **Providers → Cursor** and click **Connect** to initiate the flow.

### Execute Cursor Coding Requests

After authorization, send requests using the Cursor model identifier:

```http
POST /api/v1/chat/completions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_OMNIROUTE_TOKEN>

{
  "model": "cursor-code",
  "messages": [
    { "role": "user", "content": "Generate a React component that fetches data from an API." }
  ],
  "max_tokens": 1500,
  "temperature": 0.3
}

```

The request flows through the Cursor executor at [`open-sse/executors/cursorExecutor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/cursorExecutor.ts), which handles the HTTP dispatch and response translation.

### Monitor Token Health

Cursor connections are monitored by [`src/lib/tokenHealthCheckCursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/tokenHealthCheckCursor.ts). The dashboard displays status via the `CursorAgentNudge` component at `src/app/(dashboard)/dashboard/providers/[id]/components/CursorAgentNudge.tsx`, alerting you when tokens approach expiry or rate limits trigger cooldowns.

## Shared Architecture for Coding Agents

Both Claude Code and Cursor utilize the same request pipeline in the OmniRoute architecture. The flow proceeds as follows:

1. **Entry Point**: Next.js App Router handles requests at `src/app/api/v1/chat/completions`.
2. **Processing**: `handleChatCore()` manages CORS, Zod validation, and policy checks.
3. **Translation**: `translateRequest()` converts between OmniRoute's standard format and provider-specific APIs.
4. **Execution**: Provider-specific executors (Claude or Cursor) dispatch HTTP calls.
5. **Response**: Results are translated back and streamed via SSE or returned as JSON.

This unified approach means you can use OmniRoute with coding agents like Claude Code or Cursor interchangeably without modifying your client code—only the `model` parameter and authentication method differ.

## Summary

- **OmniRoute** provides a single `/api/v1/chat/completions` endpoint for both Claude Code and Cursor, eliminating provider-specific integration work.
- **Claude Code** uses API key authentication via the `ImportClaudeAuthModal` component and `ClaudeFastModeTab` settings.
- **Cursor** requires OAuth flow handled by `CursorAuthModal` and persisted via [`persistCursorConnection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/persistCursorConnection.ts).
- Use model identifiers `claude-3.5-code` and `cursor-code` to route requests to the respective agents.
- Enable **combo routing** in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) for automatic failover between coding agents.
- Both providers benefit from shared resilience features including circuit breakers and token health monitoring.

## Frequently Asked Questions

### Do I need separate API keys for each coding agent?

No. While you must configure authentication for each provider individually—API keys for Claude Code via [`ImportClaudeAuthModal.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/ImportClaudeAuthModal.tsx) and OAuth for Cursor via [`CursorAuthModal.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/CursorAuthModal.tsx)—you access both through the same OmniRoute bearer token. Your client only needs the OmniRoute authentication token to reach either agent.

### Can I switch between Claude Code and Cursor without changing my application code?

Yes. The only required change is the `model` field in your JSON payload. Set `"model": "claude-3.5-code"` for Claude Code or `"model": "cursor-code"` for Cursor. The routing layer handles provider selection, request translation, and execution automatically.

### How does OmniRoute handle rate limiting for these coding agents?

OmniRoute implements provider-specific rate limiting and cooldown management. For Cursor, [`src/lib/tokenHealthCheckCursor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/tokenHealthCheckCursor.ts) monitors token health and triggers the `CursorAgentNudge` component when limits approach. Both agents benefit from the circuit breaker pattern in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts) and combo routing fallbacks defined in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).

### Is streaming supported for code generation responses?

Yes. OmniRoute streams responses via Server-Sent Events (SSE) by default. The executors for both Claude Code and Cursor handle provider-specific streaming protocols, translating them into a unified SSE format that your client receives from the `/api/v1/chat/completions` endpoint.