# shareai-lab/kode-agent-sdk architecture

> Architecture diagram of the GitHub repository shareai-lab/kode-agent-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shareai-lab/kode-agent-sdk
- Repository: https://github.com/shareai-lab/kode-agent-sdk

## Overview

KODE SDK is a resumable, event-driven AI-agent framework. A caller sends work to an Agent, which interacts with a model provider, dispatches tools under permission controls, and emits events; context and checkpoint data can be persisted for recovery. AgentPool, Room, and Scheduler support multi-agent coordination. The README documents provider, persistence, sandbox, MCP, and Skills capabilities; some links to those subsystems are documented rather than verified in sampled implementation. The supplied excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/core/agent.ts`](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent.ts) (Agent), [`src/infra/provider.ts`](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/provider.ts) (Model provider API), [`src/infra/store.ts`](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/store.ts) (Store interface), [`src/core/agent/tool-runner.ts`](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent/tool-runner.ts) (Tool runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_agent["Agent<br/>[agent.ts]"]
  node_permissions["Permission manager"]
  node_events["Event bus<br/>[events.ts]"]
end

subgraph group_tools["Tool execution"]
  node_toolrunner["Tool runner<br/>[tool-runner.ts]"]
  node_registry["Tool registry<br/>[registry.ts]"]
  node_builtin["Built-in tools<br/>[builtin.ts]"]
  node_mcp["MCP tools<br/>[mcp.ts]"]
  node_sandbox["Sandbox interface<br/>[sandbox.ts]"]
  node_e2b["E2B sandbox<br/>[e2b-sandbox.ts]"]
  node_opensandbox["OpenSandbox"]
end

subgraph group_providers["Model providers"]
  node_provider["Model provider API<br/>[provider.ts]"]
  node_anthropic["Anthropic provider<br/>[anthropic.ts]"]
  node_openai["OpenAI provider<br/>[openai.ts]"]
  node_gemini["Gemini provider<br/>[gemini.ts]"]
end

subgraph group_state["Persistence and context"]
  node_context["Context manager<br/>[context-manager.ts]"]
  node_store["Store interface<br/>[store.ts]"]
  node_jsonstore[("JSON store<br/>[json-store.ts]")]
  node_sqlite[("SQLite store<br/>[sqlite-store.ts]")]
  node_postgres[("PostgreSQL store<br/>[postgres-store.ts]")]
end

subgraph group_ecosystem["Collaboration and extensions"]
  node_pool["Agent pool<br/>[pool.ts]"]
  node_room["Agent room<br/>[room.ts]"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
  node_skills["Skills system<br/>[index.ts]"]
end

node_caller(("Application caller"))
node_modelservice(("Model service"))
node_sandboxservice(("Remote sandbox service"))

node_caller -->|"sends work"| node_agent
node_agent -->|"requests completion"| node_provider
node_provider -->|"selects provider"| node_anthropic
node_provider -->|"selects provider"| node_openai
node_provider -->|"selects provider"| node_gemini
node_anthropic -->|"calls model"| node_modelservice
node_openai -->|"calls model"| node_modelservice
node_gemini -->|"calls model"| node_modelservice
node_agent -->|"checks access"| node_permissions
node_agent -->|"dispatches tools"| node_toolrunner
node_toolrunner -->|"resolves tools"| node_registry
node_registry -->|"provides tools"| node_builtin
node_registry -.->|"provides integrations"| node_mcp
node_toolrunner -->|"executes in"| node_sandbox
node_sandbox -.->|"selects backend"| node_e2b
node_sandbox -.->|"selects backend"| node_opensandbox
node_e2b -.->|"runs remotely"| node_sandboxservice
node_opensandbox -.->|"runs remotely"| node_sandboxservice
node_agent -->|"publishes events"| node_events
node_agent -->|"manages context"| node_context
node_context -->|"saves history"| node_store
node_store -->|"uses backend"| node_jsonstore
node_store -->|"uses backend"| node_sqlite
node_store -->|"uses backend"| node_postgres
node_pool -->|"manages agents"| node_agent
node_room -->|"coordinates agents"| node_agent
node_scheduler -->|"schedules work"| node_agent

click node_agent "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent.ts"
click node_permissions "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent/permission-manager.ts"
click node_events "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/events.ts"
click node_context "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/context-manager.ts"
click node_provider "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/provider.ts"
click node_anthropic "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/anthropic.ts"
click node_openai "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/openai.ts"
click node_gemini "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/gemini.ts"
click node_toolrunner "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent/tool-runner.ts"
click node_registry "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/registry.ts"
click node_builtin "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/builtin.ts"
click node_mcp "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/mcp.ts"
click node_sandbox "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/sandbox.ts"
click node_e2b "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/e2b/e2b-sandbox.ts"
click node_opensandbox "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/opensandbox/opensandbox-sandbox.ts"
click node_store "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/store.ts"
click node_jsonstore "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/store/json-store.ts"
click node_sqlite "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/db/sqlite/sqlite-store.ts"
click node_postgres "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/db/postgres/postgres-store.ts"
click node_pool "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/pool.ts"
click node_room "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/room.ts"
click node_scheduler "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/scheduler.ts"
click node_skills "https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/skills/index.ts"

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_agent,node_permissions,node_events toneBlue
class node_toolrunner,node_registry,node_builtin,node_mcp,node_sandbox,node_e2b,node_opensandbox toneAmber
class node_provider,node_anthropic,node_openai,node_gemini toneMint
class node_context,node_store,node_jsonstore,node_sqlite,node_postgres toneRose
class node_pool,node_room,node_scheduler,node_skills,node_caller,node_modelservice,node_sandboxservice toneIndigo
```

