# youngyangyang04/kamaclaude architecture

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

- Interactive diagram: https://gitdiagram.com/youngyangyang04/kamaclaude
- Repository: https://github.com/youngyangyang04/kamaclaude

## Overview

#### Purpose and deployment shape
KamaClaude is a local, daemon-backed coding-agent runtime: clients submit goals, while the Core executes multi-step LLM/tool workflows and exposes execution as durable and live event streams. Python entry points separate the daemon, CLI, and TUI:
- `src/kama_claude/core/__main__.py`
- `src/kama_claude/cli/__main__.py`
- `src/kama_claude/tui/__main__.py`

#### Client–daemon protocol boundary
CLI commands and the TUI are IPC clients rather than agent hosts. The daemon exposes typed commands/events over socket transport; the wire contract is JSON-RPC 2.0 over NDJSON. This permits multiple clients, ongoing task execution after a client exits, and future alternate front ends.
- `src/kama_claude/cli/main.py`
- `src/kama_claude/core/transport/socket_server.py`
- `src/kama_claude/core/bus/envelope.py`
- `WIRE_PROTOCOL.md`

#### Core application and run orchestration
The Core application assembles runtime services and dispatches incoming commands. A runner creates/continues runs, coordinates session state, and invokes the agent loop. The loop implements the ReAct-like cycle: construct context, call an LLM, execute requested tools, feed results back, and stop on a final response or failure.
- `src/kama_claude/core/app.py`
- `src/kama_claude/core/runner.py`
- `src/kama_claude/core/loop.py`
- `src/kama_claude/core/runs.py`

#### LLM, tools, and safety gate
The LLM provider layer isolates model integrations behind common request/response types. Tool calls are resolved through a registry and invocation boundary; local filesystem/shell and task-management tools are built in. Permission management is a hard control boundary before sensitive execution, supporting policy, storage, approval, error classification, and retry-oriented handling.
- `src/kama_claude/core/llm/provider.py`
- `src/kama_claude/core/tools/registry.py`
- `src/kama_claude/core/tools/invocation.py`
- `src/kama_claude/core/permissions/manager.py`

#### Events, persistence, and observability
Execution is externalized through an event bus. Events serve both real-time subscribers—via IPC broadcasting—and persistent run records; trace providers/writers capture cross-layer timelines for IPC, event, and LLM diagnosis/replay. The TUI consumes this observable execution state rather than directly driving internals.
- `src/kama_claude/core/events/bus.py`
- `src/kama_claude/core/events/writer.py`
- `src/kama_claude/core/transport/ipc_broadcaster.py`
- `src/kama_claude/core/trace/writer.py`

#### Stateful context lifecycle
Sessions preserve multi-turn interaction using models, management, and storage. Context construction combines thread/history and notes/memory; budget and compactor stages govern long-running conversations by detecting pressure, trimming tool results, and compacting context rather than blindly growing prompts.
- `src/kama_claude/core/session/manager.py`
- `src/kama_claude/core/context.py`
- `src/kama_claude/core/compact/compactor.py`
- `src/kama_claude/core/memory/loader.py`

#### Extensibility and agent composition
Built-in agent profiles and Markdown skills provide role/workflow instructions. Subagents expose delegated work through the tool system, while MCP client/server/tool modules integrate externally supplied tools into the same invocation, permission, event, and context pipeline.
- `src/kama_claude/core/agents/loader.py`
- `src/kama_claude/core/skills/loader.py`
- `src/kama_claude/core/subagent/tool.py`
- `src/kama_claude/core/mcp/client.py`

