# bparafina/pi_agent_rust architecture

> Architecture diagram of the GitHub repository bparafina/pi_agent_rust, 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/bparafina/pi_agent_rust
- Repository: https://github.com/bparafina/pi_agent_rust

## Overview

Pi Agent Rust is a native terminal coding agent. Its principal workflow takes a user prompt through the CLI and application runtime, uses a model/provider to generate streamed responses and tool calls, and presents results in the terminal while maintaining sessions. The README also documents extension execution and security, MCP servers, package management, and browser/computer capabilities. Some major source modules named in the SOURCE INDEX are absent from the supplied tree; those areas are represented only where an exact enclosing path is available, and unsampled implementation details are not inferred.

Main entry points: [`src/app.rs`](https://github.com/bparafina/pi_agent_rust/blob/main/src/app.rs) (Agent runtime), [`src/providers/mod.rs`](https://github.com/bparafina/pi_agent_rust/blob/main/src/providers/mod.rs) (Provider backends), [`src/models.rs`](https://github.com/bparafina/pi_agent_rust/blob/main/src/models.rs) (Model catalog), [`src/http/client.rs`](https://github.com/bparafina/pi_agent_rust/blob/main/src/http/client.rs) (Streaming HTTP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_cli["CLI entry<br/>[app.rs]"]
  node_agent["Agent runtime<br/>[app.rs]"]
  node_config["Configuration<br/>[config.rs]"]
  node_messages["Messages and events<br/>[model.rs]"]
end

subgraph group_models["Models and providers"]
  node_model_catalog[("Model catalog<br/>[models.rs]")]
  node_provider_api["Provider interface<br/>[provider.rs]"]
  node_provider_backends["Provider backends<br/>[mod.rs]"]
  node_http["Streaming HTTP<br/>[client.rs]"]
end

subgraph group_tools["Tools and extensions"]
  node_tools["Built-in tools"]
  node_extensions["Extension runtime"]
  node_package_manager["Package management<br/>[package_manager.rs]"]
end

subgraph group_integrations["Integrations and state"]
  node_mcp["MCP servers<br/>[manager.rs]"]
  node_sessions[("Session persistence")]
  node_lsp["Language server<br/>[client.rs]"]
  node_browser["Browser automation<br/>[cdp.rs]"]
end

node_user(("User"))
node_external_models(("Model services"))
node_terminal(("Terminal"))

node_user -->|"provides prompt"| node_cli
node_cli -->|"starts workflow"| node_agent
node_agent -->|"loads settings"| node_config
node_agent -->|"selects model"| node_model_catalog
node_model_catalog -->|"defines routing"| node_provider_api
node_provider_backends -->|"implements"| node_provider_api
node_provider_backends -->|"sends requests"| node_http
node_http -.->|"streams API traffic"| node_external_models
node_provider_backends -->|"emits events"| node_messages
node_agent -.->|"processes turns"| node_messages
node_agent -.->|"dispatches tools"| node_tools
node_agent -.->|"persists session"| node_sessions
node_agent -.->|"renders results"| node_terminal
node_extensions -.->|"exposes hostcalls"| node_tools
node_package_manager -.->|"installs packages"| node_extensions
node_agent -.->|"uses servers"| node_mcp
node_agent -.->|"uses language services"| node_lsp
node_agent -.->|"uses browser tools"| node_browser

click node_cli "https://github.com/bparafina/pi_agent_rust/blob/main/src/app.rs"
click node_agent "https://github.com/bparafina/pi_agent_rust/blob/main/src/app.rs"
click node_config "https://github.com/bparafina/pi_agent_rust/blob/main/src/config.rs"
click node_messages "https://github.com/bparafina/pi_agent_rust/blob/main/src/model.rs"
click node_model_catalog "https://github.com/bparafina/pi_agent_rust/blob/main/src/models.rs"
click node_provider_api "https://github.com/bparafina/pi_agent_rust/blob/main/src/provider.rs"
click node_provider_backends "https://github.com/bparafina/pi_agent_rust/blob/main/src/providers/mod.rs"
click node_http "https://github.com/bparafina/pi_agent_rust/blob/main/src/http/client.rs"
click node_tools "https://github.com/bparafina/pi_agent_rust/tree/main/src"
click node_extensions "https://github.com/bparafina/pi_agent_rust/blob/main/src/extensions/extension_manager_impl.rs"
click node_package_manager "https://github.com/bparafina/pi_agent_rust/blob/main/src/package_manager.rs"
click node_mcp "https://github.com/bparafina/pi_agent_rust/blob/main/src/mcp/manager.rs"
click node_sessions "https://github.com/bparafina/pi_agent_rust/tree/main/src"
click node_lsp "https://github.com/bparafina/pi_agent_rust/blob/main/src/lsp/client.rs"
click node_browser "https://github.com/bparafina/pi_agent_rust/blob/main/src/browser/cdp.rs"

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_agent,node_config,node_messages,node_user toneBlue
class node_model_catalog,node_provider_api,node_provider_backends,node_http toneAmber
class node_tools,node_extensions,node_package_manager toneMint
class node_mcp,node_sessions,node_lsp,node_browser toneRose
class node_external_models,node_terminal toneIndigo
```

## Components

### Agent runtime

- [CLI entry](https://github.com/bparafina/pi_agent_rust/blob/main/src/app.rs): `src/app.rs`
- [Agent runtime](https://github.com/bparafina/pi_agent_rust/blob/main/src/app.rs): `src/app.rs`
- [Configuration](https://github.com/bparafina/pi_agent_rust/blob/main/src/config.rs): `src/config.rs`
- [Messages and events](https://github.com/bparafina/pi_agent_rust/blob/main/src/model.rs): `src/model.rs`

### Models and providers

- [Model catalog](https://github.com/bparafina/pi_agent_rust/blob/main/src/models.rs): `src/models.rs`
- [Provider interface](https://github.com/bparafina/pi_agent_rust/blob/main/src/provider.rs): `src/provider.rs`
- [Provider backends](https://github.com/bparafina/pi_agent_rust/blob/main/src/providers/mod.rs): `src/providers/mod.rs`
- [Streaming HTTP](https://github.com/bparafina/pi_agent_rust/blob/main/src/http/client.rs): `src/http/client.rs`

### Tools and extensions

- [Built-in tools](https://github.com/bparafina/pi_agent_rust/tree/main/src): `src`
- [Extension runtime](https://github.com/bparafina/pi_agent_rust/blob/main/src/extensions/extension_manager_impl.rs): `src/extensions/extension_manager_impl.rs`
- [Package management](https://github.com/bparafina/pi_agent_rust/blob/main/src/package_manager.rs): `src/package_manager.rs`

### Integrations and state

- [MCP servers](https://github.com/bparafina/pi_agent_rust/blob/main/src/mcp/manager.rs): `src/mcp/manager.rs`
- [Session persistence](https://github.com/bparafina/pi_agent_rust/tree/main/src): `src`
- [Language server](https://github.com/bparafina/pi_agent_rust/blob/main/src/lsp/client.rs): `src/lsp/client.rs`
- [Browser automation](https://github.com/bparafina/pi_agent_rust/blob/main/src/browser/cdp.rs): `src/browser/cdp.rs`

### Other components

- **User**
- **Model services**
- **Terminal**

## Connections

- User → CLI entry: provides prompt (evidence: `README.md`)
- CLI entry → Agent runtime: starts workflow (evidence: `src/app.rs`)
- Agent runtime → Configuration: loads settings (evidence: `src/app.rs`)
- Agent runtime → Model catalog: selects model (evidence: `src/app.rs`)
- Model catalog → Provider interface: defines routing (evidence: `src/models.rs`)
- Provider backends → Provider interface: implements (evidence: `src/providers/mod.rs`)
- Provider backends → Streaming HTTP: sends requests (evidence: `src/providers/mod.rs`)
- Streaming HTTP → Model services: streams API traffic
- Provider backends → Messages and events: emits events (evidence: `src/providers/mod.rs`)
- Agent runtime → Messages and events: processes turns (evidence: `src/app.rs`)
- Agent runtime → Built-in tools: dispatches tools (evidence: `README.md`)
- Agent runtime → Session persistence: persists session (evidence: `README.md`)
- Agent runtime → Terminal: renders results (evidence: `README.md`)
- Extension runtime → Built-in tools: exposes hostcalls (evidence: `README.md`)
- Package management → Extension runtime: installs packages (evidence: `README.md`)
- Agent runtime → MCP servers: uses servers (evidence: `README.md`)
- Agent runtime → Language server: uses language services (evidence: `README.md`)
- Agent runtime → Browser automation: uses browser tools (evidence: `README.md`)