## Components

### Agent runtime

- [Agent](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent.ts): `src/core/agent.ts`
- [Permission manager](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent/permission-manager.ts): `src/core/agent/permission-manager.ts`
- [Event bus](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/events.ts): `src/core/events.ts`

### Tool execution

- [Tool runner](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/agent/tool-runner.ts): `src/core/agent/tool-runner.ts`
- [Tool registry](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/registry.ts): `src/tools/registry.ts`
- [Built-in tools](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/builtin.ts): `src/tools/builtin.ts`
- [MCP tools](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/tools/mcp.ts): `src/tools/mcp.ts`
- [Sandbox interface](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/sandbox.ts): `src/infra/sandbox.ts`
- [E2B sandbox](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/e2b/e2b-sandbox.ts): `src/infra/e2b/e2b-sandbox.ts`
- [OpenSandbox](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/opensandbox/opensandbox-sandbox.ts): `src/infra/opensandbox/opensandbox-sandbox.ts`

### Model providers

- [Model provider API](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/provider.ts): `src/infra/provider.ts`
- [Anthropic provider](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/anthropic.ts): `src/infra/providers/anthropic.ts`
- [OpenAI provider](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/openai.ts): `src/infra/providers/openai.ts`
- [Gemini provider](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/providers/gemini.ts): `src/infra/providers/gemini.ts`

### Persistence and context

- [Context manager](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/context-manager.ts): `src/core/context-manager.ts`
- [Store interface](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/store.ts): `src/infra/store.ts`
- [JSON store](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/store/json-store.ts): `src/infra/store/json-store.ts`
- [SQLite store](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/db/sqlite/sqlite-store.ts): `src/infra/db/sqlite/sqlite-store.ts`
- [PostgreSQL store](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/infra/db/postgres/postgres-store.ts): `src/infra/db/postgres/postgres-store.ts`

### Collaboration and extensions

- [Agent pool](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/pool.ts): `src/core/pool.ts`
- [Agent room](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/room.ts): `src/core/room.ts`
- [Scheduler](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/scheduler.ts): `src/core/scheduler.ts`
- [Skills system](https://github.com/shareai-lab/kode-agent-sdk/blob/main/src/core/skills/index.ts): `src/core/skills/index.ts`

### Other components

- **Application caller**
- **Model service**
- **Remote sandbox service**

## Connections

- Application caller → Agent: sends work
- Agent → Model provider API: requests completion
- Model provider API → Anthropic provider: selects provider
- Model provider API → OpenAI provider: selects provider
- Model provider API → Gemini provider: selects provider
- Anthropic provider → Model service: calls model
- OpenAI provider → Model service: calls model
- Gemini provider → Model service: calls model
- Agent → Permission manager: checks access
- Agent → Tool runner: dispatches tools
- Tool runner → Tool registry: resolves tools
- Tool registry → Built-in tools: provides tools
- Tool registry → MCP tools: provides integrations
- Tool runner → Sandbox interface: executes in
- Sandbox interface → E2B sandbox: selects backend
- Sandbox interface → OpenSandbox: selects backend
- E2B sandbox → Remote sandbox service: runs remotely
- OpenSandbox → Remote sandbox service: runs remotely
- Agent → Event bus: publishes events
- Agent → Context manager: manages context
- Context manager → Store interface: saves history
- Store interface → JSON store: uses backend
- Store interface → SQLite store: uses backend
- Store interface → PostgreSQL store: uses backend
- Agent pool → Agent: manages agents
- Agent room → Agent: coordinates agents
- Scheduler → Agent: schedules work