# pulseaiclub/phi architecture

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

- Interactive diagram: https://gitdiagram.com/pulseaiclub/phi
- Repository: https://github.com/pulseaiclub/phi

## Overview

Phi is a terminal coding-agent harness. A user starts an interactive or headless run; the TUI controller or CLI run path drives an agent loop, which streams model responses, executes permitted tools, and records the conversation. The graph also shows sub-agents, MCP, extensions, configuration, session persistence, and the documented diff-review and code-view features. README capabilities guide the unsampled branches; arrows are limited to documented behavior and sampled wiring.

Main entry points: [`internal/agent/engine.go`](https://github.com/pulseaiclub/phi/blob/main/internal/agent/engine.go) (Agent engine), [`internal/tui/controller/controller.go`](https://github.com/pulseaiclub/phi/blob/main/internal/tui/controller/controller.go) (TUI controller), [`cmd/main.go`](https://github.com/pulseaiclub/phi/blob/main/cmd/main.go) (CLI commands), [`internal/agent/executor.go`](https://github.com/pulseaiclub/phi/blob/main/internal/agent/executor.go) (Tool executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI commands<br/>[main.go]"]
  node_tui["Terminal UI<br/>[app.go]"]
  node_controller["TUI controller<br/>[controller.go]"]
  node_diff["Diff review"]
  node_codeview["Code viewer"]
  node_configui["Config editor"]
end

subgraph group_agent["Agent runtime"]
  node_engine["Agent engine<br/>[engine.go]"]
  node_executor["Tool executor<br/>[executor.go]"]
  node_jobs["Sub-agent jobs<br/>[manager.go]"]
  node_childrunner["Child agent runner<br/>[engine_runner.go]"]
end

subgraph group_providers["Models and tools"]
  node_llmclient["Provider client<br/>[client.go]"]
  node_tools["Built-in tools<br/>[tools.go]"]
  node_permission["Permission gate<br/>[gate.go]"]
end

subgraph group_integrations["Project integrations"]
  node_mcp["MCP clients<br/>[client.go]"]
  node_extensions["Extension runner<br/>[runner.go]"]
  node_skills["Skills catalog<br/>[skills.go]"]
end

subgraph group_state["Configuration and state"]
  node_project["Project config<br/>[project.go]"]
  node_session["Session manager<br/>[manager.go]"]
  node_sessionfiles[("Session files<br/>[manager.go]")]
  node_jobstore[("Job store<br/>[store.go]")]
end

node_user(("User"))
node_providersvc(("Model providers"))

node_user -->|"runs command"| node_cli
node_cli -->|"starts TUI"| node_tui
node_cli -->|"starts headless run"| node_controller
node_user -->|"interacts"| node_tui
node_tui -->|"dispatches input"| node_controller
node_controller -->|"starts prompt loop"| node_engine
node_engine -->|"requests completion"| node_llmclient
node_llmclient -->|"sends request"| node_providersvc
node_providersvc -->|"streams response"| node_llmclient
node_engine -->|"runs tool calls"| node_executor
node_executor -->|"dispatches tools"| node_tools
node_executor -->|"checks policy"| node_permission
node_engine -->|"reads and appends"| node_session
node_session -->|"persists entries"| node_sessionfiles
node_engine -->|"spawns sub-agents"| node_jobs
node_jobs -->|"runs job"| node_childrunner
node_childrunner -->|"runs child loop"| node_engine
node_jobs -->|"persists job data"| node_jobstore
node_engine -->|"uses MCP tools"| node_mcp
node_engine -->|"runs extension hooks"| node_extensions
node_controller -->|"loads project config"| node_project
node_engine -->|"loads skill instructions"| node_skills
node_user -->|"edits settings"| node_configui
node_configui -->|"updates config"| node_project
node_user -->|"reviews changes"| node_diff
node_user -->|"views source"| node_codeview

click node_cli "https://github.com/pulseaiclub/phi/blob/main/cmd/main.go"
click node_tui "https://github.com/pulseaiclub/phi/blob/main/internal/components/app/app.go"
click node_controller "https://github.com/pulseaiclub/phi/blob/main/internal/tui/controller/controller.go"
click node_diff "https://github.com/pulseaiclub/phi/tree/main/internal/util/diffreview"
click node_codeview "https://github.com/pulseaiclub/phi/tree/main/internal/components/codeview"
click node_configui "https://github.com/pulseaiclub/phi/tree/main/internal/tui/configui"
click node_engine "https://github.com/pulseaiclub/phi/blob/main/internal/agent/engine.go"
click node_executor "https://github.com/pulseaiclub/phi/blob/main/internal/agent/executor.go"
click node_jobs "https://github.com/pulseaiclub/phi/blob/main/internal/job/manager.go"
click node_childrunner "https://github.com/pulseaiclub/phi/blob/main/internal/agent/engine_runner.go"
click node_llmclient "https://github.com/pulseaiclub/phi/blob/main/internal/llm/client/client.go"
click node_tools "https://github.com/pulseaiclub/phi/blob/main/internal/tools/tools.go"
click node_permission "https://github.com/pulseaiclub/phi/blob/main/internal/permission/gate.go"
click node_mcp "https://github.com/pulseaiclub/phi/blob/main/internal/mcp/client.go"
click node_extensions "https://github.com/pulseaiclub/phi/blob/main/internal/extension/runner.go"
click node_project "https://github.com/pulseaiclub/phi/blob/main/internal/project/project.go"
click node_session "https://github.com/pulseaiclub/phi/blob/main/internal/session/manager.go"
click node_sessionfiles "https://github.com/pulseaiclub/phi/blob/main/internal/session/manager.go"
click node_jobstore "https://github.com/pulseaiclub/phi/blob/main/internal/job/store.go"
click node_skills "https://github.com/pulseaiclub/phi/blob/main/internal/llm/skills/skills.go"

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_controller,node_diff,node_codeview,node_configui,node_user toneBlue
class node_engine,node_executor,node_jobs,node_childrunner toneAmber
class node_llmclient,node_tools,node_permission toneMint
class node_mcp,node_extensions,node_skills toneRose
class node_project,node_session,node_sessionfiles,node_jobstore,node_providersvc toneIndigo
```

## Components

### User interaction

- [CLI commands](https://github.com/pulseaiclub/phi/blob/main/cmd/main.go): `cmd/main.go`
- [Terminal UI](https://github.com/pulseaiclub/phi/blob/main/internal/components/app/app.go): `internal/components/app/app.go`
- [TUI controller](https://github.com/pulseaiclub/phi/blob/main/internal/tui/controller/controller.go): `internal/tui/controller/controller.go`
- [Diff review](https://github.com/pulseaiclub/phi/tree/main/internal/util/diffreview): `internal/util/diffreview`
- [Code viewer](https://github.com/pulseaiclub/phi/tree/main/internal/components/codeview): `internal/components/codeview`
- [Config editor](https://github.com/pulseaiclub/phi/tree/main/internal/tui/configui): `internal/tui/configui`

### Agent runtime

- [Agent engine](https://github.com/pulseaiclub/phi/blob/main/internal/agent/engine.go): `internal/agent/engine.go`
- [Tool executor](https://github.com/pulseaiclub/phi/blob/main/internal/agent/executor.go): `internal/agent/executor.go`
- [Sub-agent jobs](https://github.com/pulseaiclub/phi/blob/main/internal/job/manager.go): `internal/job/manager.go`
- [Child agent runner](https://github.com/pulseaiclub/phi/blob/main/internal/agent/engine_runner.go): `internal/agent/engine_runner.go`

### Models and tools

- [Provider client](https://github.com/pulseaiclub/phi/blob/main/internal/llm/client/client.go): `internal/llm/client/client.go`
- [Built-in tools](https://github.com/pulseaiclub/phi/blob/main/internal/tools/tools.go): `internal/tools/tools.go`
- [Permission gate](https://github.com/pulseaiclub/phi/blob/main/internal/permission/gate.go): `internal/permission/gate.go`

### Project integrations

- [MCP clients](https://github.com/pulseaiclub/phi/blob/main/internal/mcp/client.go): `internal/mcp/client.go`
- [Extension runner](https://github.com/pulseaiclub/phi/blob/main/internal/extension/runner.go): `internal/extension/runner.go`
- [Skills catalog](https://github.com/pulseaiclub/phi/blob/main/internal/llm/skills/skills.go): `internal/llm/skills/skills.go`

### Configuration and state

- [Project config](https://github.com/pulseaiclub/phi/blob/main/internal/project/project.go): `internal/project/project.go`
- [Session manager](https://github.com/pulseaiclub/phi/blob/main/internal/session/manager.go): `internal/session/manager.go`
- [Session files](https://github.com/pulseaiclub/phi/blob/main/internal/session/manager.go): `internal/session/manager.go`
- [Job store](https://github.com/pulseaiclub/phi/blob/main/internal/job/store.go): `internal/job/store.go`

### Other components

- **User**
- **Model providers**

## Connections

- User → CLI commands: runs command
- CLI commands → Terminal UI: starts TUI
- CLI commands → TUI controller: starts headless run
- User → Terminal UI: interacts
- Terminal UI → TUI controller: dispatches input
- TUI controller → Agent engine: starts prompt loop
- Agent engine → Provider client: requests completion
- Provider client → Model providers: sends request
- Model providers → Provider client: streams response
- Agent engine → Tool executor: runs tool calls
- Tool executor → Built-in tools: dispatches tools
- Tool executor → Permission gate: checks policy
- Agent engine → Session manager: reads and appends
- Session manager → Session files: persists entries
- Agent engine → Sub-agent jobs: spawns sub-agents
- Sub-agent jobs → Child agent runner: runs job
- Child agent runner → Agent engine: runs child loop
- Sub-agent jobs → Job store: persists job data
- Agent engine → MCP clients: uses MCP tools
- Agent engine → Extension runner: runs extension hooks
- TUI controller → Project config: loads project config
- Agent engine → Skills catalog: loads skill instructions
- User → Config editor: edits settings
- Config editor → Project config: updates config
- User → Diff review: reviews changes
- User → Code viewer: views source