services — Backend Service Layer

Backend Service Layer

Comprehensive backend integration and lifecycle management. Orchestrates API communication, MCP protocol, LSP language servers, session memory, message compaction, OAuth authentication, rate limiting, analytics/telemetry, and remote settings.

Services

130

Files

~54k

Lines

TypeScript

Language

🔵 API Integration 🟢 MCP Protocol 🟡 OAuth & Rate Limiting 🔴 Telemetry

💡 Think of it this way: If Claude Code were a company, the services/ module is the entire back-office infrastructure. The API service is the mail room — every outgoing request and incoming response passes through it. OAuth is the security desk checking badges at the door. MCP is the intercom system connecting departments to outside vendors. Rate limiting is the traffic controller preventing hallway congestion. Analytics is the accounting department tracking every transaction. Session memory is the filing cabinet that remembers past conversations. No user-facing feature works without these back-office departments running smoothly behind the scenes.

Architecture

The services layer sits between the UI/REPL shell and external providers. Each service is a focused module with a clean boundary — services communicate through typed interfaces, not direct imports of each other's internals.

flowchart TB
  subgraph UI["UI / REPL Layer"]
    REPL["REPL Input"]
    Ink["Ink Components"]
  end

  subgraph Core["services/"]
    direction TB
    API["api/\nAnthropic Client"]
    MCP["mcp/\nMCP Protocol"]
    LSP["lsp/\nLanguage Servers"]
    Compact["compact/\nMessage Compaction"]
    Memory["SessionMemory/\nSession State"]
    Extract["extractMemories/\nMemory Extraction"]
    Token["tokenEstimation/\nToken Counter"]
  end

  subgraph Auth["Auth & Governance"]
    OAuth["oauth/\nAuthentication"]
    Policy["policyLimits/\nRate Limiting"]
    Settings["mcpSettings/\nRemote Config"]
  end

  subgraph Telemetry["Observability"]
    Analytics["analytics/\nGrowthBook"]
    Statsig["statsig/\nFeature Flags"]
    Sentry["sentry/\nError Tracking"]
  end

  subgraph External["External Systems"]
    Anthropic["Anthropic API"]
    MCPServers["MCP Servers"]
    LSPBin["Language Servers"]
  end

  REPL --> API
  REPL --> MCP
  Ink --> Memory
  API --> OAuth
  API --> Policy
  API --> Token
  API --> Compact
  API --> Anthropic
  MCP --> MCPServers
  LSP --> LSPBin
  Memory --> Extract
  API --> Analytics
  API --> Sentry
  Settings --> Statsig

API Call Sequence

Trace a single query from the REPL through authentication, rate limiting, streaming, and error handling — the critical hot path of every Claude Code interaction.

sequenceDiagram
  participant User as REPL / User
  participant API as api/index.ts
  participant OAuth as oauth/
  participant Policy as policyLimits/
  participant Token as tokenEstimation/
  participant Compact as compact/
  participant Anthropic as Anthropic API
  participant Analytics as analytics/
  participant Sentry as sentry/

  User->>API: sendMessage(query)
  API->>OAuth: validateToken()
  OAuth-->>API: token valid
  API->>Policy: checkRateLimit()
  Policy-->>API: allowed
  API->>Token: estimateTokens(messages)
  Token-->>API: tokenCount
  alt Token budget exceeded
    API->>Compact: compactMessages(history)
    Compact-->>API: compactedHistory
  end
  API->>Anthropic: POST /messages (stream)
  loop SSE chunks
    Anthropic-->>API: delta chunk
    API-->>User: stream chunk to UI
  end
  API->>Analytics: trackUsage(tokens, latency)
  alt Error occurred
    API->>Sentry: captureException(err)
    API-->>User: formatted error
  end
  API-->>User: complete response

🚶 Step-by-Step Narrated Walkthrough

Follow a single user query from the REPL through the API service and back as it flows through the entire services pipeline:

REPL Capture — The user types a query in the terminal. The REPL component serialises it into a UserMessage and dispatches it to the API service.
OAuth Gate — oauth/ validates the stored access token. If expired, it silently refreshes via the refresh-token flow before proceeding.
Rate-Limit Check — policyLimits/ evaluates per-minute and daily token quotas. If the user is over budget, the request is queued with exponential back-off.
Token Estimation — tokenEstimation/ runs a fast BPE approximation over the full message history to calculate the context window footprint.
Compaction Decision — If estimated tokens exceed the model's context window minus a safety margin, compact/ summarises older turns, preserving tool-use blocks and system prompts.
Request Assembly — api/index.ts constructs the final HTTP payload: model, temperature, system prompt, tools array, and the (possibly compacted) message history.
Streaming POST — The request is sent to the Anthropic Messages API with stream: true. An SSE parser begins consuming content_block_delta events.
Chunk Relay — Each delta chunk is forwarded to the Ink renderer in real time. Tool-use blocks are detected and dispatched to the tool executor as soon as the block closes.
Analytics Emission — On stream completion, analytics/ records token counts, latency percentiles, model version, and GrowthBook experiment assignments.
Session Memory Update — SessionMemory/ appends the assistant turn. extractMemories/ scans the response for facts worth persisting to the CLAUDE.md memory file.

Key Components

Component	Path	Purpose	Key Exports
API Client	`api/index.ts`	Core Anthropic HTTP client, request/response lifecycle	`sendMessage`, `streamChat`
API Types	`api/types.ts`	Request/response type definitions for the Message Rendering System" class="xref">Messages API	`ApiRequest`, `ApiResponse`
MCP Client	`mcp/client.ts`	Model Context Protocol client — connects to external tool servers	`McpClient`, `connectServer`
MCP Registry	`mcp/registry.ts`	Discovers, registers, and manages MCP server lifecycles	`McpRegistry`
LSP Manager	`lsp/manager.ts`	Spawns and manages language-server processes (TS, Python, etc.)	`LspManager`
LSP Diagnostics	`lsp/diagnostics.ts`	Collects and formats LSP diagnostics for the assistant context	`getDiagnostics`
Message Compactor	`compact/index.ts`	Summarises conversation history to fit context windows	`compactMessages`
Session Memory	`SessionMemory/index.ts`	Persistent session state — turns, tool results, timestamps	`SessionMemory`
Memory Extractor	`extractMemories/index.ts`	Extracts durable facts from conversations into CLAUDE.md	`extractMemories`
Token Estimator	`tokenEstimation/index.ts`	Fast BPE-based token counting without a full tokeniser	`estimateTokens`
OAuth Service	`oauth/index.ts`	OAuth 2.0 PKCE flow — login, token refresh, logout	`authenticate`, `refreshToken`
Rate Limiter	`policyLimits/index.ts`	Enforces per-user and per-org rate limits with back-off	`checkLimit`, `RateLimiter`
GrowthBook Analytics	`analytics/growthbook.ts`	Feature flags and A/B experiment evaluation	`GrowthBookClient`
Statsig	`statsig/index.ts`	Real-time feature-gate evaluation and dynamic config	`StatsigClient`
Sentry Integration	`sentry/index.ts`	Error tracking, breadcrumbs, and performance transactions	`initSentry`, `captureException`

Sub-Modules

api/

Anthropic Messages API client — streaming, retries, and error mapping.

SSE-based streaming with back-pressure
Automatic retry with exponential back-off
Token usage tracking per request
Structured error classification

mcp/

Model Context Protocol — tool-server discovery, connection, and invocation.

JSON-RPC transport over stdio & SSE
Dynamic tool registration from servers
Server lifecycle management
Permission-scoped tool execution

lsp/

Language Server Protocol — code intelligence for diagnostics and completions.

Multi-language server management
Real-time diagnostics collection
Workspace symbol resolution
Hover & go-to-definition support

Directory Map

Source tree for services/

