# mercphobia/krol architecture

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

- Interactive diagram: https://gitdiagram.com/mercphobia/krol
- Repository: https://github.com/mercphobia/krol

## Overview

Krol is a mobile-first AI agent framework. A user starts a conversation through the CLI or an interface; the agent loop streams model responses, dispatches requested tools through policy checks, and returns results to the conversation. Around that core, Krol provides persistent memory, planning and scheduled autonomy, extensibility, and multiple user interfaces. The README documents these capabilities, but many implementation files were not sampled, so their internal connections are shown only where documented or explicitly marked unverified.

Main entry points: [`src/krol/core/loop.py`](https://github.com/mercphobia/krol/blob/main/src/krol/core/loop.py) (Agent loop), [`src/krol/cli.py`](https://github.com/mercphobia/krol/blob/main/src/krol/cli.py) (CLI), [`src/krol/policy/session.py`](https://github.com/mercphobia/krol/blob/main/src/krol/policy/session.py) (Policy session), [`src/krol/tools/base.py`](https://github.com/mercphobia/krol/blob/main/src/krol/tools/base.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_provider["Model providers<br/>[base.py]"]
  node_types["Chat types<br/>[types.py]"]
  node_tokens["Token economy<br/>[tokens.py]"]
  node_compact["History compaction<br/>[compaction.py]"]
end

subgraph group_safety["Safety and tools"]
  node_policy["Policy session<br/>[session.py]"]
  node_tools["Tool registry<br/>[base.py]"]
  node_builtins["Built-in tools<br/>[filesystem.py]"]
  node_upgrade["Self-upgrade<br/>[tool.py]"]
  node_checkpoint[("Checkpoints<br/>[checkpoint.py]")]
end

subgraph group_autonomy["Memory and autonomy"]
  node_memory[("Persistent memory<br/>[store.py]")]
  node_recall["Memory recall<br/>[recall.py]"]
  node_goals["Goals and todos<br/>[goals.py]"]
  node_scheduler["Cron scheduler<br/>[jobs.py]"]
  node_subagents["Subagents<br/>[orchestrator.py]"]
end

subgraph group_extensions["Extensions"]
  node_skills["Skills<br/>[registry.py]"]
  node_mods["Mods and hooks<br/>[runtime.py]"]
  node_mcp["MCP client<br/>[client.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_webui["Web UI<br/>[webui.py]"]
  node_chat["Chat interfaces<br/>[chat.py]"]
  node_telegram["Telegram<br/>[telegram.py]"]
  node_discord["Discord<br/>[discord.py]"]
  node_api["HTTP API<br/>[server.py]"]
  node_tui["Node TUI<br/>[app.mjs]"]
  node_host["Python TUI host<br/>[host.py]"]
end

node_user(("User"))

node_user -->|"submits prompt"| node_cli
node_cli -->|"starts agent"| node_loop
node_loop -->|"streams requests"| node_provider
node_loop -->|"checks tool calls"| node_policy
node_policy -->|"executes guarded"| node_tools
node_tools -->|"registers tools"| node_builtins
node_tools -->|"registers tool"| node_upgrade
node_policy -->|"creates checkpoints"| node_checkpoint
node_loop -->|"uses memory"| node_memory
node_loop -.->|"recalls context"| node_recall
node_loop -->|"compacts history"| node_compact
node_loop -->|"tracks usage"| node_tokens
node_cli -->|"manages goals"| node_goals
node_cli -->|"manages schedules"| node_scheduler
node_loop -.->|"delegates work"| node_subagents
node_loop -->|"loads relevant skills"| node_skills
node_loop -->|"dispatches hooks"| node_mods
node_cli -->|"connects servers"| node_mcp
node_user -->|"sends messages"| node_webui
node_webui -->|"routes messages"| node_chat
node_user -->|"chats with agent"| node_telegram
node_user -->|"chats with agent"| node_discord
node_user -->|"sends requests"| node_api
node_user -->|"enters terminal text"| node_tui
node_tui -->|"sends frames"| node_host
node_host -.->|"runs agent"| node_loop

click node_cli "https://github.com/mercphobia/krol/blob/main/src/krol/cli.py"
click node_loop "https://github.com/mercphobia/krol/blob/main/src/krol/core/loop.py"
click node_provider "https://github.com/mercphobia/krol/blob/main/src/krol/models/base.py"
click node_types "https://github.com/mercphobia/krol/blob/main/src/krol/types.py"
click node_tokens "https://github.com/mercphobia/krol/blob/main/src/krol/tokens.py"
click node_compact "https://github.com/mercphobia/krol/blob/main/src/krol/compaction.py"
click node_policy "https://github.com/mercphobia/krol/blob/main/src/krol/policy/session.py"
click node_tools "https://github.com/mercphobia/krol/blob/main/src/krol/tools/base.py"
click node_builtins "https://github.com/mercphobia/krol/blob/main/src/krol/tools/filesystem.py"
click node_upgrade "https://github.com/mercphobia/krol/blob/main/src/krol/self_upgrade/tool.py"
click node_checkpoint "https://github.com/mercphobia/krol/blob/main/src/krol/policy/checkpoint.py"
click node_memory "https://github.com/mercphobia/krol/blob/main/src/krol/memory/store.py"
click node_recall "https://github.com/mercphobia/krol/blob/main/src/krol/memory/recall.py"
click node_goals "https://github.com/mercphobia/krol/blob/main/src/krol/goals.py"
click node_scheduler "https://github.com/mercphobia/krol/blob/main/src/krol/sched/jobs.py"
click node_subagents "https://github.com/mercphobia/krol/blob/main/src/krol/subagents/orchestrator.py"
click node_skills "https://github.com/mercphobia/krol/blob/main/src/krol/skills/registry.py"
click node_mods "https://github.com/mercphobia/krol/blob/main/src/krol/mods/runtime.py"
click node_mcp "https://github.com/mercphobia/krol/blob/main/src/krol/mcp/client.py"
click node_webui "https://github.com/mercphobia/krol/blob/main/src/krol/ui/webui.py"
click node_chat "https://github.com/mercphobia/krol/blob/main/src/krol/ui/chat.py"
click node_telegram "https://github.com/mercphobia/krol/blob/main/src/krol/ui/telegram.py"
click node_discord "https://github.com/mercphobia/krol/blob/main/src/krol/ui/discord.py"
click node_api "https://github.com/mercphobia/krol/blob/main/src/krol/api/server.py"
click node_tui "https://github.com/mercphobia/krol/blob/main/tui/src/app.mjs"
click node_host "https://github.com/mercphobia/krol/blob/main/src/krol/ui/host.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_loop,node_provider,node_types,node_tokens,node_compact,node_user toneBlue
class node_policy,node_tools,node_builtins,node_upgrade,node_checkpoint toneAmber
class node_memory,node_recall,node_goals,node_scheduler,node_subagents toneMint
class node_skills,node_mods,node_mcp toneRose
class node_cli,node_webui,node_chat,node_telegram,node_discord,node_api,node_tui,node_host toneIndigo
```

## Components

### Agent runtime

- [Agent loop](https://github.com/mercphobia/krol/blob/main/src/krol/core/loop.py): `src/krol/core/loop.py`
- [Model providers](https://github.com/mercphobia/krol/blob/main/src/krol/models/base.py): `src/krol/models/base.py`
- [Chat types](https://github.com/mercphobia/krol/blob/main/src/krol/types.py): `src/krol/types.py`
- [Token economy](https://github.com/mercphobia/krol/blob/main/src/krol/tokens.py): `src/krol/tokens.py`
- [History compaction](https://github.com/mercphobia/krol/blob/main/src/krol/compaction.py): `src/krol/compaction.py`

### Safety and tools

- [Policy session](https://github.com/mercphobia/krol/blob/main/src/krol/policy/session.py): `src/krol/policy/session.py`
- [Tool registry](https://github.com/mercphobia/krol/blob/main/src/krol/tools/base.py): `src/krol/tools/base.py`
- [Built-in tools](https://github.com/mercphobia/krol/blob/main/src/krol/tools/filesystem.py): `src/krol/tools/filesystem.py`
- [Self-upgrade](https://github.com/mercphobia/krol/blob/main/src/krol/self_upgrade/tool.py): `src/krol/self_upgrade/tool.py`
- [Checkpoints](https://github.com/mercphobia/krol/blob/main/src/krol/policy/checkpoint.py): `src/krol/policy/checkpoint.py`

### Memory and autonomy

- [Persistent memory](https://github.com/mercphobia/krol/blob/main/src/krol/memory/store.py): `src/krol/memory/store.py`
- [Memory recall](https://github.com/mercphobia/krol/blob/main/src/krol/memory/recall.py): `src/krol/memory/recall.py`
- [Goals and todos](https://github.com/mercphobia/krol/blob/main/src/krol/goals.py): `src/krol/goals.py`
- [Cron scheduler](https://github.com/mercphobia/krol/blob/main/src/krol/sched/jobs.py): `src/krol/sched/jobs.py`
- [Subagents](https://github.com/mercphobia/krol/blob/main/src/krol/subagents/orchestrator.py): `src/krol/subagents/orchestrator.py`

### Extensions

- [Skills](https://github.com/mercphobia/krol/blob/main/src/krol/skills/registry.py): `src/krol/skills/registry.py`
- [Mods and hooks](https://github.com/mercphobia/krol/blob/main/src/krol/mods/runtime.py): `src/krol/mods/runtime.py`
- [MCP client](https://github.com/mercphobia/krol/blob/main/src/krol/mcp/client.py): `src/krol/mcp/client.py`

### Interfaces

- [CLI](https://github.com/mercphobia/krol/blob/main/src/krol/cli.py): `src/krol/cli.py`
- [Web UI](https://github.com/mercphobia/krol/blob/main/src/krol/ui/webui.py): `src/krol/ui/webui.py`
- [Chat interfaces](https://github.com/mercphobia/krol/blob/main/src/krol/ui/chat.py): `src/krol/ui/chat.py`
- [Telegram](https://github.com/mercphobia/krol/blob/main/src/krol/ui/telegram.py): `src/krol/ui/telegram.py`
- [Discord](https://github.com/mercphobia/krol/blob/main/src/krol/ui/discord.py): `src/krol/ui/discord.py`
- [HTTP API](https://github.com/mercphobia/krol/blob/main/src/krol/api/server.py): `src/krol/api/server.py`
- [Node TUI](https://github.com/mercphobia/krol/blob/main/tui/src/app.mjs): `tui/src/app.mjs`
- [Python TUI host](https://github.com/mercphobia/krol/blob/main/src/krol/ui/host.py): `src/krol/ui/host.py`

### Other components

- **User**

## Connections

- User → CLI: submits prompt (evidence: `README.md`)
- CLI → Agent loop: starts agent (evidence: `src/krol/cli.py`)
- Agent loop → Model providers: streams requests (evidence: `src/krol/core/loop.py`)
- Agent loop → Policy session: checks tool calls (evidence: `src/krol/core/loop.py`)
- Policy session → Tool registry: executes guarded (evidence: `src/krol/policy/session.py`)
- Tool registry → Built-in tools: registers tools (evidence: `src/krol/tools/__init__.py`)
- Tool registry → Self-upgrade: registers tool (evidence: `src/krol/tools/__init__.py`)
- Policy session → Checkpoints: creates checkpoints (evidence: `src/krol/policy/session.py`)
- Agent loop → Persistent memory: uses memory (evidence: `src/krol/core/loop.py`)
- Agent loop → Memory recall: recalls context
- Agent loop → History compaction: compacts history (evidence: `src/krol/core/loop.py`)
- Agent loop → Token economy: tracks usage (evidence: `src/krol/core/loop.py`)
- CLI → Goals and todos: manages goals (evidence: `README.md`)
- CLI → Cron scheduler: manages schedules (evidence: `README.md`)
- Agent loop → Subagents: delegates work
- Agent loop → Skills: loads relevant skills (evidence: `src/krol/core/loop.py`)
- Agent loop → Mods and hooks: dispatches hooks (evidence: `src/krol/core/loop.py`)
- CLI → MCP client: connects servers (evidence: `README.md`)
- User → Web UI: sends messages (evidence: `README.md`)
- Web UI → Chat interfaces: routes messages (evidence: `src/krol/ui/webui.py`)
- User → Telegram: chats with agent (evidence: `README.md`)
- User → Discord: chats with agent (evidence: `README.md`)
- User → HTTP API: sends requests (evidence: `README.md`)
- User → Node TUI: enters terminal text (evidence: `tui/src/app.mjs`)
- Node TUI → Python TUI host: sends frames
- Python TUI host → Agent loop: runs agent
