# thirumalai-tech-developer/kratos-agent architecture

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

- Interactive diagram: https://gitdiagram.com/thirumalai-tech-developer/kratos-agent
- Repository: https://github.com/thirumalai-tech-developer/kratos-agent

## Overview

Kratos Agent is a terminal-based autonomous coding agent. A user request enters through the CLI, is planned and assembled into model context, sent to an LLM, and may trigger approval-gated workspace tools; the runtime then verifies work, records session history, and presents progress in the TUI. The graph preserves documented capabilities such as skills, MCP, memory, tool forging, and engineering workflows. Several subsystems are represented by their tree paths because their source was not excerpted; edges are limited to README statements and indexed references.

Main entry points: [`src/kratos_agent/main.py`](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/main.py) (Runtime composition), [`src/kratos_agent/core/agent_loop.py`](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/agent_loop.py) (Agent loop), [`src/kratos_agent/cli.py`](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/cli.py) (Terminal CLI), [`src/kratos_agent/brain/client.py`](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/brain/client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_cli["Terminal CLI<br/>[cli.py]"]
  node_tui["Live TUI<br/>[live_renderer.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_runtime_app["Runtime composition<br/>[main.py]"]
  node_agent_loop["Agent loop<br/>[agent_loop.py]"]
  node_planner["Task planning<br/>[planner.py]"]
  node_task_state["Task state<br/>[task_manager.py]"]
  node_instructions["Instruction assembly"]
  node_context["Context assembly"]
  node_approval["Approval gates<br/>[approval_mode.py]"]
end

subgraph group_model["Model gateway"]
  node_brain["Chat model<br/>[chat_model.py]"]
  node_client["LLM client<br/>[client.py]"]
  node_gateway["LLM gateway"]
end

subgraph group_workspace["Workspace capabilities"]
  node_tools["Workspace tools<br/>[tools.py]"]
  node_verification["Verification"]
  node_git["Git workflows<br/>[git_tools.py]"]
  node_tool_forge["Tool forging<br/>[tool_creator.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_mcp["MCP tools<br/>[mcp_runtime.py]"]
  node_review_prompts["Review workflows<br/>[prompt_library.py]"]
end

subgraph group_state["State and feedback"]
  node_memory[("Session memory<br/>[memory.py]")]
  node_project_memory[("Project memory<br/>[project_memory.py]")]
  node_event_store[("Session event store<br/>[event_store.py]")]
  node_event_bus["Runtime events<br/>[event_bus.py]"]
  node_latency["Latency tracking<br/>[latency_tracker.py]"]
end

node_user(("Developer"))

node_user -->|"submits request"| node_cli
node_cli -->|"enters runtime"| node_runtime_app
node_runtime_app -->|"runs loop"| node_agent_loop
node_agent_loop -->|"plans tasks"| node_planner
node_agent_loop -->|"assembles context"| node_context
node_agent_loop -->|"updates tasks"| node_task_state
node_runtime_app -->|"builds instructions"| node_instructions
node_context -->|"provides request"| node_brain
node_brain -->|"sends completion"| node_client
node_client -->|"posts requests"| node_gateway
node_client -->|"records metrics"| node_latency
node_agent_loop -->|"checks permissions"| node_approval
node_agent_loop -->|"executes tools"| node_tools
node_agent_loop -->|"verifies output"| node_verification
node_runtime_app -->|"restores sessions"| node_memory
node_runtime_app -->|"opens session trace"| node_event_store
node_agent_loop -->|"emits events"| node_event_bus
node_tui -->|"invokes runtime"| node_runtime_app
node_tui -->|"renders events"| node_event_bus
node_runtime_app -->|"loads skills"| node_skills
node_runtime_app -->|"configures MCP"| node_mcp
node_runtime_app -->|"loads project memory"| node_project_memory
node_cli -->|"creates tools"| node_tool_forge
node_cli -->|"offers git workflows"| node_git
node_cli -->|"offers review commands"| node_review_prompts

click node_cli "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/cli.py"
click node_tui "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/tui/live_renderer.py"
click node_runtime_app "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/main.py"
click node_agent_loop "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/agent_loop.py"
click node_planner "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/planner.py"
click node_task_state "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/task_manager.py"
click node_instructions "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/instruction_engine.py"
click node_context "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/context_pipeline.py"
click node_approval "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/approval_mode.py"
click node_brain "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/brain/chat_model.py"
click node_client "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/brain/client.py"
click node_tools "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/utils/tools.py"
click node_verification "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/verification_manager.py"
click node_git "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/git_tools.py"
click node_tool_forge "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/utils/tool_creator.py"
click node_skills "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/skills.py"
click node_mcp "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/mcp_runtime.py"
click node_memory "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/memory.py"
click node_project_memory "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/project_memory.py"
click node_event_store "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/event_store.py"
click node_event_bus "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/event_bus.py"
click node_latency "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/latency_tracker.py"
click node_review_prompts "https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/prompt_library.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_cli,node_tui toneBlue
class node_runtime_app,node_agent_loop,node_planner,node_task_state,node_instructions,node_context,node_approval toneAmber
class node_brain,node_client,node_gateway toneMint
class node_tools,node_verification,node_git,node_tool_forge,node_skills,node_mcp,node_review_prompts toneRose
class node_memory,node_project_memory,node_event_store,node_event_bus,node_latency,node_user toneIndigo
```

## Components

### User interface

- [Terminal CLI](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/cli.py): `src/kratos_agent/cli.py`
- [Live TUI](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/tui/live_renderer.py): `src/kratos_agent/tui/live_renderer.py`

### Agent runtime

- [Runtime composition](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/main.py): `src/kratos_agent/main.py`
- [Agent loop](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/agent_loop.py): `src/kratos_agent/core/agent_loop.py`
- [Task planning](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/planner.py): `src/kratos_agent/core/planner.py`
- [Task state](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/task_manager.py): `src/kratos_agent/core/task_manager.py`
- [Instruction assembly](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/instruction_engine.py): `src/kratos_agent/core/instruction_engine.py`
- [Context assembly](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/context_pipeline.py): `src/kratos_agent/core/context_pipeline.py`
- [Approval gates](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/approval_mode.py): `src/kratos_agent/core/approval_mode.py`

### Model gateway

- [Chat model](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/brain/chat_model.py): `src/kratos_agent/brain/chat_model.py`
- [LLM client](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/brain/client.py): `src/kratos_agent/brain/client.py`
- **LLM gateway**

### Workspace capabilities

- [Workspace tools](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/utils/tools.py): `src/kratos_agent/utils/tools.py`
- [Verification](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/verification_manager.py): `src/kratos_agent/core/verification_manager.py`
- [Git workflows](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/git_tools.py): `src/kratos_agent/core/git_tools.py`
- [Tool forging](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/utils/tool_creator.py): `src/kratos_agent/utils/tool_creator.py`
- [Skills](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/skills.py): `src/kratos_agent/core/skills.py`
- [MCP tools](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/mcp_runtime.py): `src/kratos_agent/core/mcp_runtime.py`
- [Review workflows](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/prompt_library.py): `src/kratos_agent/core/prompt_library.py`

### State and feedback

- [Session memory](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/memory.py): `src/kratos_agent/core/memory.py`
- [Project memory](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/project_memory.py): `src/kratos_agent/core/project_memory.py`
- [Session event store](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/event_store.py): `src/kratos_agent/core/event_store.py`
- [Runtime events](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/event_bus.py): `src/kratos_agent/core/event_bus.py`
- [Latency tracking](https://github.com/thirumalai-tech-developer/kratos-agent/blob/main/src/kratos_agent/core/latency_tracker.py): `src/kratos_agent/core/latency_tracker.py`

### Other components

- **Developer**

## Connections

- Developer → Terminal CLI: submits request (evidence: `README.md`)
- Terminal CLI → Runtime composition: enters runtime (evidence: `src/kratos_agent/main.py`)
- Runtime composition → Agent loop: runs loop (evidence: `src/kratos_agent/main.py`)
- Agent loop → Task planning: plans tasks (evidence: `src/kratos_agent/core/agent_loop.py`)
- Agent loop → Context assembly: assembles context (evidence: `src/kratos_agent/core/agent_loop.py`)
- Agent loop → Task state: updates tasks (evidence: `src/kratos_agent/core/agent_loop.py`)
- Runtime composition → Instruction assembly: builds instructions (evidence: `src/kratos_agent/main.py`)
- Context assembly → Chat model: provides request (evidence: `README.md`)
- Chat model → LLM client: sends completion (evidence: `src/kratos_agent/brain/__init__.py`)
- LLM client → LLM gateway: posts requests (evidence: `src/kratos_agent/brain/client.py`)
- LLM client → Latency tracking: records metrics (evidence: `src/kratos_agent/brain/client.py`)
- Agent loop → Approval gates: checks permissions (evidence: `README.md`)
- Agent loop → Workspace tools: executes tools (evidence: `README.md`)
- Agent loop → Verification: verifies output (evidence: `README.md`)
- Runtime composition → Session memory: restores sessions (evidence: `src/kratos_agent/main.py`)
- Runtime composition → Session event store: opens session trace (evidence: `src/kratos_agent/main.py`)
- Agent loop → Runtime events: emits events (evidence: `src/kratos_agent/core/agent_loop.py`)
- Live TUI → Runtime composition: invokes runtime (evidence: `src/kratos_agent/tui/live_renderer.py`)
- Live TUI → Runtime events: renders events (evidence: `src/kratos_agent/tui/live_renderer.py`)
- Runtime composition → Skills: loads skills (evidence: `src/kratos_agent/main.py`)
- Runtime composition → MCP tools: configures MCP (evidence: `src/kratos_agent/main.py`)
- Runtime composition → Project memory: loads project memory (evidence: `src/kratos_agent/main.py`)
- Terminal CLI → Tool forging: creates tools (evidence: `src/kratos_agent/cli.py`)
- Terminal CLI → Git workflows: offers git workflows (evidence: `src/kratos_agent/cli.py`)
- Terminal CLI → Review workflows: offers review commands (evidence: `src/kratos_agent/cli.py`)
