Entrypoints & Agent SDK

01 The Entrypoint Layer

The src/entrypoints/ directory is the boundary between the outside world and Claude Code's internals. It contains five surface-level files — cli.tsx, init.ts, mcp.ts, agentSdkTypes.ts, and sandboxTypes.ts — plus an sdk/ sub-directory that holds the serializable contract types. main.tsx sits one level up and is the single large Commander-based CLI handler that nearly every interactive and headless path flows through.

02 cli.tsx — The Bootstrap Dispatcher

src/entrypoints/cli.tsx is the actual binary entrypoint. It runs before any other module evaluation. Its design philosophy: load as little as possible for each fast-path.

Fast Paths (in order of detection)

// From cli.tsx — each fast-path is gated by a build-time feature() flag
if (feature('BRIDGE_MODE') && (args[0] === 'remote-control' || args[0] === 'rc'
    || args[0] === 'remote' || args[0] === 'sync' || args[0] === 'bridge')) {
  // Auth check → GrowthBook gate → policy limits → bridgeMain()
  const { bridgeMain } = await import('../bridge/bridgeMain.js');
  await bridgeMain(args.slice(1));
  return;
}

03 init.ts — Shared Initialization

src/entrypoints/init.ts is a memoized init() function shared by all non-trivial entrypoints. It is not called for fast-paths. It performs all the one-time setup that must happen before the first API call.

A separate initializeTelemetryAfterTrust() function is called only after the user has accepted the trust dialog. This separates consent-independent setup from consent-gated telemetry, and waits for remote managed settings to load before initializing OpenTelemetry exporters.

04 mcp.ts — Claude Code as an MCP Server

When invoked with claude --mcp, Claude Code runs as a standard Model Context Protocol server over stdio. This exposes all of Claude Code's tools (Bash, Edit, Read, WebFetch, etc.) to other MCP clients — editors, agents, or automation scripts can call them directly without spawning a full REPL.

// src/entrypoints/mcp.ts
const server = new Server(
  { name: 'claude/tengu', version: MACRO.VERSION },
  { capabilities: { tools: {} } }
)

// ListTools: enumerate every Claude Code tool with its Zod-derived JSON schema
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: await Promise.all(tools.map(async tool => ({
    ...tool,
    description: await tool.prompt(...),
    inputSchema: zodToJsonSchema(tool.inputSchema),
  })))
}))

// CallTool: validate input, check permissions, execute, return result
server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
  const tool = findToolByName(tools, params.name)
  return await tool.call(params.arguments, toolUseContext, ...)
})

05 agentSdkTypes.ts — The Public SDK Contract

src/entrypoints/agentSdkTypes.ts is the main export of the Agent SDK package. It re-exports the full public API from three sub-modules and declares the top-level functions that SDK consumers call. All function bodies throw 'not implemented' in this file — the actual implementations are injected at runtime by the SDK transport layer.

Module Structure

Top-Level SDK Functions

// V1 API (stable) — headless one-shot query
export function query(params: {
  prompt: string | AsyncIterable<SDKUserMessage>
  options?: Options
}): Query

// V2 API (@alpha) — persistent multi-turn sessions
export function unstable_v2_createSession(options: SDKSessionOptions): SDKSession
export function unstable_v2_resumeSession(sessionId: string, options: SDKSessionOptions): SDKSession
export async function unstable_v2_prompt(message: string, options: SDKSessionOptions): Promise<SDKResultMessage>

// Session management
export async function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>
export async function getSessionInfo(sessionId: string): Promise<SDKSessionInfo | undefined>
export async function getSessionMessages(sessionId: string): Promise<SessionMessage[]>
export async function renameSession(sessionId: string, title: string): Promise<void>
export async function tagSession(sessionId: string, tag: string | null): Promise<void>
export async function forkSession(sessionId: string, options?: ForkSessionOptions): Promise<ForkSessionResult>

// In-process MCP server
export function createSdkMcpServer(options: { name: string; tools: SdkMcpToolDefinition[] }): McpSdkServerConfigWithInstance
export function tool<S>(name, description, schema, handler): SdkMcpToolDefinition<S>

06 The Control Protocol (SDK Builders)

External SDK implementations (like the Python claude-code-sdk) communicate with the Claude Code process via a JSON-based control protocol layered over stdio. The schemas are defined in sdk/controlSchemas.ts.

Control Request Subtypes

