# copperpilot/copper-pilot-cli architecture

> Architecture diagram of the GitHub repository copperpilot/copper-pilot-cli, 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/copperpilot/copper-pilot-cli
- Repository: https://github.com/copperpilot/copper-pilot-cli

## Overview

CopperPilot is a terminal client for a hosted electronics-design agent. A user launches the CLI, selects a workspace and chat mode, authenticates, and sends a request; the hosted service streams responses and local tool requests, which the client brokers and presents. Local graph checkpoints support thread resumption. The package also exposes the hosted agent through MCP and LangChain adapters. The README documents these capabilities; some implementation details are unsampled, so their links are limited to documented or indexed references.

Main entry points: [`src/copper_pilot_cli/copper_main.py`](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_main.py) (CLI entry), [`src/copper_pilot_cli/copper_app.py`](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_app.py) (Chat interface), [`src/copper_pilot_cli/copper_graph.py`](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_graph.py) (Checkpointed runtime), [`src/copper_pilot_cli/langchain.py`](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/langchain.py) (LangChain adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and UI"]
  node_cli["CLI entry<br/>[copper_main.py]"]
  node_terminal["Chat interface<br/>[copper_app.py]"]
  node_widgets["Chat widgets<br/>[copper_widgets.py]"]
  node_presentation["Presentation"]
end

subgraph group_runtime["Agent runtime"]
  node_graph["Checkpointed runtime<br/>[copper_graph.py]"]
  node_protocol["Hosted chat protocol<br/>[copper_protocol.py]"]
  node_tools["Tool approval bridge"]
  node_features["Agent features<br/>[copper_features.py]"]
  node_media["Media handling<br/>[media_utils.py]"]
end

subgraph group_workspace["Workspace and state"]
  node_workspace["Workspace discovery"]
  node_auth["Device authentication<br/>[copper_auth.py]"]
  node_config["User configuration<br/>[copper_config.py]"]
  node_sessions[("Thread persistence<br/>[sessions.py]")]
end

subgraph group_integrations["External interfaces"]
  node_mcp["MCP server<br/>[copper_mcp.py]"]
  node_langchain["LangChain adapter<br/>[langchain.py]"]
end

node_user(("CLI user"))
node_api{{"CopperPilot service"}}
node_local{{"Workspace tools"}}
node_mcp_host(("MCP host"))
node_sdk(("LangChain caller"))

node_user -->|"launches"| node_cli
node_cli -->|"starts"| node_terminal
node_cli -->|"selects"| node_workspace
node_cli -->|"authenticates"| node_auth
node_cli -->|"runs"| node_graph
node_cli -->|"lists threads"| node_sessions
node_cli -->|"starts server"| node_mcp
node_cli -->|"exposes adapter"| node_langchain
node_terminal -->|"renders"| node_widgets
node_terminal -->|"runs turns"| node_graph
node_terminal -->|"requests approval"| node_tools
node_terminal -->|"prepares attachments"| node_media
node_terminal -->|"loads skills"| node_features
node_graph -->|"invokes"| node_langchain
node_graph -->|"checkpoints"| node_sessions
node_langchain -->|"builds requests"| node_protocol
node_langchain -->|"brokers tools"| node_tools
node_protocol -->|"streams chat"| node_api
node_protocol -->|"dispatches requests"| node_local
node_tools -->|"executes approved actions"| node_local
node_auth -->|"logs in"| node_api
node_auth -->|"stores credentials"| node_config
node_workspace -->|"uses paths"| node_config
node_mcp_host -->|"connects over stdio"| node_mcp
node_mcp -->|"delegates turns"| node_graph
node_sdk -->|"invokes runnable"| node_langchain
node_presentation -.->|"supports display"| node_terminal

click node_cli "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_main.py"
click node_terminal "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_app.py"
click node_widgets "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_widgets.py"
click node_presentation "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_presentation.py"
click node_workspace "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_workspace.py"
click node_auth "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_auth.py"
click node_config "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_config.py"
click node_sessions "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/sessions.py"
click node_graph "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_graph.py"
click node_protocol "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_protocol.py"
click node_tools "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/deepagents_tools.py"
click node_features "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_features.py"
click node_media "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/media_utils.py"
click node_mcp "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_mcp.py"
click node_langchain "https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/langchain.py"

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_terminal,node_widgets,node_presentation,node_user toneBlue
class node_graph,node_protocol,node_tools,node_features,node_media toneAmber
class node_workspace,node_auth,node_config,node_sessions toneMint
class node_mcp,node_langchain toneRose
class node_api,node_local,node_mcp_host,node_sdk toneIndigo
```

## Components

### CLI and UI

- [CLI entry](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_main.py): `src/copper_pilot_cli/copper_main.py`
- [Chat interface](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_app.py): `src/copper_pilot_cli/copper_app.py`
- [Chat widgets](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_widgets.py): `src/copper_pilot_cli/copper_widgets.py`
- [Presentation](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_presentation.py): `src/copper_pilot_cli/copper_presentation.py`

### Agent runtime

- [Checkpointed runtime](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_graph.py): `src/copper_pilot_cli/copper_graph.py`
- [Hosted chat protocol](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_protocol.py): `src/copper_pilot_cli/copper_protocol.py`
- [Tool approval bridge](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/deepagents_tools.py): `src/copper_pilot_cli/deepagents_tools.py`
- [Agent features](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_features.py): `src/copper_pilot_cli/copper_features.py`
- [Media handling](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/media_utils.py): `src/copper_pilot_cli/media_utils.py`

### Workspace and state

- [Workspace discovery](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_workspace.py): `src/copper_pilot_cli/copper_workspace.py`
- [Device authentication](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_auth.py): `src/copper_pilot_cli/copper_auth.py`
- [User configuration](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_config.py): `src/copper_pilot_cli/copper_config.py`
- [Thread persistence](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/sessions.py): `src/copper_pilot_cli/sessions.py`

### External interfaces

- [MCP server](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/copper_mcp.py): `src/copper_pilot_cli/copper_mcp.py`
- [LangChain adapter](https://github.com/copperpilot/copper-pilot-cli/blob/main/src/copper_pilot_cli/langchain.py): `src/copper_pilot_cli/langchain.py`

### Other components

- **CLI user**
- **CopperPilot service**
- **Workspace tools**
- **MCP host**
- **LangChain caller**

## Connections

- CLI user → CLI entry: launches (evidence: `README.md`)
- CLI entry → Chat interface: starts (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → Workspace discovery: selects (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → Device authentication: authenticates (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → Checkpointed runtime: runs (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → Thread persistence: lists threads (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → MCP server: starts server (evidence: `src/copper_pilot_cli/copper_main.py`)
- CLI entry → LangChain adapter: exposes adapter (evidence: `src/copper_pilot_cli/copper_main.py`)
- Chat interface → Chat widgets: renders (evidence: `src/copper_pilot_cli/copper_app.py`)
- Chat interface → Checkpointed runtime: runs turns (evidence: `src/copper_pilot_cli/copper_app.py`)
- Chat interface → Tool approval bridge: requests approval (evidence: `src/copper_pilot_cli/copper_app.py`)
- Chat interface → Media handling: prepares attachments (evidence: `src/copper_pilot_cli/copper_app.py`)
- Chat interface → Agent features: loads skills (evidence: `src/copper_pilot_cli/copper_app.py`)
- Checkpointed runtime → LangChain adapter: invokes (evidence: `src/copper_pilot_cli/copper_graph.py`)
- Checkpointed runtime → Thread persistence: checkpoints (evidence: `src/copper_pilot_cli/copper_graph.py`)
- LangChain adapter → Hosted chat protocol: builds requests (evidence: `src/copper_pilot_cli/langchain.py`)
- LangChain adapter → Tool approval bridge: brokers tools (evidence: `src/copper_pilot_cli/langchain.py`)
- Hosted chat protocol → CopperPilot service: streams chat (evidence: `src/copper_pilot_cli/copper_protocol.py`)
- Hosted chat protocol → Workspace tools: dispatches requests (evidence: `src/copper_pilot_cli/copper_protocol.py`)
- Tool approval bridge → Workspace tools: executes approved actions (evidence: `README.md`)
- Device authentication → CopperPilot service: logs in (evidence: `src/copper_pilot_cli/copper_auth.py`)
- Device authentication → User configuration: stores credentials (evidence: `src/copper_pilot_cli/copper_auth.py`)
- Workspace discovery → User configuration: uses paths (evidence: `src/copper_pilot_cli/copper_workspace.py`)
- MCP host → MCP server: connects over stdio (evidence: `README.md`)
- MCP server → Checkpointed runtime: delegates turns (evidence: `src/copper_pilot_cli/copper_mcp.py`)
- LangChain caller → LangChain adapter: invokes runnable (evidence: `README.md`)
- Presentation → Chat interface: supports display (evidence: `src/copper_pilot_cli/copper_app.py`)
