# cogitave/namzu architecture

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

- Interactive diagram: https://gitdiagram.com/cogitave/namzu
- Repository: https://github.com/cogitave/namzu

## Overview

Namzu is an agent kernel SDK with a terminal coding-agent application built on the same runtime. Its principal workflow accepts an agent configuration and prompt, applies identity and budgets, calls a provider, schedules and executes tools under permissions, and returns a result while recording session state. The SDK also supports durable sessions, checkpoints, compaction, delegation, directory-based agents, and host-supplied sandboxing. The CLI adds interactive coding workflows and integrations. Several runtime links are documented in the README; unsampled subsystems are represented at their source-directory level.

Main entry points: [`packages/sdk/src`](https://github.com/cogitave/namzu/tree/main/packages/sdk/src) (Agent runtime), [`packages/cli/src/tui/App.tsx`](https://github.com/cogitave/namzu/blob/main/packages/cli/src/tui/App.tsx) (Interactive TUI), [`packages/sdk/src/runtime/query/session-storage.ts`](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/runtime/query/session-storage.ts) (Session storage), [`packages/sdk/src/toolsets/manager.ts`](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/toolsets/manager.ts) (Tool scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Agent kernel"]
  node_agent_config["Agent configuration<br/>[base.ts]"]
  node_agent_runtime["Agent runtime"]
  node_turn_budget["Turn budgets<br/>[ledger.ts]"]
  node_compaction["Context compaction<br/>[manager.ts]"]
  node_delegation["Agent delegation<br/>[task.ts]"]
  node_agent_folders["Directory agents"]
end

subgraph group_state["Identity and durability"]
  node_session_identity["Session identity<br/>[index.ts]"]
  node_session_storage["Session storage<br/>[session-storage.ts]"]
  node_session_log[("Hash-chained log<br/>[core.ts]")]
  node_checkpoints[("Turn checkpoints")]
end

subgraph group_execution["Tools and confinement"]
  node_tool_manager["Tool scheduler<br/>[manager.ts]"]
  node_permissions["Permission gate"]
  node_sandbox["Sandbox backends"]
end

subgraph group_providers["Model drivers"]
  node_provider_registry["Provider registry<br/>[registry.ts]"]
  node_provider_drivers["Model drivers"]
  node_zen_driver["Zen driver<br/>[client.ts]"]
end

subgraph group_cli["Terminal application"]
  node_cli_tui["Interactive TUI<br/>[App.tsx]"]
  node_cli_sessions[("CLI sessions<br/>[store.ts]")]
  node_cli_resident["Resident agents"]
  node_cli_scheduling["Job scheduling"]
  node_browser["Browser control"]
end

node_developer(("SDK host"))
node_terminal_user(("Terminal user"))

node_developer -->|"configures"| node_agent_config
node_agent_config -->|"runs turn"| node_agent_runtime
node_agent_runtime -->|"creates identity"| node_session_identity
node_agent_runtime -->|"applies budget"| node_turn_budget
node_agent_runtime -.->|"uses provider"| node_provider_registry
node_agent_runtime -->|"schedules tools"| node_tool_manager
node_tool_manager -->|"checks access"| node_permissions
node_tool_manager -.->|"confines execution"| node_sandbox
node_agent_runtime -->|"resolves storage"| node_session_storage
node_session_storage -->|"opens log"| node_session_log
node_session_storage -->|"opens stores"| node_checkpoints
node_agent_runtime -->|"records turn"| node_session_log
node_agent_runtime -->|"writes checkpoints"| node_checkpoints
node_agent_runtime -.->|"compacts context"| node_compaction
node_agent_runtime -->|"delegates work"| node_delegation
node_delegation -->|"inherits storage"| node_session_storage
node_agent_folders -->|"derives options"| node_agent_runtime
node_provider_registry -.->|"selects driver"| node_provider_drivers
node_provider_drivers -.->|"includes"| node_zen_driver
node_terminal_user -->|"starts session"| node_cli_tui
node_cli_tui -->|"runs agent"| node_agent_runtime
node_cli_tui -->|"discovers providers"| node_provider_registry
node_cli_tui -->|"opens sessions"| node_cli_sessions
node_cli_tui -.->|"uses resident agents"| node_cli_resident
node_cli_tui -->|"creates schedule integration"| node_cli_scheduling
node_cli_tui -.->|"controls browser"| node_browser

click node_agent_config "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/agent/base.ts"
click node_agent_runtime "https://github.com/cogitave/namzu/tree/main/packages/sdk/src"
click node_turn_budget "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/store/budget/ledger.ts"
click node_compaction "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/compaction/manager.ts"
click node_delegation "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/agent/task.ts"
click node_agent_folders "https://github.com/cogitave/namzu/tree/main/packages/sdk/src/agents"
click node_session_identity "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/ids/index.ts"
click node_session_storage "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/runtime/query/session-storage.ts"
click node_session_log "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/store/session-log/core.ts"
click node_checkpoints "https://github.com/cogitave/namzu/tree/main/packages/sdk/src/store/checkpoint"
click node_tool_manager "https://github.com/cogitave/namzu/blob/main/packages/sdk/src/toolsets/manager.ts"
click node_permissions "https://github.com/cogitave/namzu/tree/main/packages/sdk/src/types/permission"
click node_sandbox "https://github.com/cogitave/namzu/tree/main/packages/sandbox/src"
click node_provider_registry "https://github.com/cogitave/namzu/blob/main/packages/cli/src/integrations/providers/registry.ts"
click node_provider_drivers "https://github.com/cogitave/namzu/tree/main/packages/providers"
click node_zen_driver "https://github.com/cogitave/namzu/blob/main/packages/providers/zen/src/client.ts"
click node_cli_tui "https://github.com/cogitave/namzu/blob/main/packages/cli/src/tui/App.tsx"
click node_cli_sessions "https://github.com/cogitave/namzu/blob/main/packages/cli/src/integrations/sessions/store.ts"
click node_cli_resident "https://github.com/cogitave/namzu/tree/main/packages/cli/src/integrations/resident"
click node_cli_scheduling "https://github.com/cogitave/namzu/tree/main/packages/cli/src/schedule"
click node_browser "https://github.com/cogitave/namzu/tree/main/packages/browser/src"

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_config,node_agent_runtime,node_turn_budget,node_compaction,node_delegation,node_agent_folders,node_terminal_user toneBlue
class node_session_identity,node_session_storage,node_session_log,node_checkpoints toneAmber
class node_tool_manager,node_permissions,node_sandbox toneMint
class node_provider_registry,node_provider_drivers,node_zen_driver toneRose
class node_cli_tui,node_cli_sessions,node_cli_resident,node_cli_scheduling,node_browser,node_developer toneIndigo
```

## Components

### Agent kernel

- [Agent configuration](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/agent/base.ts): `packages/sdk/src/types/agent/base.ts`
- [Agent runtime](https://github.com/cogitave/namzu/tree/main/packages/sdk/src): `packages/sdk/src`
- [Turn budgets](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/store/budget/ledger.ts): `packages/sdk/src/store/budget/ledger.ts`
- [Context compaction](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/compaction/manager.ts): `packages/sdk/src/compaction/manager.ts`
- [Agent delegation](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/agent/task.ts): `packages/sdk/src/types/agent/task.ts`
- [Directory agents](https://github.com/cogitave/namzu/tree/main/packages/sdk/src/agents): `packages/sdk/src/agents`

### Identity and durability

- [Session identity](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/types/ids/index.ts): `packages/sdk/src/types/ids/index.ts`
- [Session storage](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/runtime/query/session-storage.ts): `packages/sdk/src/runtime/query/session-storage.ts`
- [Hash-chained log](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/store/session-log/core.ts): `packages/sdk/src/store/session-log/core.ts`
- [Turn checkpoints](https://github.com/cogitave/namzu/tree/main/packages/sdk/src/store/checkpoint): `packages/sdk/src/store/checkpoint`

### Tools and confinement

- [Tool scheduler](https://github.com/cogitave/namzu/blob/main/packages/sdk/src/toolsets/manager.ts): `packages/sdk/src/toolsets/manager.ts`
- [Permission gate](https://github.com/cogitave/namzu/tree/main/packages/sdk/src/types/permission): `packages/sdk/src/types/permission`
- [Sandbox backends](https://github.com/cogitave/namzu/tree/main/packages/sandbox/src): `packages/sandbox/src`

### Model drivers

- [Provider registry](https://github.com/cogitave/namzu/blob/main/packages/cli/src/integrations/providers/registry.ts): `packages/cli/src/integrations/providers/registry.ts`
- [Model drivers](https://github.com/cogitave/namzu/tree/main/packages/providers): `packages/providers`
- [Zen driver](https://github.com/cogitave/namzu/blob/main/packages/providers/zen/src/client.ts): `packages/providers/zen/src/client.ts`

### Terminal application

- [Interactive TUI](https://github.com/cogitave/namzu/blob/main/packages/cli/src/tui/App.tsx): `packages/cli/src/tui/App.tsx`
- [CLI sessions](https://github.com/cogitave/namzu/blob/main/packages/cli/src/integrations/sessions/store.ts): `packages/cli/src/integrations/sessions/store.ts`
- [Resident agents](https://github.com/cogitave/namzu/tree/main/packages/cli/src/integrations/resident): `packages/cli/src/integrations/resident`
- [Job scheduling](https://github.com/cogitave/namzu/tree/main/packages/cli/src/schedule): `packages/cli/src/schedule`
- [Browser control](https://github.com/cogitave/namzu/tree/main/packages/browser/src): `packages/browser/src`

### Other components

- **SDK host**
- **Terminal user**

## Connections

- SDK host → Agent configuration: configures (evidence: `README.md`)
- Agent configuration → Agent runtime: runs turn (evidence: `README.md`)
- Agent runtime → Session identity: creates identity (evidence: `README.md`)
- Agent runtime → Turn budgets: applies budget (evidence: `README.md`)
- Agent runtime → Provider registry: uses provider
- Agent runtime → Tool scheduler: schedules tools (evidence: `README.md`)
- Tool scheduler → Permission gate: checks access (evidence: `README.md`)
- Tool scheduler → Sandbox backends: confines execution
- Agent runtime → Session storage: resolves storage (evidence: `packages/sdk/src/types/agent/base.ts`)
- Session storage → Hash-chained log: opens log (evidence: `packages/sdk/src/runtime/query/session-storage.ts`)
- Session storage → Turn checkpoints: opens stores (evidence: `packages/sdk/src/runtime/query/session-storage.ts`)
- Agent runtime → Hash-chained log: records turn (evidence: `README.md`)
- Agent runtime → Turn checkpoints: writes checkpoints (evidence: `README.md`)
- Agent runtime → Context compaction: compacts context (evidence: `packages/sdk/src/compaction/manager.ts`)
- Agent runtime → Agent delegation: delegates work (evidence: `README.md`)
- Agent delegation → Session storage: inherits storage (evidence: `packages/sdk/src/agents/storage.ts`)
- Directory agents → Agent runtime: derives options (evidence: `README.md`)
- Provider registry → Model drivers: selects driver
- Model drivers → Zen driver: includes (evidence: `packages/providers/zen/src/client.ts`)
- Terminal user → Interactive TUI: starts session (evidence: `README.md`)
- Interactive TUI → Agent runtime: runs agent (evidence: `README.md`)
- Interactive TUI → Provider registry: discovers providers (evidence: `packages/cli/src/tui/App.tsx`)
- Interactive TUI → CLI sessions: opens sessions (evidence: `packages/cli/src/tui/App.tsx`)
- Interactive TUI → Resident agents: uses resident agents
- Interactive TUI → Job scheduling: creates schedule integration (evidence: `packages/cli/src/tui/App.tsx`)
- Interactive TUI → Browser control: controls browser
