# How to Integrate Claude Code, Codex, Cursor, and Cline with OmniRoute: A Complete Guide

> Integrate Claude Code, Codex, Cursor, and Cline with OmniRoute using the unified proxy layer. This guide details enabling the proxy for seamless integration via provider-registry and token helpers.

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

---

**You can integrate Claude Code, Codex, Cursor, and Cline with OmniRoute by enabling the unified proxy layer that reproduces each client's exact wire format through provider-registry entries, request-fingerprinting services, and OAuth/API-key token helpers.**

Integrating popular AI coding assistants with **OmniRoute** lets you route Claude Code, Codex, Cursor, and Cline through a single endpoint while preserving each tool's native behavior. OmniRoute achieves this through a **stateless compatibility layer** that handles authentication, request shaping, and response translation without modifying the client binaries themselves. This guide walks through the configuration, environment variables, and code patterns needed for each integration.

## How OmniRoute's Compatibility Layer Works

OmniRoute operates as a **wire-compatible proxy** that intercepts HTTPS requests from AI coding assistants and transforms them to match upstream provider expectations. The architecture remains stateless from the client's perspective while adding resilience, rate-limiting, and unified billing.

The integration pipeline follows this flow:

1. **Client request** arrives at `/v1/chat/completions` or `/v1/models`
2. **Middleware** runs CORS, Zod validation, and auth checks via Next.js routes (`src/app/api/v1/…`)
3. **Provider lookup** resolves aliases like `cc`, `codex`, `cursor`, or `clinepass` in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts)
4. **Request shaping** applies fingerprinting, header injection, and tool-call translation
5. **Execution** sends the shaped request to upstream providers with circuit-breaker protection
6. **Response translation** restores original tool-call shapes and strips internal fields
7. **Streaming** wraps SSE responses with proper marker suppression

## Claude Code Integration

### Enable the Claude Code Compatible Provider

The Claude Code integration registers the `cc` alias and enforces Anthropic-compatible JSON, OAuth flows, and required headers. Enable it through environment variables:

```bash

# .env configuration

ENABLE_CC_COMPATIBLE_PROVIDER=1
CLI_COMPAT_CLAUDE=1

```

The provider entry in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts) defines base URLs, auth methods, and supported models for the `cc` alias.

### Claude Code Handshake and Fingerprinting

Two services handle Claude Code's security requirements:

- **[`claudeCodeCCH.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeCCH.ts)** validates OAuth tokens, exchanges session cookies, and injects `X-Title: Claude`
- **[`claudeCodeFingerprint.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeFingerprint.ts)** reorders JSON fields and rewrites header casing to match the real CLI's request hash

Optional **stealth mode** via [`claudeCodeObfuscation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeObfuscation.ts) randomizes non-essential request parts while preserving the signed fingerprint—useful when environments block exact Claude traffic patterns.

### Launch Claude Code Against OmniRoute

Use the `omniroute launch` wrapper to inject correct environment variables:

```bash
omniroute launch \
  --remote http://localhost:20128 \
  --api-key <YOUR_OMNIRoute_API_KEY>

```

The wrapper automatically configures the CLI to target your OmniRoute endpoint instead of Anthropic's direct API.

## Cline Integration

### Token Handling and Header Generation

Cline integration requires **WorkOS token management** and specific headers. The [`clinepassHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/clinepassHeaders.ts) utility builds:

- `Authorization: Bearer workos:<token>`
- Mandatory `X-Title: Cline` header

### Refresh Cline Tokens Programmatically

```typescript
import { buildClineHeaders, getClineAccessToken } from '@omniroute/open-sse/utils/clinepassHeaders.ts';

async function refreshClineToken(refreshToken: string) {
  const accessToken = await fetch('https://auth.workos.com/token', {
    method: 'POST',
    body: JSON.stringify({ refresh_token: refreshToken }),
    headers: { 'Content-Type': 'application/json' },
  })
    .then(r => r.json())
    .then(r => r.access_token);

  return buildClineHeaders(accessToken, {}, { taskId: 'cline-refresh' });
}

```

The `clinepass` provider alias in the registry maps to Cline-specific configuration with automatic token refresh support.

## Cursor Integration

### Version Detection and User-Agent Injection

Cursor requires precise **binary version detection** to set the correct `User-Agent`. The [`cursorVersionDetector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursorVersionDetector.ts) utility parses incoming headers and identifies whether the stable or insiders build is calling:

```typescript
import { cursorVersionDetector } from '@omniroute/open-sse/utils/cursorVersionDetector.ts';
import { cursorAgentProtobuf } from '@omniroute/open-sse/utils/cursorAgentProtobuf.ts';

export async function adaptCursorRequest(body: any, reqHeaders: Record<string, string>) {
  const version = cursorVersionDetector(reqHeaders['user-agent']);
  const patched = cursorAgentProtobuf.encodeTools(body);

  // Inject proper User-Agent for detected version
  reqHeaders['User-Agent'] = `Cursor/${version}`;

  return { body: patched, headers: reqHeaders };
}

```

### Tool-Call Format Translation

Cursor uses a **subagent format** different from Claude's native `tool_use` / `tool_result` blocks. The [`cursorAgentProtobuf.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursorAgentProtobuf.ts) utility performs bidirectional conversion between these formats, enabling seamless tool use across clients.