services/
├── api/                        ← Anthropic API client & streaming
│   ├── index.ts                ← Main client: sendMessage, streamChat
│   ├── types.ts                ← Request/response type definitions
│   ├── errors.ts               ← API error classification
│   └── retry.ts                ← Exponential back-off logic
├── mcp/                        ← Model Context Protocol integration
│   ├── client.ts               ← MCP client transport layer
│   ├── registry.ts             ← Server discovery & lifecycle
│   ├── permissions.ts          ← Tool permission scoping
│   └── types.ts                ← MCP type definitions
├── lsp/                        ← Language Server Protocol management
│   ├── manager.ts              ← Process spawn & lifecycle
│   ├── diagnostics.ts          ← Diagnostic collection & formatting
│   └── capabilities.ts         ← Server capability negotiation
├── compact/                    ← Message history compaction
│   ├── index.ts                ← Compaction entry point
│   ├── strategy.ts             ← Summarisation strategies
│   └── preserve.ts             ← Block-preservation rules
├── SessionMemory/              ← Persistent session state
│   ├── index.ts                ← Memory read/write interface
│   └── store.ts                ← On-disk session storage
├── extractMemories/            ← Durable fact extraction
│   ├── index.ts                ← Extraction pipeline
│   └── patterns.ts             ← Fact-detection heuristics
├── tokenEstimation/            ← Fast token counting
│   └── index.ts                ← BPE approximation engine
├── oauth/                      ← OAuth 2.0 PKCE authentication
│   ├── index.ts                ← Auth flow orchestration
│   ├── pkce.ts                 ← Code challenge generation
│   └── tokens.ts               ← Token storage & refresh
├── policyLimits/               ← Rate limiting & quotas
│   ├── index.ts                ← Limit checker
│   └── budgets.ts              ← Per-org budget definitions
├── analytics/                  ← Usage tracking & experiments
│   ├── growthbook.ts           ← GrowthBook A/B testing client
│   ├── telemetry.ts            ← Event emission pipeline
│   └── schemas.ts              ← Analytics event schemas
├── statsig/                    ← Feature flags & dynamic config
│   └── index.ts                ← Statsig SDK wrapper
├── sentry/                     ← Error tracking
│   └── index.ts                ← Sentry init & helpers
├── mcpSettings/                ← Remote MCP configuration
│   └── index.ts                ← Settings fetch & cache
├── costTracker/                ← API cost accounting
│   └── index.ts                ← Running cost tally
├── notifier/                   ← System notifications
│   └── index.ts                ← Desktop / terminal alerts
├── autoUpdater/                ← Self-update mechanism
│   └── index.ts                ← Version check & download
├── doctor/                     ← Environment diagnostics
│   └── index.ts                ← Health-check suite
├── fileWatcher/                ← Filesystem change detection
│   └── index.ts                ← Debounced file-change events
└── configLoader/               ← Configuration resolution
    └── index.ts                ← Layered config merge

Configuration

Services are configured through environment variables, settings.json, and runtime flags. The table below lists the most important knobs.

Setting	Source	Default	Description
`ANTHROPIC_API_KEY`	env	required	API key for Anthropic Messages endpoint
`ANTHROPIC_BASE_URL`	env	`https://api.anthropic.com`	Override base URL (proxies, testing)
`CLAUDE_CODE_MAX_TOKENS`	env	`128000`	Maximum context-window token budget
`CLAUDE_CODE_DISABLE_STREAMING`	env	`false`	Force non-streaming mode (debugging)
`MCP_SERVERS`	settings.json	`[]`	Array of MCP server configurations to auto-start
`LSP_ENABLED`	settings.json	`true`	Enable/disable language-server diagnostics
`COMPACT_THRESHOLD`	settings.json	`0.85`	Context-window fill ratio that triggers compaction
`RATE_LIMIT_RPM`	settings.json	`60`	Max requests per minute before queueing
`GROWTHBOOK_CLIENT_KEY`	env	optional	GrowthBook SDK key for feature-flag evaluation
`SENTRY_DSN`	env	optional	Sentry Data Source Name for error reporting
`OAUTH_REDIRECT_PORT`	env	`19282`	Local port for OAuth redirect callback
`SESSION_MEMORY_DIR`	env	`~/.claude/sessions`	Directory for persistent session storage