# elidickinson/pi-claude-bridge architecture

> Architecture diagram of the GitHub repository elidickinson/pi-claude-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elidickinson/pi-claude-bridge
- Repository: https://github.com/elidickinson/pi-claude-bridge

## Overview

pi-claude-bridge is a Pi extension offering two user-facing capabilities: a Claude Code-backed model provider whose tool calls return through Pi, and an opt-in AskClaude delegation tool. The main runtime in src/index.ts coordinates queries, streaming, tool-result delivery, and session handling; supporting modules manage prompts, configuration, transcript conversion, and model metadata. The README documents additional provider capabilities, including skills forwarding and steering. Most runtime wiring is concentrated in index.ts; unsampled implementation details are represented only where the README or source index supports them.

Main entry points: [`src/index.ts`](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/index.ts) (Pi extension runtime), [`src/prompt-capture.ts`](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/prompt-capture.ts) (Prompt capture), [`src/convert.ts`](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/convert.ts) (Pi transcript conversion), [`src/askclaude-schema.ts`](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/askclaude-schema.ts) (AskClaude tool schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bridge runtime"]
  node_pi_runtime["Pi extension runtime<br/>[index.ts]"]
  node_query_state["Query state<br/>[query-state.ts]"]
  node_prompt_stream["Prompt stream<br/>[prompt-stream.ts]"]
  node_tool_results["Tool-result extraction"]
  node_mcp_server["MCP tool server<br/>[mcp-server.ts]"]
  node_config["Bridge configuration<br/>[config.ts]"]
  node_log_paths["Debug log paths<br/>[log-paths.ts]"]
end

subgraph group_provider["Claude provider"]
  node_claude_sdk["Claude Agent SDK"]
  node_claude_cli["Claude Code CLI"]
  node_models["Model catalog mapping<br/>[models.ts]"]
  node_usage["Usage reporting<br/>[usage.ts]"]
end

subgraph group_delegation["AskClaude delegation"]
  node_ask_schema["AskClaude tool schema"]
  node_ask_ui["AskClaude UI<br/>[askclaude-ui.ts]"]
end

subgraph group_context["Prompt and history"]
  node_prompt_capture["Prompt capture<br/>[prompt-capture.ts]"]
  node_skills["Skills forwarding<br/>[skills.ts]"]
  node_agents_md["Project context formatting<br/>[agents-md.ts]"]
  node_transcript["Transcript replay<br/>[transcript.ts]"]
  node_convert["Pi transcript conversion<br/>[convert.ts]"]
  node_attachments["Attachment carry-forward<br/>[attachments.ts]"]
  node_session_verify["Session integrity check<br/>[session-verify.ts]"]
end

node_pi_user(("Pi user"))

node_pi_user -->|"selects or invokes"| node_pi_runtime
node_pi_runtime -->|"starts queries"| node_claude_sdk
node_claude_sdk -->|"runs CLI"| node_claude_cli
node_pi_runtime -->|"maps model IDs"| node_models
node_pi_runtime -->|"manages query state"| node_query_state
node_pi_runtime -->|"streams prompts"| node_prompt_stream
node_pi_runtime -->|"serves bridged tools"| node_mcp_server
node_pi_runtime -->|"extracts tool results"| node_tool_results
node_pi_runtime -->|"reports usage"| node_usage
node_pi_runtime -->|"loads settings"| node_config
node_pi_runtime -->|"collects prompt context"| node_prompt_capture
node_prompt_capture -->|"renders skills"| node_skills
node_prompt_capture -->|"formats project context"| node_agents_md
node_pi_runtime -->|"converts history"| node_convert
node_convert -->|"maps MCP tool names"| node_skills
node_pi_runtime -->|"carries attachments"| node_attachments
node_attachments -->|"converts message content"| node_convert
node_pi_runtime -->|"replays transcripts"| node_transcript
node_pi_runtime -->|"checks saved sessions"| node_session_verify
node_pi_runtime -->|"configures debug paths"| node_log_paths
node_pi_runtime -->|"registers delegation tool"| node_ask_schema
node_pi_runtime -->|"renders delegation UI"| node_ask_ui
node_ask_schema -->|"delegates tasks"| node_claude_sdk
node_pi_runtime -->|"compacts history"| node_claude_cli

click node_pi_runtime "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/index.ts"
click node_query_state "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/query-state.ts"
click node_prompt_stream "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/prompt-stream.ts"
click node_tool_results "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/extract-tool-results.ts"
click node_mcp_server "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/mcp-server.ts"
click node_models "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/models.ts"
click node_usage "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/usage.ts"
click node_ask_schema "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/askclaude-schema.ts"
click node_ask_ui "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/askclaude-ui.ts"
click node_config "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/config.ts"
click node_prompt_capture "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/prompt-capture.ts"
click node_skills "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/skills.ts"
click node_agents_md "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/agents-md.ts"
click node_transcript "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/transcript.ts"
click node_convert "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/convert.ts"
click node_attachments "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/attachments.ts"
click node_session_verify "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/session-verify.ts"
click node_log_paths "https://github.com/elidickinson/pi-claude-bridge/blob/main/src/log-paths.ts"

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_pi_runtime,node_query_state,node_prompt_stream,node_tool_results,node_mcp_server,node_config,node_log_paths,node_pi_user toneBlue
class node_claude_sdk,node_claude_cli,node_models,node_usage toneAmber
class node_ask_schema,node_ask_ui toneMint
class node_prompt_capture,node_skills,node_agents_md,node_transcript,node_convert,node_attachments,node_session_verify toneRose
```

## Components

### Bridge runtime

- [Pi extension runtime](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/index.ts): `src/index.ts`
- [Query state](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/query-state.ts): `src/query-state.ts`
- [Prompt stream](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/prompt-stream.ts): `src/prompt-stream.ts`
- [Tool-result extraction](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/extract-tool-results.ts): `src/extract-tool-results.ts`
- [MCP tool server](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/mcp-server.ts): `src/mcp-server.ts`
- [Bridge configuration](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/config.ts): `src/config.ts`
- [Debug log paths](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/log-paths.ts): `src/log-paths.ts`

### Claude provider

- **Claude Agent SDK**
- **Claude Code CLI**
- [Model catalog mapping](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/models.ts): `src/models.ts`
- [Usage reporting](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/usage.ts): `src/usage.ts`

### AskClaude delegation

- [AskClaude tool schema](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/askclaude-schema.ts): `src/askclaude-schema.ts`
- [AskClaude UI](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/askclaude-ui.ts): `src/askclaude-ui.ts`

### Prompt and history

- [Prompt capture](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/prompt-capture.ts): `src/prompt-capture.ts`
- [Skills forwarding](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/skills.ts): `src/skills.ts`
- [Project context formatting](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/agents-md.ts): `src/agents-md.ts`
- [Transcript replay](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/transcript.ts): `src/transcript.ts`
- [Pi transcript conversion](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/convert.ts): `src/convert.ts`
- [Attachment carry-forward](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/attachments.ts): `src/attachments.ts`
- [Session integrity check](https://github.com/elidickinson/pi-claude-bridge/blob/main/src/session-verify.ts): `src/session-verify.ts`

### Other components

- **Pi user**

## Connections

- Pi user → Pi extension runtime: selects or invokes (evidence: `README.md`)
- Pi extension runtime → Claude Agent SDK: starts queries (evidence: `src/index.ts`)
- Claude Agent SDK → Claude Code CLI: runs CLI (evidence: `README.md`)
- Pi extension runtime → Model catalog mapping: maps model IDs (evidence: `src/index.ts`)
- Pi extension runtime → Query state: manages query state (evidence: `src/index.ts`)
- Pi extension runtime → Prompt stream: streams prompts (evidence: `src/index.ts`)
- Pi extension runtime → MCP tool server: serves bridged tools (evidence: `README.md`)
- Pi extension runtime → Tool-result extraction: extracts tool results (evidence: `src/index.ts`)
- Pi extension runtime → Usage reporting: reports usage (evidence: `src/index.ts`)
- Pi extension runtime → Bridge configuration: loads settings (evidence: `src/index.ts`)
- Pi extension runtime → Prompt capture: collects prompt context (evidence: `src/index.ts`)
- Prompt capture → Skills forwarding: renders skills (evidence: `src/prompt-capture.ts`)
- Prompt capture → Project context formatting: formats project context (evidence: `src/prompt-capture.ts`)
- Pi extension runtime → Pi transcript conversion: converts history (evidence: `src/index.ts`)
- Pi transcript conversion → Skills forwarding: maps MCP tool names (evidence: `src/convert.ts`)
- Pi extension runtime → Attachment carry-forward: carries attachments (evidence: `src/index.ts`)
- Attachment carry-forward → Pi transcript conversion: converts message content (evidence: `src/attachments.ts`)
- Pi extension runtime → Transcript replay: replays transcripts (evidence: `src/index.ts`)
- Pi extension runtime → Session integrity check: checks saved sessions (evidence: `src/index.ts`)
- Pi extension runtime → Debug log paths: configures debug paths (evidence: `src/index.ts`)
- Pi extension runtime → AskClaude tool schema: registers delegation tool (evidence: `src/index.ts`)
- Pi extension runtime → AskClaude UI: renders delegation UI (evidence: `src/index.ts`)
- AskClaude tool schema → Claude Agent SDK: delegates tasks (evidence: `README.md`)
- Pi extension runtime → Claude Code CLI: compacts history (evidence: `src/index.ts`)