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

> Integrate OmniRoute with Claude Code, Cursor, and Cline effortlessly. This guide provides a complete setup for seamless integration with zero client-side configuration. Learn how.

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

---

**OmniRoute integrates with coding agents through automatic CLI detection, OAuth-based provider registration, and MCP skill orchestration—requiring zero client-side configuration beyond installing the agent and saving its credentials.**

OmniRoute acts as a unified gateway for LLM requests, routing traffic to 33+ local coding agents while handling authentication, model aliases, and response translation automatically. This guide explains the complete integration architecture and provides copy-paste code examples for connecting Claude Code, Cursor, Cline, and other popular agents.

## How OmniRoute Discovers and Registers Coding Agents

OmniRoute uses a three-layer architecture to integrate coding agents without manual configuration files.

| Layer | Responsibility | Key Source File |
|-------|---------------|---------------|
| **Provider registry** | Defines base URLs, auth headers, and model aliases for OAuth/API-key agents | [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) |
| **CLI-tool detection** | Scans the host for installed agents and creates unified tool descriptors | [`src/lib/cli-helper/tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cli-helper/tool-detector.ts) |
| **Agent-skill orchestration** | Exposes MCP/A2A skills for invoking detected agents | [`src/shared/constants/agentSkills.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/agentSkills.ts) |

The integration flows automatically: detection → registration → skill exposure. Each layer feeds the next, enabling zero-config discovery of Claude Code, Cursor, Cline, and 30+ other coding tools.

## Registering OAuth-Based Coding Agents

Coding agents that use OAuth or API-key authentication are defined in [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts). Each entry specifies headers, model prefixes, and compatibility flags.

### Claude Code Provider Definition

Claude Code integration uses a special `compatiblePrefix` to enable model-gateway discovery:

```typescript
// src/shared/constants/providers/oauth.ts
export const OAUTH_PROVIDERS = {
  "claude": {
    name: "Claude Code",
    description: "Anthropic Claude Code CLI — ANTHROPIC_BASE_URL points to OmniRoute",
    authHeaders: (token) => ({
      "Authorization": `Bearer ${token}`,
      "Anthropic-Version": "2023-06-01",
      "User-Agent": getClaudeCodeUserAgent("cli"),
    }),
    compatiblePrefix: "anthropic-compatible-cc-",  // enables auto-discovery
  },
  // Cursor, Cline follow identical structure
};

```

The `compatiblePrefix` value tells [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) to treat matching model IDs as Claude Code-compatible, triggering the appropriate header transformation and payload translation.

## Detecting Installed CLI Agents

On startup, OmniRoute runs [`tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tool-detector.ts) to locate agent binaries and configuration files:

```typescript
// src/lib/cli-helper/tool-detector.ts
export const DETECTED_TOOLS = [
  { id: "claude", name: "Claude Code", configPath: "~/.claude/profiles" },
  { id: "cursor", name: "Cursor", configPath: "~/.cursor/config.json" },
  { id: "cline",  name: "Cline",   configPath: "~/.cline/data/globalState.json" },
  // ... 30+ additional agents
];

```

Each descriptor feeds into [`src/lib/acp/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/acp/registry.ts), which:

- Renders agent cards in the UI ([`CliToolCard.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/CliToolCard.tsx))
- Builds correct upstream headers per agent
- Enables skill invocation through the MCP server

## Exposing Agent Skills via MCP

OmniRoute wraps detected agents with invocable skills defined in [`src/shared/constants/agentSkills.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/agentSkills.ts):

```typescript
// src/shared/constants/agentSkills.ts
{
  name: "installCodingAgents",
  description:
    "Detect installed CLI coding tools (Claude Code, Codex, Cursor, Copilot, Cline and more), " +
    "search GitHub for matching agent skills, and install them to the detected tools",
  handler: async (args) => { /* scans DETECTED_TOOLS → installs skill packs */ },
}

```

These skills enable programmatic workflows: installing Claude Code profiles, running Cline sub-agents, or executing Cursor code completions through the same unified API.

## Request Routing Flow for Coding Agents

When a client sends a request, OmniRoute handles the full translation pipeline:

1. **Model resolution** — [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts) matches model IDs to providers via `isClaudeCodeCompatibleProvider()`
2. **Header construction** — [`default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/default.ts) executor injects OAuth tokens using provider-specific logic
3. **Payload translation** — OpenAI-format requests convert to Anthropic-compatible format for Claude Code
4. **Response streaming** — SSE responses preserve agent-specific markers (e.g., `message_stop`)

This executes transparently with no client-side code changes—only the agent installation and credential storage are required.

## Practical Integration Examples

### List All Detected Coding Agents

Query the MCP tools endpoint to see which agents OmniRoute has discovered:

```typescript
import { fetch } from "node-fetch";

async function listAgents() {
  const res = await fetch("http://localhost:3000/api/mcp/tools", {
    method: "GET",
    headers: { "Accept": "application/json" },
  });
  const { tools } = await res.json();
  
  tools
    .filter((t) => ["claude", "cursor", "cline"].includes(t.id))
    .forEach((t) => console.log(`- ${t.name} (id=${t.id})`));
}

listAgents();

```

This pulls from [`src/lib/acp/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/acp/registry.ts), which is populated by [`tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tool-detector.ts) scan results.

### Auto-Install Claude Code Profiles

Enable profile synchronization and trigger the install skill:

```typescript
import { fetch } from "node-fetch";

async function syncClaudeProfiles() {
  // Enable Claude Code Discovery Aliases feature flag
  await fetch("http://localhost:3000/api/settings/feature-flags/claude-code-profiles", {
    method: "POST",
    body: JSON.stringify({ enabled: true }),
    headers: { "Content-Type": "application/json" },
  });

  // Execute the agent installation skill
  await fetch("http://localhost:3000/api/mcp/execute", {
    method: "POST",
    body: JSON.stringify({ tool: "installCodingAgents", args: {} }),
    headers: { "Content-Type": "application/json" },
  });
}

syncClaudeProfiles();

```

The feature flag is defined in [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) and controls automatic profile creation in `~/.claude/profiles`.

### Route Requests Through Cursor

Send chat completions through Cursor's API via OmniRoute:

```typescript
import { fetch } from "node-fetch";

async function cursorChat(prompt: string) {
  const res = await fetch("http://localhost:3000/v1/chat/completions", {
    method: "POST",
    body: JSON.stringify({
      model: "cursor-codex-1",  // alias from providers/oauth.ts
      messages: [{ role: "user", content: prompt }],
    }),
    headers: { "Content-Type": "application/json" },
  });

  const data = await res.json();
  console.log(data.choices[0].message.content);
}

cursorChat("Explain the Observer pattern in TypeScript.");

```

The router in [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts) detects the `cursor` provider, and [`src/shared/utils/cursorAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/cursorAuth.ts) injects the required `Authorization` header before forwarding to Cursor's upstream API.

## Cline-Specific Authentication

Cline uses a distinct header format with WorkOS-prefixed tokens:

```typescript
// src/shared/utils/clineAuth.ts
export function buildClineHeaders(token: string) {
  return {
    "Authorization": `Bearer workos:${token}`,
    "X-Cline-Version": "1.0",
  };
}

```

OmniRoute automatically applies this when [`tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tool-detector.ts) identifies Cline in `~/.cline/data/globalState.json` and routes to the `cline` provider.

## Adding New Coding Agents to OmniRoute

To extend OmniRoute with additional agents, modify four files:

1. **[`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts)** — Add provider entry with `authHeaders` and `compatiblePrefix`
2. **`src/shared/utils/{agent}Auth.ts`** — Implement custom header construction if needed
3. **[`src/lib/cli-helper/tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cli-helper/tool-detector.ts)** — Add detection path for binary and config
4. **[`src/shared/constants/agentSkills.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/agentSkills.ts)** — Expose orchestration skill if desired

The routing engine ([`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts)), translators, and UI ([`CliToolCard.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/CliToolCard.tsx)) automatically incorporate new providers without further changes.

## Summary

- **Provider registration** in [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) defines OAuth agents like Claude Code, Cursor, and Cline with model aliases and header logic
- **CLI detection** via [`src/lib/cli-helper/tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cli-helper/tool-detector.ts) scans for installed agents and creates tool descriptors for 33+ coding tools
- **Skill orchestration** through [`src/shared/constants/agentSkills.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/agentSkills.ts) exposes MCP endpoints for programmatic agent control
- **Zero-config routing** translates OpenAI-format requests to agent-specific protocols automatically using [`src/open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/services/combo.ts) and [`src/open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/executors/default.ts)
- **Per-agent authentication** handlers in `src/shared/utils/` (e.g., [`clineAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/clineAuth.ts), [`cursorAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cursorAuth.ts)) inject correct headers for each upstream API

## Frequently Asked Questions

### How does OmniRoute detect which coding agents are installed?

OmniRoute runs filesystem checks at startup through [`src/lib/cli-helper/tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cli-helper/tool-detector.ts), scanning standard installation paths like `~/.claude/profiles`, `~/.cursor/config.json`, and `~/.cline/data/globalState.json`. The detector uses `which` and `stat` operations to verify binary presence, then registers each found agent as an MCP tool in [`src/lib/acp/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/acp/registry.ts).

### Can I use OmniRoute with Claude Code without modifying its configuration?

Yes. Set the `ANTHROPIC_BASE_URL` environment variable to your OmniRoute instance before launching Claude Code. OmniRoute's `compatiblePrefix` mechanism (`anthropic-compatible-cc-`) automatically routes requests to the correct provider, and [`src/open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/executors/default.ts) handles Anthropic-version headers without client-side changes.

### What authentication does Cline require for OmniRoute integration?

Cline requires a WorkOS-format token stored in OmniRoute's credential manager. The [`src/shared/utils/clineAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/clineAuth.ts) module prefixes tokens with `workos:` and adds the `X-Cline-Version` header before forwarding requests. OmniRoute detects Cline's existing `~/.cline/data/globalState.json` to locate and use these credentials automatically.

### How do I add a custom coding agent that isn't in the default 33+ list?

Register the agent in [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) with its `authHeaders` function and `compatiblePrefix`. Add detection logic to [`src/lib/cli-helper/tool-detector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cli-helper/tool-detector.ts) pointing to the agent's config path or binary location. Optionally create a skill in [`src/shared/constants/agentSkills.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/agentSkills.ts) for MCP/A2A orchestration. The routing pipeline will recognize the new provider immediately.