Skip to content

Open Claude Code

Types

open-claude-code

Core Data Structures and Type Definitions¶

Message — Message Type System¶

// Top-level union type
type Message =
  | UserMessage
  | AssistantMessage
  | AttachmentMessage
  | ProgressMessage<any>
  | SystemMessage

// ---------- User Message ----------
type UserMessage = {
  type: 'user'
  content: ContentBlockParam[]
  origin?: MessageOrigin        // 'user' | 'tool_result' | 'hook' | ...
  permissionMode?: PermissionMode
  summarizeMetadata?: CompactMetadata
  isMeta?: boolean              // Visible to model but hidden in UI
  isVirtual?: boolean
}

// ---------- Assistant Message ----------
type AssistantMessage = {
  type: 'assistant'
  message: BetaMessage          // Raw response from Anthropic SDK
  requestId?: string
  apiError?: SDKAssistantMessageError
  isVirtual?: boolean
  costUSD?: number
  durationMs?: number
}

// ---------- System Message (15 subtypes) ----------
type SystemMessage = {
  type: 'system'
  subtype:
    | 'informational'           // General notification
    | 'permission_retry'        // Permission retry
    | 'bridge_status'           // Bridge status
    | 'scheduled_task_fire'     // Scheduled task triggered
    | 'stop_hook_summary'       // Stop hook summary
    | 'turn_duration'           // Turn duration
    | 'away_summary'            // Away summary
    | 'memory_saved'            // Memory saved
    | 'agents_killed'           // Agent terminated
    | 'api_metrics'             // API metrics
    | 'local_command'           // Local command result
    | 'compact_boundary'        // Compaction boundary
    | 'microcompact_boundary'   // Micro compaction boundary
    | 'api_error'               // API error
    | 'thinking'                // Thinking message
    | 'file_snapshot'           // File snapshot
  level?: 'info' | 'warning' | 'error'
  content: string
}

// ---------- Attachment Message ----------
type AttachmentMessage = {
  type: 'attachment'
  attachment: Attachment        // Files, directories, hook context, etc.
}

// ---------- Progress Message ----------
type ProgressMessage<P> = {
  type: 'progress'
  toolUseID: string
  data: P                       // Tool-specific progress data
}

Normalized Messages (for UI rendering)¶

// One message per content block
type NormalizedAssistantMessage<C> = {
  type: 'assistant'
  content: C                    // Single content block
  message: BetaMessage
  costUSD?: number
}

type NormalizedMessage =
  | NormalizedAssistantMessage<TextBlock>
  | NormalizedAssistantMessage<ThinkingBlock>
  | NormalizedAssistantMessage<ToolUseBlock>
  | NormalizedUserMessage
  | SystemMessage
  | AttachmentMessage

Command — Command Types¶

type CommandBase = {
  name: string
  description: string
  aliases?: string[]
  isHidden?: boolean
  isEnabled?: () => boolean
  availability?: ('claude-ai' | 'console')[]
  whenToUse?: string            // Description of usage scenarios for models
  disableModelInvocation?: boolean
  userInvocable?: boolean
  loadedFrom?: 'commands_DEPRECATED' | 'skills' | 'plugin' | 'managed' | 'bundled' | 'mcp'
  kind?: 'workflow'
  immediate?: boolean           // Skip queue, execute immediately
  isSensitive?: boolean         // Parameter redaction
}

type Command = CommandBase & (PromptCommand | LocalCommand | LocalJSXCommand)

ToolPermissionContext — Permission Context¶

type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
  alwaysAllowRules: ToolPermissionRulesBySource
  alwaysDenyRules: ToolPermissionRulesBySource
  alwaysAskRules: ToolPermissionRulesBySource
  isBypassPermissionsModeAvailable: boolean
  isAutoModeAvailable?: boolean
  shouldAvoidPermissionPrompts?: boolean
}>

type PermissionMode =
  | 'default'
  | 'plan'              // Read-only operations auto-allow
  | 'acceptEdits'       // Edit operations auto-allow
  | 'bypassPermissions' // Skip all permission checks
  | 'auto'              // Auto mode (classifier decides)

ToolProgressData — Tool Progress¶

type ToolProgressData =
  | BashProgress          // { type: 'bash', output: string }
  | ShellProgress
  | AgentToolProgress     // { type: 'agent', message: string }
  | MCPProgress           // { type: 'mcp', status: string }
  | WebSearchProgress     // { type: 'query_update' | 'search_results_received' }
  | REPLToolProgress
  | SkillToolProgress
  | TaskOutputProgress

Task — Task Types¶

type TaskType =
  | 'local_bash'
  | 'local_agent'
  | 'remote_agent'
  | 'in_process_teammate'
  | 'local_workflow'
  | 'monitor_mcp'
  | 'dream'

type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'killed'

type TaskStateBase = {
  id: string               // Prefix + 8 characters (b=bash, a=agent, r=remote...)
  type: TaskType
  status: TaskStatus
  description: string
  startTime: number
  endTime?: number
  outputFile: string
  outputOffset: number
  notified: boolean
}

AppState — Application State¶

type AppState = {
  messages: Message[]
  toolPermissionContext: ToolPermissionContext
  mcp: {
    clients: MCPServerConnection[]
    tools: MCPTool[]
    commands: Command[]
    resources: Record<string, ServerResource>
  }
  tasks: Record<string, TaskStateBase>
  effortValue: EffortValue         // 'low' | 'medium' | 'high' | 'max'
  fastMode: boolean
  thinkingEnabled: boolean
  kairosEnabled?: boolean
  // ... more fields
}

QuerySource — Query Source¶

type QuerySource =
  | 'repl_main_thread'       // Main interaction loop
  | 'compact'                // Compaction query
  | 'session_memory'         // Session memory
  | 'sdk'                    // SDK invocation
  | 'hook_agent'             // Hook agent
  | 'verification_agent'     // Verification agent
  | 'web_search_tool'        // Web search
  | 'dream'                  // Background thinking
  | (string & {})            // Extensible

OAuth Types¶

type OAuthTokens = {
  accessToken: string
  refreshToken?: string
  expiresAt?: number
}

type SubscriptionType = 'free' | 'pro' | 'max' | 'team' | 'enterprise'
type BillingType = 'free' | 'pro' | 'max' | 'team' | 'enterprise'
type RateLimitTier = 'standard' | 'high' | 'unlimited'

MCP Configuration Types¶

type ScopedMcpServerConfig = {
  type: 'stdio' | 'sse' | 'http' | 'ws'
  command?: string             // stdio command
  args?: string[]
  url?: string                 // HTTP/SSE/WS URL
  env?: Record<string, string>
  scope: ConfigScope
  // ... OAuth, headers, etc.
}

type ConfigScope =
  | 'local' | 'user' | 'project'
  | 'enterprise' | 'managed' | 'claudeai'
  | 'dynamic'

Hook Types¶

type HookEvent =
  | 'PreToolUse'
  | 'PostToolUse'
  | 'Notification'
  | 'Stop'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Setup'

type HookResult = {
  exitCode: number
  stdout: string
  stderr: string
  duration: number
  // Structured output (JSON)
  decision?: 'approve' | 'deny' | 'skip'
  reason?: string
  additionalContext?: string
}

type FilePersistenceOptions = { path: string; encoding?: BufferEncoding }
type FilePersistenceResult = { success: boolean; error?: string }

type SecureStorage = {
  read(key: string): Promise<string | null>
  write(key: string, value: string): Promise<void>
  clear(key: string): Promise<void>
  name: string
}