# dimetron/pi-go architecture

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

- Interactive diagram: https://gitdiagram.com/dimetron/pi-go
- Repository: https://github.com/dimetron/pi-go

## Overview

pi-go is a terminal-based coding agent with a reusable Go runtime and a VS Code chat integration. Its principal workflow is user input through the CLI and agent to an LLM provider; tool calls use project-confined tools, and results return to the interactive TUI. Sessions, Memory Palace, and LSP support that workflow. The README documents additional integrations and capabilities included here. Source excerpts are limited, so edges for unsampled subsystems rely on README statements rather than inferred call chains.

Main entry points: [`internal/cli/cli.go`](https://github.com/dimetron/pi-go/blob/main/internal/cli/cli.go) (CLI), [`internal/agent/agent.go`](https://github.com/dimetron/pi-go/blob/main/internal/agent/agent.go) (Agent runtime), [`vscode/src/webview/controller.ts`](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/controller.ts) (Chat controller), [`vscode/src/extension.ts`](https://github.com/dimetron/pi-go/blob/main/vscode/src/extension.ts) (VS Code host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Agent runtime"]
  node_cli["CLI<br/>[cli.go]"]
  node_tui["Interactive TUI<br/>[tui.go]"]
  node_agent["Agent runtime<br/>[agent.go]"]
  node_providers["LLM providers<br/>[provider.go]"]
  node_tools["Sandboxed tools<br/>[registry.go]"]
  node_subagents["Subagents<br/>[orchestrator.go]"]
end

subgraph group_context["Project context"]
  node_sessions[("Session store<br/>[store.go]")]
  node_palace["Memory Palace<br/>[palace.go]"]
  node_palace_db[("Palace storage<br/>[sqlite_store.go]")]
  node_lsp["LSP integration<br/>[manager.go]"]
end

subgraph group_integrations["Interfaces and extensions"]
  node_extensions["Hooks, skills, MCP<br/>[skills.go]"]
  node_plugins["Plugin marketplaces<br/>[install.go]"]
  node_audit["Skills audit<br/>[scanner.go]"]
  node_rpc["Editor RPC<br/>[rpc.go]"]
  node_acp["ACP server<br/>[agent.go]"]
  node_a2a["A2A server<br/>[server.go]"]
  node_webserver["Web server<br/>[server.go]"]
end

subgraph group_editor["VS Code integration"]
  node_extension_host["VS Code host<br/>[extension.ts]"]
  node_protocol["Host-webview protocol<br/>[protocol.ts]"]
  node_webview_main["Webview entry<br/>[main.ts]"]
  node_controller["Chat controller<br/>[controller.ts]"]
  node_composer["Prompt composer<br/>[composer.ts]"]
  node_markdown["Markdown renderer<br/>[markdown.ts]"]
  node_mermaid["Mermaid renderer<br/>[mermaid.ts]"]
  node_toolcard["Tool cards<br/>[toolCard.ts]"]
  node_icons["Webview icons<br/>[icons.ts]"]
  node_clipboard["Clipboard actions<br/>[clipboard.ts]"]
  node_diff["Diff display<br/>[diff.ts]"]
  node_sessions_tree["Session browser<br/>[sessionsTree.ts]"]
end

node_user(("User"))

node_user -->|"enters prompt"| node_cli
node_cli -->|"dispatches input"| node_agent
node_agent -->|"requests completion"| node_providers
node_agent -->|"invokes tools"| node_tools
node_tools -.->|"returns result"| node_user
node_agent -->|"returns response"| node_tui
node_agent -->|"persists events"| node_sessions
node_agent -->|"uses memory"| node_palace
node_palace -.->|"stores memory"| node_palace_db
node_agent -->|"uses diagnostics"| node_lsp
node_agent -->|"dispatches tasks"| node_subagents
node_cli -.->|"configures extensions"| node_extensions
node_cli -->|"manages plugins"| node_plugins
node_cli -->|"runs security scan"| node_audit
node_cli -->|"serves editor RPC"| node_rpc
node_cli -->|"starts ACP server"| node_acp
node_cli -->|"starts A2A server"| node_a2a
node_cli -.->|"starts web server"| node_webserver
node_extension_host -->|"exchanges messages"| node_protocol
node_webview_main -->|"routes messages"| node_protocol
node_webview_main -->|"creates controller"| node_controller
node_controller -->|"uses composer"| node_composer
node_controller -->|"renders markdown"| node_markdown
node_controller -->|"renders diagrams"| node_mermaid
node_controller -->|"renders tool cards"| node_toolcard
node_controller -->|"posts prompts"| node_extension_host
node_toolcard -->|"formats diffs"| node_diff
node_toolcard -->|"uses clipboard"| node_clipboard
node_controller -->|"uses icons"| node_icons
node_extension_host -.->|"browses sessions"| node_sessions_tree

click node_cli "https://github.com/dimetron/pi-go/blob/main/internal/cli/cli.go"
click node_tui "https://github.com/dimetron/pi-go/blob/main/internal/tui/tui.go"
click node_agent "https://github.com/dimetron/pi-go/blob/main/internal/agent/agent.go"
click node_providers "https://github.com/dimetron/pi-go/blob/main/internal/provider/provider.go"
click node_tools "https://github.com/dimetron/pi-go/blob/main/internal/tools/registry.go"
click node_subagents "https://github.com/dimetron/pi-go/blob/main/internal/subagent/orchestrator.go"
click node_sessions "https://github.com/dimetron/pi-go/blob/main/internal/session/store.go"
click node_palace "https://github.com/dimetron/pi-go/blob/main/internal/palace/palace.go"
click node_palace_db "https://github.com/dimetron/pi-go/blob/main/internal/palace/sqlite_store.go"
click node_lsp "https://github.com/dimetron/pi-go/blob/main/internal/lsp/manager.go"
click node_extensions "https://github.com/dimetron/pi-go/blob/main/internal/extension/skills.go"
click node_plugins "https://github.com/dimetron/pi-go/blob/main/internal/plugin/install.go"
click node_audit "https://github.com/dimetron/pi-go/blob/main/internal/audit/scanner.go"
click node_rpc "https://github.com/dimetron/pi-go/blob/main/internal/pirpc/rpc.go"
click node_acp "https://github.com/dimetron/pi-go/blob/main/internal/acp/server/agent.go"
click node_a2a "https://github.com/dimetron/pi-go/blob/main/internal/a2a/server/server.go"
click node_webserver "https://github.com/dimetron/pi-go/blob/main/internal/webserver/server.go"
click node_extension_host "https://github.com/dimetron/pi-go/blob/main/vscode/src/extension.ts"
click node_protocol "https://github.com/dimetron/pi-go/blob/main/vscode/src/shared/protocol.ts"
click node_webview_main "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/main.ts"
click node_controller "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/controller.ts"
click node_composer "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/composer.ts"
click node_markdown "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/markdown.ts"
click node_mermaid "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/mermaid.ts"
click node_toolcard "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/toolCard.ts"
click node_icons "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/icons.ts"
click node_clipboard "https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/clipboard.ts"
click node_diff "https://github.com/dimetron/pi-go/blob/main/vscode/src/shared/diff.ts"
click node_sessions_tree "https://github.com/dimetron/pi-go/blob/main/vscode/src/sessionsTree.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_cli,node_tui,node_agent,node_providers,node_tools,node_subagents,node_user toneBlue
class node_sessions,node_palace,node_palace_db,node_lsp toneAmber
class node_extensions,node_plugins,node_audit,node_rpc,node_acp,node_a2a,node_webserver toneMint
class node_extension_host,node_protocol,node_webview_main,node_controller,node_composer,node_markdown,node_mermaid,node_toolcard,node_icons,node_clipboard,node_diff,node_sessions_tree toneRose
```

## Components

### Agent runtime

- [CLI](https://github.com/dimetron/pi-go/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Interactive TUI](https://github.com/dimetron/pi-go/blob/main/internal/tui/tui.go): `internal/tui/tui.go`
- [Agent runtime](https://github.com/dimetron/pi-go/blob/main/internal/agent/agent.go): `internal/agent/agent.go`
- [LLM providers](https://github.com/dimetron/pi-go/blob/main/internal/provider/provider.go): `internal/provider/provider.go`
- [Sandboxed tools](https://github.com/dimetron/pi-go/blob/main/internal/tools/registry.go): `internal/tools/registry.go`
- [Subagents](https://github.com/dimetron/pi-go/blob/main/internal/subagent/orchestrator.go): `internal/subagent/orchestrator.go`

### Project context

- [Session store](https://github.com/dimetron/pi-go/blob/main/internal/session/store.go): `internal/session/store.go`
- [Memory Palace](https://github.com/dimetron/pi-go/blob/main/internal/palace/palace.go): `internal/palace/palace.go`
- [Palace storage](https://github.com/dimetron/pi-go/blob/main/internal/palace/sqlite_store.go): `internal/palace/sqlite_store.go`
- [LSP integration](https://github.com/dimetron/pi-go/blob/main/internal/lsp/manager.go): `internal/lsp/manager.go`

### Interfaces and extensions

- [Hooks, skills, MCP](https://github.com/dimetron/pi-go/blob/main/internal/extension/skills.go): `internal/extension/skills.go`
- [Plugin marketplaces](https://github.com/dimetron/pi-go/blob/main/internal/plugin/install.go): `internal/plugin/install.go`
- [Skills audit](https://github.com/dimetron/pi-go/blob/main/internal/audit/scanner.go): `internal/audit/scanner.go`
- [Editor RPC](https://github.com/dimetron/pi-go/blob/main/internal/pirpc/rpc.go): `internal/pirpc/rpc.go`
- [ACP server](https://github.com/dimetron/pi-go/blob/main/internal/acp/server/agent.go): `internal/acp/server/agent.go`
- [A2A server](https://github.com/dimetron/pi-go/blob/main/internal/a2a/server/server.go): `internal/a2a/server/server.go`
- [Web server](https://github.com/dimetron/pi-go/blob/main/internal/webserver/server.go): `internal/webserver/server.go`

### VS Code integration

- [VS Code host](https://github.com/dimetron/pi-go/blob/main/vscode/src/extension.ts): `vscode/src/extension.ts`
- [Host-webview protocol](https://github.com/dimetron/pi-go/blob/main/vscode/src/shared/protocol.ts): `vscode/src/shared/protocol.ts`
- [Webview entry](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/main.ts): `vscode/src/webview/main.ts`
- [Chat controller](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/controller.ts): `vscode/src/webview/controller.ts`
- [Prompt composer](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/composer.ts): `vscode/src/webview/composer.ts`
- [Markdown renderer](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/markdown.ts): `vscode/src/webview/markdown.ts`
- [Mermaid renderer](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/mermaid.ts): `vscode/src/webview/mermaid.ts`
- [Tool cards](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/toolCard.ts): `vscode/src/webview/toolCard.ts`
- [Webview icons](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/icons.ts): `vscode/src/webview/icons.ts`
- [Clipboard actions](https://github.com/dimetron/pi-go/blob/main/vscode/src/webview/clipboard.ts): `vscode/src/webview/clipboard.ts`
- [Diff display](https://github.com/dimetron/pi-go/blob/main/vscode/src/shared/diff.ts): `vscode/src/shared/diff.ts`
- [Session browser](https://github.com/dimetron/pi-go/blob/main/vscode/src/sessionsTree.ts): `vscode/src/sessionsTree.ts`

### Other components

- **User**

## Connections

- User → CLI: enters prompt (evidence: `README.md`)
- CLI → Agent runtime: dispatches input (evidence: `README.md`)
- Agent runtime → LLM providers: requests completion (evidence: `README.md`)
- Agent runtime → Sandboxed tools: invokes tools (evidence: `README.md`)
- Sandboxed tools → User: returns result (evidence: `README.md`)
- Agent runtime → Interactive TUI: returns response (evidence: `README.md`)
- Agent runtime → Session store: persists events (evidence: `README.md`)
- Agent runtime → Memory Palace: uses memory (evidence: `README.md`)
- Memory Palace → Palace storage: stores memory (evidence: `README.md`)
- Agent runtime → LSP integration: uses diagnostics (evidence: `README.md`)
- Agent runtime → Subagents: dispatches tasks (evidence: `README.md`)
- CLI → Hooks, skills, MCP: configures extensions (evidence: `README.md`)
- CLI → Plugin marketplaces: manages plugins (evidence: `README.md`)
- CLI → Skills audit: runs security scan (evidence: `README.md`)
- CLI → Editor RPC: serves editor RPC (evidence: `README.md`)
- CLI → ACP server: starts ACP server (evidence: `README.md`)
- CLI → A2A server: starts A2A server (evidence: `internal/a2a/server/server.go`)
- CLI → Web server: starts web server (evidence: `README.md`)
- VS Code host → Host-webview protocol: exchanges messages (evidence: `vscode/src/shared/protocol.ts`)
- Webview entry → Host-webview protocol: routes messages (evidence: `vscode/src/webview/main.ts`)
- Webview entry → Chat controller: creates controller (evidence: `vscode/src/webview/main.ts`)
- Chat controller → Prompt composer: uses composer (evidence: `vscode/src/webview/controller.ts`)
- Chat controller → Markdown renderer: renders markdown (evidence: `vscode/src/webview/controller.ts`)
- Chat controller → Mermaid renderer: renders diagrams (evidence: `vscode/src/webview/controller.ts`)
- Chat controller → Tool cards: renders tool cards (evidence: `vscode/src/webview/controller.ts`)
- Chat controller → VS Code host: posts prompts (evidence: `vscode/src/webview/controller.ts`)
- Tool cards → Diff display: formats diffs (evidence: `vscode/src/webview/toolCard.ts`)
- Tool cards → Clipboard actions: uses clipboard (evidence: `vscode/src/webview/toolCard.ts`)
- Chat controller → Webview icons: uses icons (evidence: `vscode/src/webview/controller.ts`)
- VS Code host → Session browser: browses sessions (evidence: `README.md`)
