# starlessskynight/arkad-agent architecture

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

## Overview

Arkad is a terminal-native AI coding agent. A user starts the Textual interface or legacy REPL, submits a prompt, and the agent selects tools, consults a configured model provider, then can inspect project context, edit files, run commands, and check its work. Supporting branches provide persistent sessions and memory, MCP servers, provider authentication, and an optional browser mirror. The README documents capabilities beyond the sampled excerpts; uncertain implementation links are omitted rather than inferred.

Main entry points: [`arkad/repl/stream.py`](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/repl/stream.py) (Turn streaming), [`arkad/tui/app.py`](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/tui/app.py) (Textual TUI), [`arkad/tools`](https://github.com/starlessskynight/arkad-agent/tree/main/arkad/tools) (Coding tools), [`arkad/main.py`](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/main.py) (Rich REPL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_tui["Textual TUI<br/>[app.py]"]
  node_legacy["Rich REPL<br/>[main.py]"]
  node_web["Browser mirror<br/>[handler.py]"]
  node_webserver["Web server<br/>[server.py]"]
end

subgraph group_agent["Agent runtime"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_stream["Turn streaming<br/>[stream.py]"]
  node_router["Tool selection<br/>[router.py]"]
  node_render["Turn rendering<br/>[render.py]"]
  node_state["Shared state<br/>[state.py]"]
end

subgraph group_providers["Models and auth"]
  node_client["Provider client<br/>[client.py]"]
  node_catalog["Provider catalog<br/>[providers.py]"]
  node_auth["Provider sign-in<br/>[oauth_flow.py]"]
end

subgraph group_capabilities["Project capabilities"]
  node_tools["Coding tools"]
  node_project["Project context<br/>[project_context.py]"]
  node_changes["File changes<br/>[file_changes.py]"]
end

subgraph group_persistence["State and integrations"]
  node_sessions[("Session history<br/>[sessions.py]")]
  node_memory[("Memory and skills")]
  node_mcp["MCP registry<br/>[registry.py]"]
  node_mcpmanager["MCP management<br/>[manager.py]"]
end

node_user(("User"))

node_user -->|"starts default"| node_tui
node_user -->|"starts legacy"| node_legacy
node_user -->|"uses browser"| node_web
node_webserver -->|"serves interface"| node_web
node_tui -.->|"runs turns"| node_loop
node_legacy -->|"streams turns"| node_stream
node_stream -->|"requests model"| node_client
node_stream -->|"selects schemas"| node_router
node_router -->|"exposes tools"| node_tools
node_stream -->|"renders output"| node_render
node_client -->|"resolves models"| node_catalog
node_client -->|"uses credentials"| node_auth
node_loop -.->|"invokes tools"| node_tools
node_tools -->|"reads context"| node_project
node_tools -->|"edits files"| node_changes
node_legacy -->|"loads history"| node_sessions
node_state -->|"tracks sessions"| node_sessions
node_router -->|"includes MCP tools"| node_mcp
node_mcpmanager -->|"manages connections"| node_mcp
node_tui -->|"uses shared state"| node_state
node_webserver -->|"mirrors console"| node_tui

click node_tui "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/tui/app.py"
click node_legacy "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/main.py"
click node_web "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/web/handler.py"
click node_webserver "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/web/server.py"
click node_loop "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/loop.py"
click node_stream "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/repl/stream.py"
click node_router "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/tools/router.py"
click node_render "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/repl/render.py"
click node_state "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/state.py"
click node_client "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/auth/client.py"
click node_catalog "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/constants/providers.py"
click node_tools "https://github.com/starlessskynight/arkad-agent/tree/main/arkad/tools"
click node_project "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/project_context.py"
click node_changes "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/file_changes.py"
click node_sessions "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/storage/sessions.py"
click node_memory "https://github.com/starlessskynight/arkad-agent/tree/main/arkad/storage"
click node_mcp "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/mcp/registry.py"
click node_mcpmanager "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/mcp/manager.py"
click node_auth "https://github.com/starlessskynight/arkad-agent/blob/main/arkad/auth/oauth_flow.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_tui,node_legacy,node_web,node_webserver,node_user toneBlue
class node_loop,node_stream,node_router,node_render,node_state toneAmber
class node_client,node_catalog,node_auth toneMint
class node_tools,node_project,node_changes toneRose
class node_sessions,node_memory,node_mcp,node_mcpmanager toneIndigo
```

## Components

### User interaction

- [Textual TUI](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/tui/app.py): `arkad/tui/app.py`
- [Rich REPL](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/main.py): `arkad/main.py`
- [Browser mirror](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/web/handler.py): `arkad/web/handler.py`
- [Web server](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/web/server.py): `arkad/web/server.py`

### Agent runtime

- [Agent loop](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/loop.py): `arkad/loop.py`
- [Turn streaming](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/repl/stream.py): `arkad/repl/stream.py`
- [Tool selection](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/tools/router.py): `arkad/tools/router.py`
- [Turn rendering](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/repl/render.py): `arkad/repl/render.py`
- [Shared state](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/state.py): `arkad/state.py`

### Models and auth

- [Provider client](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/auth/client.py): `arkad/auth/client.py`
- [Provider catalog](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/constants/providers.py): `arkad/constants/providers.py`
- [Provider sign-in](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/auth/oauth_flow.py): `arkad/auth/oauth_flow.py`

### Project capabilities

- [Coding tools](https://github.com/starlessskynight/arkad-agent/tree/main/arkad/tools): `arkad/tools`
- [Project context](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/project_context.py): `arkad/project_context.py`
- [File changes](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/file_changes.py): `arkad/file_changes.py`

### State and integrations

- [Session history](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/storage/sessions.py): `arkad/storage/sessions.py`
- [Memory and skills](https://github.com/starlessskynight/arkad-agent/tree/main/arkad/storage): `arkad/storage`
- [MCP registry](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/mcp/registry.py): `arkad/mcp/registry.py`
- [MCP management](https://github.com/starlessskynight/arkad-agent/blob/main/arkad/mcp/manager.py): `arkad/mcp/manager.py`

### Other components

- **User**

## Connections

- User → Textual TUI: starts default
- User → Rich REPL: starts legacy
- User → Browser mirror: uses browser
- Web server → Browser mirror: serves interface (evidence: `arkad/web/server.py`)
- Textual TUI → Agent loop: runs turns
- Rich REPL → Turn streaming: streams turns (evidence: `arkad/main.py`)
- Turn streaming → Provider client: requests model (evidence: `arkad/repl/stream.py`)
- Turn streaming → Tool selection: selects schemas (evidence: `arkad/repl/stream.py`)
- Tool selection → Coding tools: exposes tools (evidence: `arkad/tools/router.py`)
- Turn streaming → Turn rendering: renders output (evidence: `arkad/repl/stream.py`)
- Provider client → Provider catalog: resolves models (evidence: `arkad/auth/client.py`)
- Provider client → Provider sign-in: uses credentials (evidence: `arkad/auth/client.py`)
- Agent loop → Coding tools: invokes tools (evidence: `arkad/tools/router.py`)
- Coding tools → Project context: reads context
- Coding tools → File changes: edits files
- Rich REPL → Session history: loads history (evidence: `arkad/main.py`)
- Shared state → Session history: tracks sessions (evidence: `arkad/state.py`)
- Tool selection → MCP registry: includes MCP tools (evidence: `arkad/tools/router.py`)
- MCP management → MCP registry: manages connections (evidence: `arkad/mcp/manager.py`)
- Textual TUI → Shared state: uses shared state (evidence: `arkad/tui/app.py`)
- Web server → Textual TUI: mirrors console (evidence: `arkad/web/server.py`)