Enable Cursor compatibility with:

```bash
CLI_COMPAT_CURSOR=1

```

## Codex Integration

### Native Passthrough Mode

Codex integration is the simplest—when `nativeCodexPassthrough` is enabled, OmniRoute detects the native **web_search** tool shape and forwards requests unmodified.

```bash
nativeCodexPassthrough=1

```

The translator checks this flag in [`open-sse/translator/helpers/claudeHelper.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/helpers/claudeHelper.ts) and skips all conversion for native Codex clients. This preserves OpenAI's exact wire format when Codex is the calling client.

## Feature Flags for Step-by-Step Enablement

All compatibility layers can be toggled independently through environment variables defined in [`docs/reference/FEATURE_FLAGS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/FEATURE_FLAGS.md):

| Flag | Effect |
|------|--------|
| `ENABLE_CC_COMPATIBLE_PROVIDER` | Registers `cc` aliases in provider registry |
| `CLI_COMPAT_CLAUDE=1` | Forces Claude Code request fingerprinting |
| `CLI_COMPAT_CURSOR=1` | Enables Cursor version detection and tool translation |
| `nativeCodexPassthrough=1` | Bypasses translation for native Codex requests |

This modular approach lets operators enable integrations incrementally and debug each layer separately.

## Key Source Files Reference

Understanding these files helps with custom integrations and troubleshooting:

- **[`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts)** — Central map of all provider aliases (`claude`, `cc`, `cursor`, `clinepass`)
- **[`open-sse/services/claudeCodeCCH.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/claudeCodeCCH.ts)** — OAuth handshake and session-cookie handling
- **[`open-sse/services/claudeCodeFingerprint.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/claudeCodeFingerprint.ts)** — JSON field reordering and header casing
- **[`open-sse/services/claudeCodeObfuscation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/claudeCodeObfuscation.ts)** — Optional stealth mode for fingerprinted requests
- **[`open-sse/utils/clinepassHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/clinepassHeaders.ts)** — Cline token header builder and refresh logic
- **[`open-sse/utils/cursorVersionDetector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/cursorVersionDetector.ts)** — Cursor binary version detection from User-Agent
- **[`open-sse/utils/cursorAgentProtobuf.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/cursorAgentProtobuf.ts)** — Tool-call format conversion between Claude and Cursor
- **[`open-sse/translator/helpers/claudeHelper.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/helpers/claudeHelper.ts)** — Core translation logic with Codex passthrough flag

## Configuration Checklist

Before running your integrated setup:

1. Verify OmniRoute endpoint is accessible (`http://localhost:20128` or remote URL)
2. Set provider-specific feature flags for each client you need
3. Configure API keys or OAuth credentials in OmniRoute dashboard
4. Test with `omniroute launch` wrapper or direct CLI configuration
5. Monitor translation logs for fingerprint mismatches or auth errors

## Summary

- **OmniRoute's unified proxy layer** lets Claude Code, Codex, Cursor, and Cline connect to any LLM provider without client modifications
- **Provider-registry entries** (`cc`, `clinepass`, `cursor`, etc.) define base URLs, auth methods, and model lists in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts)
- **Request fingerprinting** services ([`claudeCodeFingerprint.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeFingerprint.ts), [`cursorVersionDetector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursorVersionDetector.ts)) reproduce each client's exact wire format
- **OAuth and token helpers** handle Claude Code session cookies, Cline WorkOS tokens, and Cursor version-specific headers
- **Feature flags** enable step-by-step activation: `CLI_COMPAT_CLAUDE`, `CLI_COMPAT_CURSOR`, `nativeCodexPassthrough`
- **Tool-call translation** ([`cursorAgentProtobuf.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursorAgentProtobuf.ts)) bridges format differences between Claude-style and Cursor subagent blocks

## Frequently Asked Questions

### What is the minimum OmniRoute version for Claude Code integration?

Claude Code compatibility requires OmniRoute release **v3.8.50** or later, where the `cc` alias and fingerprinting services were stabilized. Earlier versions lack the [`claudeCodeObfuscation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeObfuscation.ts) stealth mode and complete OAuth handshake implementation.

### Can I run multiple AI assistants simultaneously through one OmniRoute instance?

Yes. The provider-registry architecture isolates each integration. Configure `CLI_COMPAT_CLAUDE=1`, `CLI_COMPAT_CURSOR=1`, and `nativeCodexPassthrough=1` together—each client uses its own alias (`cc`, `cursor`, default for Codex) and receives correctly shaped requests without interference.

### Why does Claude Code require fingerprinting when other clients don't?

Anthropic's official CLI computes a **cryptographic request hash** that includes JSON field order and header casing. The [`claudeCodeFingerprint.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/claudeCodeFingerprint.ts) service reproduces this hash so upstream security checks pass. Other clients lack this verification—Cursor and Cline use standard header validation, while Codex relies on OpenAI's simpler auth model.

### How do I troubleshoot token refresh failures with Cline?

Check [`open-sse/utils/clinepassHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/clinepassHeaders.ts) for the `buildClineHeaders` function. Verify your WorkOS refresh token is valid and the `taskId` parameter is unique per session. Enable debug logging in OmniRoute to see the full token exchange with `auth.workos.com`—expired or revoked refresh tokens return 401 errors that should trigger re-authentication flows in your client.