# maka-agent/maka-agent architecture

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

## Overview

Maka is a local-first agent workspace whose central workflow is: a user starts a task in Desktop or a terminal client, the Runtime Host executes it through a session and agent run, and an append-only event record supports the resulting UI, future prompts, and recovery. The README also describes evaluation as a separate experiment/cell/attempt/results flow that uses the same execution authority. Edges are based on README statements and SOURCE INDEX references; unsampled implementation details are represented only at documented subsystem boundaries.

Main entry points: [`packages/runtime`](https://github.com/maka-agent/maka-agent/tree/main/packages/runtime) (Agent Run), [`packages/storage`](https://github.com/maka-agent/maka-agent/tree/main/packages/storage) (Runtime Event Log), [`packages/runtime-host`](https://github.com/maka-agent/maka-agent/tree/main/packages/runtime-host) (Runtime Host), [`packages/runtime/src/plugin-runtime.ts`](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-runtime.ts) (Plugin Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_desktop["Desktop<br/>[app.tsx]"]
  node_terminal["TUI and CLI"]
end

subgraph group_execution["Execution Runtime"]
  node_host["Runtime Host"]
  node_sessions["Session Manager<br/>[session-manager.ts]"]
  node_agentrun["Agent Run"]
  node_modeltools["Model and Tools<br/>[tool-runtime.ts]"]
  node_plugins["Plugin Runtime<br/>[plugin-runtime.ts]"]
  node_pluginagents["Plugin Agents"]
  node_pluginllm["Plugin LLM"]
  node_pluginqueries["Plugin Queries"]
  node_mcp["MCP Integration<br/>[index.ts]"]
  node_computeruse["Computer Use<br/>[maka-cu-service.ts]"]
end

subgraph group_records["Records and Projections"]
  node_eventlog[("Runtime Event Log")]
  node_localstate[("Local State")]
  node_memory[("Long-Term Memory")]
  node_projections["UI Projections"]
end

subgraph group_evaluation["Evaluation"]
  node_experiment["Experiment"]
  node_cells["Cells"]
  node_attempts["Attempts"]
  node_results["Results"]
end

node_user(("User"))

node_user -->|"starts task"| node_desktop
node_user -->|"starts task"| node_terminal
node_desktop -->|"requests execution"| node_host
node_terminal -->|"requests execution"| node_host
node_host -->|"dispatches to"| node_sessions
node_sessions -->|"runs session"| node_agentrun
node_agentrun -->|"uses"| node_modeltools
node_modeltools -->|"appends events"| node_eventlog
node_eventlog -->|"projects into UI"| node_projections
node_eventlog -->|"informs next prompt"| node_agentrun
node_eventlog -->|"supports recovery"| node_sessions
node_plugins -->|"provides service"| node_pluginagents
node_plugins -->|"provides service"| node_pluginllm
node_plugins -->|"provides service"| node_pluginqueries
node_pluginagents -->|"supplies invocation"| node_pluginllm
node_pluginagents -->|"supplies caller"| node_pluginqueries
node_agentrun -.->|"uses integration"| node_mcp
node_agentrun -.->|"uses integration"| node_computeruse
node_localstate -->|"opens store"| node_memory
node_experiment -->|"defines"| node_cells
node_cells -->|"runs"| node_attempts
node_attempts -->|"produces"| node_results
node_attempts -->|"executes subjects"| node_host

click node_desktop "https://github.com/maka-agent/maka-agent/blob/main/apps/desktop/src/renderer/app.tsx"
click node_terminal "https://github.com/maka-agent/maka-agent/tree/main/packages/cli"
click node_host "https://github.com/maka-agent/maka-agent/tree/main/packages/runtime-host"
click node_sessions "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/session-manager.ts"
click node_agentrun "https://github.com/maka-agent/maka-agent/tree/main/packages/runtime"
click node_modeltools "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/tool-runtime.ts"
click node_plugins "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-runtime.ts"
click node_pluginagents "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-agent-service.ts"
click node_pluginllm "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-llm-service.ts"
click node_pluginqueries "https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-session-query-service.ts"
click node_mcp "https://github.com/maka-agent/maka-agent/blob/main/packages/mcp/src/index.ts"
click node_computeruse "https://github.com/maka-agent/maka-agent/blob/main/packages/computer-use/src/maka-cu-service.ts"
click node_eventlog "https://github.com/maka-agent/maka-agent/tree/main/packages/storage"
click node_localstate "https://github.com/maka-agent/maka-agent/blob/main/packages/storage/src/storage-writer-composition.ts"
click node_memory "https://github.com/maka-agent/maka-agent/blob/main/packages/storage/src/long-term-memory-store.ts"
click node_projections "https://github.com/maka-agent/maka-agent/tree/main/packages/ui"
click node_experiment "https://github.com/maka-agent/maka-agent/tree/main/packages/eval"
click node_cells "https://github.com/maka-agent/maka-agent/tree/main/packages/eval"
click node_attempts "https://github.com/maka-agent/maka-agent/tree/main/packages/eval"
click node_results "https://github.com/maka-agent/maka-agent/tree/main/packages/eval"

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_desktop,node_terminal,node_user toneBlue
class node_host,node_sessions,node_agentrun,node_modeltools,node_plugins,node_pluginagents,node_pluginllm,node_pluginqueries,node_mcp,node_computeruse toneAmber
class node_eventlog,node_localstate,node_memory,node_projections toneMint
class node_experiment,node_cells,node_attempts,node_results toneRose
```

## Components

### User Clients

- [Desktop](https://github.com/maka-agent/maka-agent/blob/main/apps/desktop/src/renderer/app.tsx): `apps/desktop/src/renderer/app.tsx`
- [TUI and CLI](https://github.com/maka-agent/maka-agent/tree/main/packages/cli): `packages/cli`

### Execution Runtime

- [Runtime Host](https://github.com/maka-agent/maka-agent/tree/main/packages/runtime-host): `packages/runtime-host`
- [Session Manager](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/session-manager.ts): `packages/runtime/src/session-manager.ts`
- [Agent Run](https://github.com/maka-agent/maka-agent/tree/main/packages/runtime): `packages/runtime`
- [Model and Tools](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/tool-runtime.ts): `packages/runtime/src/tool-runtime.ts`
- [Plugin Runtime](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-runtime.ts): `packages/runtime/src/plugin-runtime.ts`
- [Plugin Agents](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-agent-service.ts): `packages/runtime/src/plugin-agent-service.ts`
- [Plugin LLM](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-llm-service.ts): `packages/runtime/src/plugin-llm-service.ts`
- [Plugin Queries](https://github.com/maka-agent/maka-agent/blob/main/packages/runtime/src/plugin-session-query-service.ts): `packages/runtime/src/plugin-session-query-service.ts`
- [MCP Integration](https://github.com/maka-agent/maka-agent/blob/main/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`
- [Computer Use](https://github.com/maka-agent/maka-agent/blob/main/packages/computer-use/src/maka-cu-service.ts): `packages/computer-use/src/maka-cu-service.ts`

### Records and Projections

- [Runtime Event Log](https://github.com/maka-agent/maka-agent/tree/main/packages/storage): `packages/storage`
- [Local State](https://github.com/maka-agent/maka-agent/blob/main/packages/storage/src/storage-writer-composition.ts): `packages/storage/src/storage-writer-composition.ts`
- [Long-Term Memory](https://github.com/maka-agent/maka-agent/blob/main/packages/storage/src/long-term-memory-store.ts): `packages/storage/src/long-term-memory-store.ts`
- [UI Projections](https://github.com/maka-agent/maka-agent/tree/main/packages/ui): `packages/ui`

### Evaluation

- [Experiment](https://github.com/maka-agent/maka-agent/tree/main/packages/eval): `packages/eval`
- [Cells](https://github.com/maka-agent/maka-agent/tree/main/packages/eval): `packages/eval`
- [Attempts](https://github.com/maka-agent/maka-agent/tree/main/packages/eval): `packages/eval`
- [Results](https://github.com/maka-agent/maka-agent/tree/main/packages/eval): `packages/eval`

### Other components

- **User**

## Connections

- User → Desktop: starts task (evidence: `README.md`)
- User → TUI and CLI: starts task (evidence: `README.md`)
- Desktop → Runtime Host: requests execution (evidence: `README.md`)
- TUI and CLI → Runtime Host: requests execution (evidence: `README.md`)
- Runtime Host → Session Manager: dispatches to (evidence: `README.md`)
- Session Manager → Agent Run: runs session (evidence: `README.md`)
- Agent Run → Model and Tools: uses (evidence: `README.md`)
- Model and Tools → Runtime Event Log: appends events (evidence: `README.md`)
- Runtime Event Log → UI Projections: projects into UI (evidence: `README.md`)
- Runtime Event Log → Agent Run: informs next prompt (evidence: `README.md`)
- Runtime Event Log → Session Manager: supports recovery (evidence: `README.md`)
- Plugin Runtime → Plugin Agents: provides service (evidence: `packages/runtime/src/plugin-agent-service.ts`)
- Plugin Runtime → Plugin LLM: provides service (evidence: `packages/runtime/src/plugin-llm-service.ts`)
- Plugin Runtime → Plugin Queries: provides service (evidence: `packages/runtime/src/plugin-session-query-service.ts`)
- Plugin Agents → Plugin LLM: supplies invocation (evidence: `packages/runtime/src/plugin-llm-service.ts`)
- Plugin Agents → Plugin Queries: supplies caller (evidence: `packages/runtime/src/plugin-session-query-service.ts`)
- Agent Run → MCP Integration: uses integration
- Agent Run → Computer Use: uses integration
- Local State → Long-Term Memory: opens store (evidence: `packages/storage/src/storage-writer-composition.ts`)
- Experiment → Cells: defines (evidence: `README.md`)
- Cells → Attempts: runs (evidence: `README.md`)
- Attempts → Results: produces (evidence: `README.md`)
- Attempts → Runtime Host: executes subjects (evidence: `README.md`)
