# guess/claude_code architecture

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

- Interactive diagram: https://gitdiagram.com/guess/claude_code
- Repository: https://github.com/guess/claude_code

## Overview

Claude Code for Elixir is an SDK for running Claude Code CLI agents as OTP sessions and consuming their responses as Elixir streams. The principal workflow starts or queries a session, sends a prompt through the session process and CLI adapter, parses streamed JSON messages, and exposes results to the application. The README also documents in-process tools and hooks, session history and controls, subagents, structured output, distributed adapters, and plugin support. Several subsystem links are documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`lib/claude_code/session.ex`](https://github.com/guess/claude_code/blob/main/lib/claude_code/session.ex) (Session API), [`lib/claude_code/adapter.ex`](https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter.ex) (CLI adapters), [`lib/claude_code/cli/parser.ex`](https://github.com/guess/claude_code/blob/main/lib/claude_code/cli/parser.ex) (Stream parser), [`lib/claude_code.ex`](https://github.com/guess/claude_code/blob/main/lib/claude_code.ex) (SDK entry points)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Agent API"]
  node_sdk["SDK entry points<br/>[claude_code.ex]"]
  node_session_api["Session API<br/>[session.ex]"]
  node_stream["Stream helpers<br/>[stream.ex]"]
end

subgraph group_runtime["Session Runtime"]
  node_session_server["Session process<br/>[server.ex]"]
  node_options["Session options<br/>[options.ex]"]
  node_adapter["CLI adapters<br/>[adapter.ex]"]
  node_port_adapter["Port adapter<br/>[port.ex]"]
  node_node_adapter["Remote adapter<br/>[node.ex]"]
end

subgraph group_protocol["CLI Protocol"]
  node_parser["Stream parser<br/>[parser.ex]"]
  node_messages["Message types"]
  node_content["Content blocks<br/>[content.ex]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_hooks["Hooks and permissions<br/>[hook.ex]"]
  node_mcp["In-process MCP tools<br/>[server.ex]"]
  node_mcp_router["MCP request router<br/>[router.ex]"]
  node_agents["Subagent definitions<br/>[agent.ex]"]
end

subgraph group_operations["Session Operations"]
  node_history["Conversation history<br/>[history.ex]"]
  node_sandbox["Remote sandboxes<br/>[sandbox.ex]"]
  node_plugins["Plugins<br/>[plugin.ex]"]
end

node_app(("Elixir application"))
node_cli["Claude CLI"]
node_cli_service(("Claude service"))

node_app -->|"starts or queries"| node_sdk
node_sdk -->|"starts sessions"| node_session_api
node_session_api -.->|"manages session"| node_session_server
node_session_server -.->|"dispatches queries"| node_adapter
node_adapter -.->|"uses port transport"| node_port_adapter
node_adapter -.->|"supports remote"| node_node_adapter
node_port_adapter -.->|"runs CLI"| node_cli
node_node_adapter -.->|"offloads CLI"| node_cli
node_cli -->|"emits stream JSON"| node_parser
node_parser -->|"parses messages"| node_messages
node_parser -->|"parses blocks"| node_content
node_session_api -->|"streams responses"| node_stream
node_stream -->|"yields results"| node_app
node_cli -->|"requests callbacks"| node_hooks
node_cli -->|"sends tool requests"| node_mcp_router
node_mcp_router -->|"dispatches tools"| node_mcp
node_app -->|"defines tools"| node_mcp
node_app -->|"configures hooks"| node_hooks
node_app -->|"configures subagents"| node_agents
node_session_api -.->|"reads history"| node_history
node_app -.->|"uses distributed sessions"| node_sandbox
node_app -.->|"uses plugins"| node_plugins

click node_sdk "https://github.com/guess/claude_code/blob/main/lib/claude_code.ex"
click node_session_api "https://github.com/guess/claude_code/blob/main/lib/claude_code/session.ex"
click node_stream "https://github.com/guess/claude_code/blob/main/lib/claude_code/stream.ex"
click node_session_server "https://github.com/guess/claude_code/blob/main/lib/claude_code/session/server.ex"
click node_options "https://github.com/guess/claude_code/blob/main/lib/claude_code/options.ex"
click node_adapter "https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter.ex"
click node_port_adapter "https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter/port.ex"
click node_node_adapter "https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter/node.ex"
click node_parser "https://github.com/guess/claude_code/blob/main/lib/claude_code/cli/parser.ex"
click node_messages "https://github.com/guess/claude_code/blob/main/lib/claude_code/message/assistant_message.ex"
click node_content "https://github.com/guess/claude_code/blob/main/lib/claude_code/content.ex"
click node_hooks "https://github.com/guess/claude_code/blob/main/lib/claude_code/hook.ex"
click node_mcp "https://github.com/guess/claude_code/blob/main/lib/claude_code/mcp/server.ex"
click node_mcp_router "https://github.com/guess/claude_code/blob/main/lib/claude_code/mcp/router.ex"
click node_agents "https://github.com/guess/claude_code/blob/main/lib/claude_code/agent.ex"
click node_history "https://github.com/guess/claude_code/blob/main/lib/claude_code/history.ex"
click node_sandbox "https://github.com/guess/claude_code/blob/main/lib/claude_code/sandbox.ex"
click node_plugins "https://github.com/guess/claude_code/blob/main/lib/claude_code/plugin.ex"

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_sdk,node_session_api,node_stream toneBlue
class node_session_server,node_options,node_adapter,node_port_adapter,node_node_adapter toneAmber
class node_parser,node_messages,node_content toneMint
class node_hooks,node_mcp,node_mcp_router,node_agents toneRose
class node_history,node_sandbox,node_plugins,node_app,node_cli,node_cli_service toneIndigo
```

## Components

### Agent API

- [SDK entry points](https://github.com/guess/claude_code/blob/main/lib/claude_code.ex): `lib/claude_code.ex`
- [Session API](https://github.com/guess/claude_code/blob/main/lib/claude_code/session.ex): `lib/claude_code/session.ex`
- [Stream helpers](https://github.com/guess/claude_code/blob/main/lib/claude_code/stream.ex): `lib/claude_code/stream.ex`

### Session Runtime

- [Session process](https://github.com/guess/claude_code/blob/main/lib/claude_code/session/server.ex): `lib/claude_code/session/server.ex`
- [Session options](https://github.com/guess/claude_code/blob/main/lib/claude_code/options.ex): `lib/claude_code/options.ex`
- [CLI adapters](https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter.ex): `lib/claude_code/adapter.ex`
- [Port adapter](https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter/port.ex): `lib/claude_code/adapter/port.ex`
- [Remote adapter](https://github.com/guess/claude_code/blob/main/lib/claude_code/adapter/node.ex): `lib/claude_code/adapter/node.ex`

### CLI Protocol

- [Stream parser](https://github.com/guess/claude_code/blob/main/lib/claude_code/cli/parser.ex): `lib/claude_code/cli/parser.ex`
- [Message types](https://github.com/guess/claude_code/blob/main/lib/claude_code/message/assistant_message.ex): `lib/claude_code/message/assistant_message.ex`
- [Content blocks](https://github.com/guess/claude_code/blob/main/lib/claude_code/content.ex): `lib/claude_code/content.ex`

### Agent Capabilities

- [Hooks and permissions](https://github.com/guess/claude_code/blob/main/lib/claude_code/hook.ex): `lib/claude_code/hook.ex`
- [In-process MCP tools](https://github.com/guess/claude_code/blob/main/lib/claude_code/mcp/server.ex): `lib/claude_code/mcp/server.ex`
- [MCP request router](https://github.com/guess/claude_code/blob/main/lib/claude_code/mcp/router.ex): `lib/claude_code/mcp/router.ex`
- [Subagent definitions](https://github.com/guess/claude_code/blob/main/lib/claude_code/agent.ex): `lib/claude_code/agent.ex`

### Session Operations

- [Conversation history](https://github.com/guess/claude_code/blob/main/lib/claude_code/history.ex): `lib/claude_code/history.ex`
- [Remote sandboxes](https://github.com/guess/claude_code/blob/main/lib/claude_code/sandbox.ex): `lib/claude_code/sandbox.ex`
- [Plugins](https://github.com/guess/claude_code/blob/main/lib/claude_code/plugin.ex): `lib/claude_code/plugin.ex`

### Other components

- **Elixir application**
- **Claude CLI**
- **Claude service**

## Connections

- Elixir application → SDK entry points: starts or queries
- SDK entry points → Session API: starts sessions (evidence: `lib/claude_code.ex`)
- Session API → Session process: manages session
- Session process → CLI adapters: dispatches queries
- CLI adapters → Port adapter: uses port transport
- CLI adapters → Remote adapter: supports remote
- Port adapter → Claude CLI: runs CLI
- Remote adapter → Claude CLI: offloads CLI
- Claude CLI → Stream parser: emits stream JSON (evidence: `lib/claude_code/cli/parser.ex`)
- Stream parser → Message types: parses messages (evidence: `lib/claude_code/cli/parser.ex`)
- Stream parser → Content blocks: parses blocks (evidence: `lib/claude_code/cli/parser.ex`)
- Session API → Stream helpers: streams responses
- Stream helpers → Elixir application: yields results
- Claude CLI → Hooks and permissions: requests callbacks
- Claude CLI → MCP request router: sends tool requests
- MCP request router → In-process MCP tools: dispatches tools (evidence: `lib/claude_code/mcp/router.ex`)
- Elixir application → In-process MCP tools: defines tools
- Elixir application → Hooks and permissions: configures hooks
- Elixir application → Subagent definitions: configures subagents
- Session API → Conversation history: reads history
- Elixir application → Remote sandboxes: uses distributed sessions
- Elixir application → Plugins: uses plugins