// Initialize request — sent by SDK to start a session
{
  subtype: "initialize",
  hooks: {
    "PreToolUse": [{ hookCallbackIds: ["my-hook"], matcher: "Bash" }]
  },
  sdkMcpServers: ["my-server"],
  systemPrompt: "You are a coding assistant.",
  agents: {
    "reviewer": { description: "Reviews code changes", ... }
  }
}

// Initialize response — returned by CLI
{
  commands: [...],    // available slash commands
  agents: [...],      // available agent types
  models: [...],      // available models
  account: {...},     // account info
  pid: 12345          // @internal CLI PID for tmux socket isolation
}

07 Hook Events — The SDK Observer Pattern

The SDK exposes a rich hook system that lets external hosts observe and intercept Claude Code's lifecycle. There are 26 named hook events, defined in sdk/coreTypes.ts:

export const HOOK_EVENTS = [
  // Tool execution
  'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
  // Permission flow
  'PermissionRequest', 'PermissionDenied',
  // Session lifecycle
  'SessionStart', 'SessionEnd', 'Setup',
  // Turn lifecycle
  'Stop', 'StopFailure',
  // Context management
  'PreCompact', 'PostCompact',
  // Agent/swarm lifecycle
  'SubagentStart', 'SubagentStop', 'TeammateIdle',
  'TaskCreated', 'TaskCompleted',
  // Notifications and user input
  'Notification', 'UserPromptSubmit',
  // Config changes
  'ConfigChange', 'InstructionsLoaded', 'CwdChanged', 'FileChanged',
  // Elicitation
  'Elicitation', 'ElicitationResult',
  // Worktree
  'WorktreeCreate', 'WorktreeRemove',
] as const

Every hook fires with a BaseHookInput that includes session_id, transcript_path, cwd, agent_id (if inside a subagent), and agent_type. Each event adds its own specific fields on top.

08 Daemon & Bridge Mode (@internal)

For advanced host architectures (desktop apps, CI systems, claude.ai integrations), agentSdkTypes.ts also exports @internal primitives:

Scheduled Tasks / Cron

// Watch .claude/scheduled_tasks.json and yield fire/missed events
export function watchScheduledTasks(opts: {
  dir: string
  signal: AbortSignal
  getJitterConfig?: () => CronJitterConfig
}): ScheduledTasksHandle

// ScheduledTasksHandle — drain with for await
{
  events(): AsyncGenerator<ScheduledTaskEvent>  // fire | missed
  getNextFireTime(): number | null               // epoch ms of next scheduled run
}

This lets daemon processes own the scheduler in the parent process. When a task fires, the daemon spawns a query() subprocess — if it crashes, the daemon can respawn it while the schedule continues.

Remote Control / Bridge

// Connect the local machine as a claude.ai remote-control environment
export async function connectRemoteControl(opts: ConnectRemoteControlOptions):
  Promise<RemoteControlHandle | null>

// RemoteControlHandle — two-way bridge over WebSocket
{
  sessionUrl: string
  environmentId: string
  bridgeSessionId: string
  write(msg: SDKMessage): void         // pipe query() yields in
  sendResult(): void                     // signal turn complete
  inboundPrompts(): AsyncGenerator<...>  // read user messages from claude.ai
  controlRequests(): AsyncGenerator<...> // interrupt, set_model, etc.
  permissionResponses(): AsyncGenerator<...>
  onStateChange(cb): void               // ready | connected | reconnecting | failed
  teardown(): Promise<void>
}

09 sandboxTypes.ts — Process Isolation Config

src/entrypoints/sandboxTypes.ts is the single source of truth for sandbox configuration types. Both the SDK and the settings validation system import from here. It is exported through agentSdkTypes.ts so SDK consumers can configure sandboxing.

// SandboxSettings — full configuration for process-level isolation
{
  enabled: boolean
  failIfUnavailable: boolean    // hard-gate for managed deployments
  autoAllowBashIfSandboxed: boolean
  allowUnsandboxedCommands: boolean
  network: {
    allowedDomains: string[]
    allowManagedDomainsOnly: boolean  // enterprise: only managed domains
    allowUnixSockets: string[]        // macOS only
    allowLocalBinding: boolean
    httpProxyPort: number
    socksProxyPort: number
  }
  filesystem: {
    allowWrite: string[]      // merged with Edit() allow rules
    denyWrite: string[]       // merged with Edit() deny rules
    denyRead: string[]
    allowRead: string[]       // re-allow within denyRead regions
    allowManagedReadPathsOnly: boolean
  }
}

10 main.tsx — Invocation Modes

Once cli.tsx falls through to main.tsx, the Commander-based CLI handles the remaining invocation modes. Key ones:

11 Complete Invocation Flow