Main entry points: [`src/kama_claude/core/loop.py`](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/loop.py) (Agent loop), [`src/kama_claude/core/tools/registry.py`](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/tools/registry.py) (Tool registry), [`src/kama_claude/core/events/bus.py`](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/events/bus.py) (Event bus), [`src/kama_claude/core/transport/socket_server.py`](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/transport/socket_server.py) (Socket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_cli["CLI<br/>[main.py]"]
  node_tui["TUI<br/>IPC client<br/>[__main__.py]"]
end

subgraph group_daemon["Daemon boundary"]
  node_wire["JSON-RPC / NDJSON<br/>wire contract<br/>[WIRE_PROTOCOL.md]"]
  node_socket_server["Socket server<br/>IPC transport<br/>[socket_server.py]"]
  node_core_app{{"Core application<br/>daemon composition<br/>[app.py]"}}
  node_ipc_broadcaster["IPC broadcaster<br/>live event delivery<br/>[ipc_broadcaster.py]"]
end

subgraph group_execution["Agent execution"]
  node_runner["Runner<br/>run orchestrator<br/>[runner.py]"]
  node_agent_loop{{"Agent loop<br/>ReAct loop<br/>[loop.py]"}}
end

subgraph group_extensions["Capabilities"]
  node_llm_provider["LLM provider<br/>model adapter<br/>[provider.py]"]
  node_tool_registry["Tool registry<br/>tool resolution<br/>[registry.py]"]
  node_tool_invocation["Tool invocation<br/>execution boundary<br/>[invocation.py]"]
  node_permissions{{"Permission manager<br/>safety gate<br/>[manager.py]"}}
  node_agent_profiles["Agents and skills<br/>instruction loading<br/>[loader.py]"]
  node_subagent_tool["Subagent tool<br/>delegation<br/>[tool.py]"]
  node_mcp_client["MCP integration<br/>external tools<br/>[client.py]"]
end

subgraph group_state["Durable state"]
  node_session_manager[("Session manager<br/>conversation state<br/>[manager.py]")]
  node_context["Context lifecycle<br/>prompt assembly<br/>[context.py]"]
  node_compactor["Context compactor<br/>context reduction<br/>[compactor.py]"]
  node_event_bus["Event bus<br/>execution stream<br/>[bus.py]"]
  node_event_writer[("Run event writer<br/>durable records<br/>[writer.py]")]
  node_trace_writer[("Trace writer<br/>diagnostics<br/>[writer.py]")]
end

node_cli -->|"commands"| node_wire
node_tui -->|"commands and events"| node_wire
node_wire -->|"implemented by"| node_socket_server
node_socket_server -->|"dispatches commands"| node_core_app
node_core_app -->|"starts or resumes run"| node_runner
node_runner -->|"coordinates session"| node_session_manager
node_runner -->|"invokes"| node_agent_loop
node_agent_loop -->|"constructs prompt context"| node_context
node_context -->|"compacts under budget pressure"| node_compactor
node_agent_loop -->|"model request"| node_llm_provider
node_agent_loop -->|"resolves requested tool"| node_tool_registry
node_tool_registry -->|"selected tool"| node_tool_invocation
node_tool_invocation -->|"authorization before execution"| node_permissions
node_tool_registry -.->|"delegated capability"| node_subagent_tool
node_tool_registry -.->|"external capability"| node_mcp_client
node_agent_profiles -.->|"instructions"| node_context
node_agent_loop -->|"execution events"| node_event_bus
node_event_bus -->|"persists run events"| node_event_writer
node_event_bus -->|"broadcasts live events"| node_ipc_broadcaster
node_ipc_broadcaster -->|"observable state"| node_tui
node_socket_server -.->|"IPC traces"| node_trace_writer
node_event_bus -.->|"event traces"| node_trace_writer
node_llm_provider -.->|"LLM traces"| node_trace_writer

click node_cli "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/cli/main.py"
click node_tui "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/tui/__main__.py"
click node_wire "https://github.com/youngyangyang04/kamaclaude/blob/main/WIRE_PROTOCOL.md"
click node_socket_server "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/transport/socket_server.py"
click node_core_app "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/app.py"
click node_runner "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/runner.py"
click node_agent_loop "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/loop.py"
click node_llm_provider "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/llm/provider.py"
click node_tool_registry "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/tools/registry.py"
click node_tool_invocation "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/tools/invocation.py"
click node_permissions "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/permissions/manager.py"
click node_agent_profiles "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/agents/loader.py"
click node_subagent_tool "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/subagent/tool.py"
click node_mcp_client "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/mcp/client.py"
click node_session_manager "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/session/manager.py"
click node_context "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/context.py"
click node_compactor "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/compact/compactor.py"
click node_event_bus "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/events/bus.py"
click node_event_writer "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/events/writer.py"
click node_ipc_broadcaster "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/transport/ipc_broadcaster.py"
click node_trace_writer "https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/trace/writer.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_wire,node_socket_server,node_core_app,node_ipc_broadcaster toneAmber
class node_runner,node_agent_loop toneMint
class node_llm_provider,node_tool_registry,node_tool_invocation,node_permissions,node_agent_profiles,node_subagent_tool,node_mcp_client toneRose
class node_session_manager,node_context,node_compactor,node_event_bus,node_event_writer,node_trace_writer toneIndigo
```

## Components

### Clients

Independent IPC front ends.

- [CLI](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/cli/main.py): IPC client · `src/kama_claude/cli/main.py`
- [TUI](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/tui/__main__.py): IPC client · Renders observable execution state. · `src/kama_claude/tui/__main__.py`

### Daemon boundary

Long-lived command and event service.

- [JSON-RPC / NDJSON](https://github.com/youngyangyang04/kamaclaude/blob/main/WIRE_PROTOCOL.md): wire contract · Typed commands and events over socket transport. · `WIRE_PROTOCOL.md`
- [Socket server](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/transport/socket_server.py): IPC transport · `src/kama_claude/core/transport/socket_server.py`
- [Core application](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/app.py): daemon composition · Assembles services and dispatches commands. · `src/kama_claude/core/app.py`
- [IPC broadcaster](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/transport/ipc_broadcaster.py): live event delivery · `src/kama_claude/core/transport/ipc_broadcaster.py`

### Agent execution

Run orchestration and ReAct workflow.

- [Runner](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/runner.py): run orchestrator · Creates or resumes runs and coordinates sessions. · `src/kama_claude/core/runner.py`
- [Agent loop](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/loop.py): ReAct loop · Builds context, calls the model, executes tools, and terminates runs. · `src/kama_claude/core/loop.py`

### Capabilities

Models, tools, safety, and delegated integrations.

- [LLM provider](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/llm/provider.py): model adapter · Common model request and response boundary. · `src/kama_claude/core/llm/provider.py`
- [Tool registry](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/tools/registry.py): tool resolution · Includes local filesystem, shell, and task tools. · `src/kama_claude/core/tools/registry.py`
- [Tool invocation](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/tools/invocation.py): execution boundary · `src/kama_claude/core/tools/invocation.py`
- [Permission manager](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/permissions/manager.py): safety gate · Policy, approval, classification, and retry control before sensitive execution. · `src/kama_claude/core/permissions/manager.py`
- [Agents and skills](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/agents/loader.py): instruction loading · Loads built-in profiles and Markdown workflow instructions. · `src/kama_claude/core/agents/loader.py`
- [Subagent tool](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/subagent/tool.py): delegation · Exposes delegated work through the tool system. · `src/kama_claude/core/subagent/tool.py`
- [MCP integration](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/mcp/client.py): external tools · Adapts externally supplied tools into the common pipeline. · `src/kama_claude/core/mcp/client.py`

### Durable state

Session context, events, and diagnostic records.

- [Session manager](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/session/manager.py): conversation state · Preserves multi-turn interaction. · `src/kama_claude/core/session/manager.py`
- [Context lifecycle](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/context.py): prompt assembly · Combines history and memory; manages budget pressure. · `src/kama_claude/core/context.py`
- [Context compactor](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/compact/compactor.py): context reduction · Trims tool results and compacts long conversations. · `src/kama_claude/core/compact/compactor.py`
- [Event bus](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/events/bus.py): execution stream · Externalizes live execution events. · `src/kama_claude/core/events/bus.py`
- [Run event writer](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/events/writer.py): durable records · `src/kama_claude/core/events/writer.py`
- [Trace writer](https://github.com/youngyangyang04/kamaclaude/blob/main/src/kama_claude/core/trace/writer.py): diagnostics · Captures IPC, event, and LLM timelines for diagnosis and replay. · `src/kama_claude/core/trace/writer.py`

## Connections

- CLI → JSON-RPC / NDJSON: commands
- TUI → JSON-RPC / NDJSON: commands and events
- JSON-RPC / NDJSON → Socket server: implemented by
- Socket server → Core application: dispatches commands
- Core application → Runner: starts or resumes run
- Runner → Session manager: coordinates session
- Runner → Agent loop: invokes
- Agent loop → Context lifecycle: constructs prompt context
- Context lifecycle → Context compactor: compacts under budget pressure
- Agent loop → LLM provider: model request
- Agent loop → Tool registry: resolves requested tool
- Tool registry → Tool invocation: selected tool
- Tool invocation → Permission manager: authorization before execution
- Tool registry → Subagent tool: delegated capability
- Tool registry → MCP integration: external capability
- Agents and skills → Context lifecycle: instructions
- Agent loop → Event bus: execution events
- Event bus → Run event writer: persists run events
- Event bus → IPC broadcaster: broadcasts live events
- IPC broadcaster → TUI: observable state
- Socket server → Trace writer: IPC traces
- Event bus → Trace writer: event traces
- LLM provider → Trace writer: LLM traces