# theblixguy/xcode-copilot-server architecture

> Architecture diagram of the GitHub repository theblixguy/xcode-copilot-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theblixguy/xcode-copilot-server
- Repository: https://github.com/theblixguy/xcode-copilot-server

## Overview

xcode-copilot-server is a local API proxy that lets Xcode use GitHub Copilot through OpenAI-, Anthropic-, and OpenAI Responses-compatible provider modes. The principal flow is CLI startup and configuration, provider route registration, request/session preparation, Copilot streaming, and—where enabled—tool calls bridged back to Xcode. README-described OpenAI MCP access and launchd operation are included; their detailed runtime wiring is not fully excerpted, so uncertain links are omitted. The graph emphasizes documented and indexed relationships rather than inferring calls from naming.

Main entry points: [`proxy-server/src/providers/claude/provider.ts`](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/provider.ts) (Claude API), [`proxy-server/src/providers/codex/provider.ts`](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/provider.ts) (Codex API), [`proxy-server/src/startup.ts`](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/startup.ts) (Server startup), [`proxy-server/src/providers/openai/provider.ts`](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/openai/provider.ts) (OpenAI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server entry"]
  node_cli["CLI<br/>[index.ts]"]
  node_startup["Server startup<br/>[startup.ts]"]
  node_context["App context<br/>[context.ts]"]
end

subgraph group_providers["API providers"]
  node_openai["OpenAI API<br/>[provider.ts]"]
  node_claude["Claude API<br/>[provider.ts]"]
  node_codex["Codex API<br/>[provider.ts]"]
  node_toolresults["Provider tool results<br/>[tool-results.ts]"]
  node_codextoolresults["Codex tool results<br/>[tool-results.ts]"]
end

subgraph group_stream["Session and streaming"]
  node_sessionconfig["Session configuration<br/>[session-config.ts]"]
  node_prompt["Prompt preparation<br/>[prompt-utils.ts]"]
  node_continuation["Conversation continuation<br/>[continuation.ts]"]
  node_orchestrator["Stream orchestration"]
  node_conversation[("Conversation manager")]
  node_sharedstream["Streaming core<br/>[streaming-core.ts]"]
  node_claudestream["Claude streaming<br/>[streaming.ts]"]
  node_codexstream["Codex streaming<br/>[streaming.ts]"]
end

subgraph group_bridge["Tool bridge"]
  node_bridgeroutes["MCP bridge routes<br/>[routes.ts]"]
  node_bridgemanager["Bridge registration<br/>[index.ts]"]
  node_bridgestate[("Bridge state<br/>[state.ts]")]
  node_router["Tool call router<br/>[tool-router.ts]"]
end

subgraph group_ops["Configuration and operations"]
  node_config["Configuration<br/>[config.ts]"]
  node_validators["CLI validation<br/>[cli-validators.ts]"]
  node_settings["Settings patchers<br/>[index.ts]"]
  node_claudesettings["Claude settings<br/>[claude.ts]"]
  node_codexsettings["Codex settings<br/>[codex.ts]"]
  node_launchd["Launchd agent<br/>[agent.ts]"]
end

node_xcode(("Xcode"))
node_copilot{{"Copilot SDK service"}}
node_mcp{{"Xcode MCP tools"}}

node_xcode -.->|"sends completions"| node_openai
node_xcode -.->|"sends requests"| node_claude
node_xcode -.->|"sends responses"| node_codex
node_cli -->|"starts server"| node_startup
node_cli -->|"parses options"| node_validators
node_startup -->|"loads config"| node_config
node_startup -->|"builds context"| node_context
node_startup -->|"patches settings"| node_settings
node_startup -->|"registers agent"| node_launchd
node_openai -->|"configures session"| node_sessionconfig
node_claude -->|"configures session"| node_sessionconfig
node_codex -->|"configures session"| node_sessionconfig
node_claude -->|"filters prompt"| node_prompt
node_codex -->|"filters prompt"| node_prompt
node_claude -->|"handles continuation"| node_continuation
node_codex -->|"handles continuation"| node_continuation
node_claude -->|"selects conversation"| node_conversation
node_codex -->|"selects conversation"| node_conversation
node_claude -->|"resolves bridge"| node_bridgemanager
node_codex -->|"resolves bridge"| node_bridgemanager
node_claude -->|"orchestrates stream"| node_orchestrator
node_codex -->|"orchestrates stream"| node_orchestrator
node_orchestrator -->|"updates conversation"| node_conversation
node_claude -->|"handles stream"| node_claudestream
node_codex -->|"handles stream"| node_codexstream
node_claudestream -->|"uses stream core"| node_sharedstream
node_codexstream -->|"uses stream core"| node_sharedstream
node_openai -.->|"serves Copilot"| node_copilot
node_claude -.->|"serves Copilot"| node_copilot
node_codex -.->|"serves Copilot"| node_copilot
node_bridgemanager -->|"registers routes"| node_bridgeroutes
node_bridgeroutes -->|"registers tool request"| node_router
node_conversation -->|"creates state"| node_bridgestate
node_bridgestate -->|"owns router"| node_router
node_claude -->|"resolves results"| node_toolresults
node_codex -->|"resolves results"| node_codextoolresults
node_settings -->|"delegates patching"| node_claudesettings
node_settings -->|"delegates patching"| node_codexsettings
node_codexsettings -->|"sets launchctl vars"| node_launchd
node_openai -.->|"accesses Xcode tools"| node_mcp

click node_cli "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/index.ts"
click node_startup "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/startup.ts"
click node_context "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/context.ts"
click node_config "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/config.ts"
click node_validators "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/cli-validators.ts"
click node_openai "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/openai/provider.ts"
click node_claude "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/provider.ts"
click node_codex "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/provider.ts"
click node_sessionconfig "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/session-config.ts"
click node_prompt "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/prompt-utils.ts"
click node_continuation "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/continuation.ts"
click node_orchestrator "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/streaming-orchestrator.ts"
click node_conversation "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/conversation-manager.ts"
click node_sharedstream "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/streaming-core.ts"
click node_claudestream "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/streaming.ts"
click node_codexstream "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/streaming.ts"
click node_toolresults "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/tool-results.ts"
click node_codextoolresults "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/tool-results.ts"
click node_bridgeroutes "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/routes.ts"
click node_bridgemanager "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/index.ts"
click node_bridgestate "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/state.ts"
click node_router "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/tool-router.ts"
click node_settings "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/index.ts"
click node_claudesettings "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/claude.ts"
click node_codexsettings "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/codex.ts"
click node_launchd "https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/launchd/agent.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_startup,node_context toneBlue
class node_openai,node_claude,node_codex,node_toolresults,node_codextoolresults toneAmber
class node_sessionconfig,node_prompt,node_continuation,node_orchestrator,node_conversation,node_sharedstream,node_claudestream,node_codexstream toneMint
class node_bridgeroutes,node_bridgemanager,node_bridgestate,node_router toneRose
class node_config,node_validators,node_settings,node_claudesettings,node_codexsettings,node_launchd,node_xcode,node_copilot,node_mcp toneIndigo
```

## Components

### Server entry

- [CLI](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/index.ts): `proxy-server/src/index.ts`
- [Server startup](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/startup.ts): `proxy-server/src/startup.ts`
- [App context](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/context.ts): `proxy-server/src/context.ts`

### API providers

- [OpenAI API](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/openai/provider.ts): `proxy-server/src/providers/openai/provider.ts`
- [Claude API](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/provider.ts): `proxy-server/src/providers/claude/provider.ts`
- [Codex API](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/provider.ts): `proxy-server/src/providers/codex/provider.ts`
- [Provider tool results](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/tool-results.ts): `proxy-server/src/providers/claude/tool-results.ts`
- [Codex tool results](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/tool-results.ts): `proxy-server/src/providers/codex/tool-results.ts`

### Session and streaming

- [Session configuration](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/session-config.ts): `proxy-server/src/providers/shared/session-config.ts`
- [Prompt preparation](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/prompt-utils.ts): `proxy-server/src/providers/shared/prompt-utils.ts`
- [Conversation continuation](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/continuation.ts): `proxy-server/src/providers/shared/continuation.ts`
- [Stream orchestration](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/streaming-orchestrator.ts): `proxy-server/src/providers/shared/streaming-orchestrator.ts`
- [Conversation manager](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/conversation-manager.ts): `proxy-server/src/conversation-manager.ts`
- [Streaming core](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/shared/streaming-core.ts): `proxy-server/src/providers/shared/streaming-core.ts`
- [Claude streaming](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/claude/streaming.ts): `proxy-server/src/providers/claude/streaming.ts`
- [Codex streaming](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/providers/codex/streaming.ts): `proxy-server/src/providers/codex/streaming.ts`

### Tool bridge

- [MCP bridge routes](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/routes.ts): `proxy-server/src/tool-bridge/routes.ts`
- [Bridge registration](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/index.ts): `proxy-server/src/tool-bridge/index.ts`
- [Bridge state](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/state.ts): `proxy-server/src/tool-bridge/state.ts`
- [Tool call router](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/tool-bridge/tool-router.ts): `proxy-server/src/tool-bridge/tool-router.ts`

### Configuration and operations

- [Configuration](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/config.ts): `proxy-server/src/config.ts`
- [CLI validation](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/cli-validators.ts): `proxy-server/src/cli-validators.ts`
- [Settings patchers](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/index.ts): `proxy-server/src/settings-patcher/index.ts`
- [Claude settings](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/claude.ts): `proxy-server/src/settings-patcher/claude.ts`
- [Codex settings](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/settings-patcher/codex.ts): `proxy-server/src/settings-patcher/codex.ts`
- [Launchd agent](https://github.com/theblixguy/xcode-copilot-server/blob/main/proxy-server/src/launchd/agent.ts): `proxy-server/src/launchd/agent.ts`

### Other components

- **Xcode**
- **Copilot SDK service**
- **Xcode MCP tools**

## Connections

- Xcode → OpenAI API: sends completions
- Xcode → Claude API: sends requests
- Xcode → Codex API: sends responses
- CLI → Server startup: starts server (evidence: `proxy-server/src/index.ts`)
- CLI → CLI validation: parses options (evidence: `proxy-server/src/index.ts`)
- Server startup → Configuration: loads config (evidence: `proxy-server/src/startup.ts`)
- Server startup → App context: builds context (evidence: `proxy-server/src/startup.ts`)
- Server startup → Settings patchers: patches settings (evidence: `proxy-server/src/startup.ts`)
- Server startup → Launchd agent: registers agent (evidence: `proxy-server/src/startup.ts`)
- OpenAI API → Session configuration: configures session (evidence: `proxy-server/src/providers/openai/provider.ts`)
- Claude API → Session configuration: configures session (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Session configuration: configures session (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude API → Prompt preparation: filters prompt (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Prompt preparation: filters prompt (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude API → Conversation continuation: handles continuation (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Conversation continuation: handles continuation (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude API → Conversation manager: selects conversation (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Conversation manager: selects conversation (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude API → Bridge registration: resolves bridge (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Bridge registration: resolves bridge (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude API → Stream orchestration: orchestrates stream (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Stream orchestration: orchestrates stream (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Stream orchestration → Conversation manager: updates conversation (evidence: `proxy-server/src/providers/shared/streaming-orchestrator.ts`)
- Claude API → Claude streaming: handles stream (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Codex streaming: handles stream (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Claude streaming → Streaming core: uses stream core (evidence: `proxy-server/src/providers/claude/streaming.ts`)
- Codex streaming → Streaming core: uses stream core (evidence: `proxy-server/src/providers/codex/streaming.ts`)
- OpenAI API → Copilot SDK service: serves Copilot
- Claude API → Copilot SDK service: serves Copilot
- Codex API → Copilot SDK service: serves Copilot
- Bridge registration → MCP bridge routes: registers routes (evidence: `proxy-server/src/tool-bridge/index.ts`)
- MCP bridge routes → Tool call router: registers tool request (evidence: `proxy-server/src/tool-bridge/routes.ts`)
- Conversation manager → Bridge state: creates state (evidence: `proxy-server/src/conversation-manager.ts`)
- Bridge state → Tool call router: owns router (evidence: `proxy-server/src/tool-bridge/state.ts`)
- Claude API → Provider tool results: resolves results (evidence: `proxy-server/src/providers/claude/provider.ts`)
- Codex API → Codex tool results: resolves results (evidence: `proxy-server/src/providers/codex/provider.ts`)
- Settings patchers → Claude settings: delegates patching (evidence: `proxy-server/src/settings-patcher/index.ts`)
- Settings patchers → Codex settings: delegates patching (evidence: `proxy-server/src/settings-patcher/index.ts`)
- Codex settings → Launchd agent: sets launchctl vars (evidence: `proxy-server/src/settings-patcher/codex.ts`)
- OpenAI API → Xcode MCP tools: accesses Xcode tools
