# 0xkarl-dev/claw-codes architecture

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

- Interactive diagram: https://gitdiagram.com/0xkarl-dev/claw-codes
- Repository: https://github.com/0xkarl-dev/claw-codes

## Overview

1. **Current runtime and shape of the repo**
   - The checked-in implementation is a **TypeScript/Node.js application** with a large **Ink + React** terminal UI layer.
   - The README describes a future Rust/Python rewrite, but the actual architecture in this repo is still the existing **CLI-first agent system**.

2. **Top-level entry and app bootstrap**
   - `src/entrypoints/*`, `src/main.tsx`, `src/setup.ts`, and `src/ink.ts` form the startup path.
   - Bootstrapping wires together config, session state, keybindings, tool registry, services, and the terminal renderer before the interactive app is shown.

3. **Terminal UI as the presentation layer**
   - `src/ink/*` is a custom terminal rendering stack, not just a thin wrapper over a library.
   - `src/components/*` contains the interactive UI: prompt input, message feed, dialogs, settings screens, permission prompts, task views, onboarding, and status indicators.
   - This layer only renders state and emits user intents; it does not own execution logic.

4. **Global state and interaction context**
   - `src/state/*`, `src/context/*`, and many `src/hooks/*` files form the application’s reactive state and orchestration layer.
   - These modules coordinate prompt submission, message queues, modal state, notifications, task selection, session history, and user preferences.
   - The app relies heavily on hooks and context to bridge UI events to execution services.

5. **Agent/session execution pipeline**
   - `src/services/tools/*`, `src/tools/*`, `src/tasks/*`, `src/task.ts`, `src/Task.ts`, and `src/QueryEngine.ts` define the execution model for work performed by the assistant.
   - The flow is: user input or background trigger → task creation/scheduling → model/tool invocation → streamed tool/output messages → UI rendering and persistence.
   - There are explicit task types for local shell work, remote agents, in-process teammates, dreams/background work, and shell sessions.

6. **Tooling subsystem**
   - `src/tools/*` is the main tool catalog: bash/powershell, file read/write/edit, grep/glob, web fetch/search, LSP, MCP, agent spawning, scheduling, task management, notebook edits, and more.
   - Each tool has its own UI, prompt schema, validation, and result message types.
   - `src/constants/tools.ts` and related schema/helpers define what the model can call and how tool calls are rendered back to the user.

7. **Permissions and safety boundary**
   - `src/components/permissions/*`, `src/hooks/toolPermission/*`, and `src/utils/permissions/*` implement the approval layer between model intent and side effects.
   - This boundary governs shell execution, file edits, filesystem access, web fetches, computer use, and other potentially unsafe operations.
   - The architecture clearly separates “requesting permission” from “executing the action.”

8. **Remote control, bridge, and session transport**
   - `src/bridge/*`, `src/remote/*`, `src/server/*`, `src/upstreamproxy/*`, and related CLI transports in `src/cli/transports/*` form the remote/session connectivity layer.
   - These modules handle live session bridging, remote session management, WebSocket/SSE transport, direct-connect sessions, REPL bridging, and message relaying.
   - This is the boundary for non-local execution, mobile/desktop handoff, and session persistence across clients.

9. **Plugins, MCP, skills, and extensibility**
   - `src/plugins/*`, `src/services/plugins/*`, `src/services/mcp/*`, `src/components/mcp/*`, `src/skills/*`, and `src/utils/plugins/*` provide the extensibility system.
   - The architecture supports loading built-in and external plugins, MCP servers/resources, marketplace flows, skill bundles, and plugin-specific commands/hooks.
   - Plugins can contribute commands, tools, output styles, hooks, and model-facing capabilities.

10. **Memory, session history, and context management**
    - `src/history.ts`, `src/assistant/sessionHistory.ts`, `src/memdir/*`, `src/services/SessionMemory/*`, `src/services/extractMemories/*`, and `src/utils/context*` manage long-lived context.
    - The system scans files, stores memories, summarizes sessions, and computes relevant context for the model.
    - This is a key data-flow boundary: raw chat/tool activity is transformed into compacted, searchable, reusable context.

11. **Model/API/auth/integration services**
    - `src/services/api/*`, `src/services/oauth/*`, `src/services/analytics/*`, `src/services/claudeAiLimits.ts`, `src/utils/model/*`, and `src/utils/auth*` handle external service integration.
    - These modules manage API calls, auth flows, limits/rate handling, usage reporting, telemetry, and model/provider selection.
    - They sit below the app logic and above network services, keeping provider concerns separate from UI and tool execution.

12. **Background automation and orchestration**
    - `src/services/compact/*`, `src/services/autoDream/*`, `src/services/tips/*`, `src/services/voice*`, `src/services/lsp/*`, `src/services/notifier.ts`, and many `src/hooks/notifs/*` support background features.
    - These services run compaction, memory extraction, notifications, LSP diagnostics, voice/STT, and scheduled/background tasks.
    - They feed events back into the main state/store and UI rather than directly manipulating presentation.

13. **Important diagram boundary to preserve**
    - A useful architecture diagram should show three major layers:
      - **Interactive terminal UI** (Ink/React components)
      - **Core orchestration and execution** (state, hooks, tasks, tools, permissions, services)
      - **Integration/transport layer** (API/auth, plugins/MCP, remote bridge, analytics, persistence)
    - The critical flows are user input → command/task resolution → permission gate → tool/model execution → streamed output → session/history/memory updates → UI refresh.

14. **Practical takeaway**
    - This repo is best understood as a **modular agent runtime and terminal control plane** rather than a simple chat client.
    - Its architecture is centered on **message-driven task execution**, **tool isolation**, **permission mediation**, and **extensibility via plugins/skills/remote sessions**.

Main entry points: [`src/components/App.tsx`](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/App.tsx) (App UI), [`src/tasks.ts`](https://github.com/0xkarl-dev/claw-codes/blob/main/src/tasks.ts) (Task Engine), [`src/state/AppStateStore.ts`](https://github.com/0xkarl-dev/claw-codes/blob/main/src/state/AppStateStore.ts) (App State), [`src/hooks/useQueueProcessor.ts`](https://github.com/0xkarl-dev/claw-codes/blob/main/src/hooks/useQueueProcessor.ts) (Orchestration Hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ui["Terminal UI"]
  node_n_ui["App UI<br/>ink/react UI<br/>[App.tsx]"]
  node_n_prompt["Prompt Flow<br/>input orchestration<br/>[PromptInput.tsx]"]
  node_n_messages["Message Feed<br/>conversation UI<br/>[Messages.tsx]"]
  node_n_perms["Permission Gate<br/>safety boundary"]
  node_n_tasks_ui["Task Views<br/>task UI"]
end

subgraph group_grp_core["Core Orchestration"]
  node_n_state[("App State<br/>reactive state<br/>[AppStateStore.ts]")]
  node_n_hooks["Orchestration Hooks<br/>coordination hooks"]
  node_n_tasks["Task Engine<br/>execution model<br/>[tasks.ts]"]
  node_n_tools["Tool Runtime<br/>tooling subsystem<br/>[tools.ts]"]
  node_n_toolsvc["Tool Services<br/>tool orchestration"]
  node_n_permsvc["Permission Logic<br/>safety policy<br/>[permissions.ts]"]
end

subgraph group_grp_integrations["Integrations"]
  node_n_modelsvc["Model/API<br/>provider integration<br/>[client.ts]"]
  node_n_plugins["Plugins & MCP<br/>extensibility"]
  node_n_remote["Remote Bridge<br/>transport layer<br/>[bridgeMain.ts]"]
  node_n_memory["Memory & History<br/>context store<br/>[history.ts]"]
  node_n_bg["Background Services<br/>automation services<br/>[compact.ts]"]
end

subgraph group_grp_runtime["Runtime Infra"]
  node_n_entry["Bootstrap<br/>[cli.tsx]"]
  node_n_main["Main App<br/>app bootstrap<br/>[main.tsx]"]
  node_n_ink["Ink Engine<br/>terminal runtime<br/>[ink.ts]"]
end

node_n_entry -->|"starts"| node_n_main
node_n_main -->|"boots"| node_n_ink
node_n_ink -->|"renders"| node_n_ui
node_n_main -->|"initializes"| node_n_state
node_n_ui -->|"captures input"| node_n_prompt
node_n_ui -->|"shows output"| node_n_messages
node_n_ui -->|"shows tasks"| node_n_tasks_ui
node_n_ui -->|"requests approval"| node_n_perms
node_n_prompt -->|"submits intent"| node_n_hooks
node_n_hooks -->|"updates"| node_n_state
node_n_hooks -->|"creates work"| node_n_tasks
node_n_tasks -->|"runs via"| node_n_toolsvc
node_n_toolsvc -->|"dispatches"| node_n_tools
node_n_tools -->|"checks"| node_n_permsvc
node_n_permsvc -->|"surfaces"| node_n_perms
node_n_toolsvc -->|"calls model"| node_n_modelsvc
node_n_modelsvc -->|"writes context"| node_n_memory
node_n_tasks -->|"records history"| node_n_memory
node_n_plugins -->|"extends"| node_n_tools
node_n_plugins -->|"integrates"| node_n_modelsvc
node_n_remote -->|"bridges"| node_n_tasks
node_n_bg -->|"compacts"| node_n_memory
node_n_bg -->|"notifies"| node_n_state
node_n_state -->|"refreshes"| node_n_ui

click node_n_entry "https://github.com/0xkarl-dev/claw-codes/blob/main/src/entrypoints/cli.tsx"
click node_n_main "https://github.com/0xkarl-dev/claw-codes/blob/main/src/main.tsx"
click node_n_ink "https://github.com/0xkarl-dev/claw-codes/blob/main/src/ink.ts"
click node_n_ui "https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/App.tsx"
click node_n_prompt "https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/PromptInput/PromptInput.tsx"
click node_n_messages "https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/Messages.tsx"
click node_n_perms "https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/permissions/PermissionDialog.tsx"
click node_n_tasks_ui "https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/tasks/BackgroundTasksDialog.tsx"
click node_n_state "https://github.com/0xkarl-dev/claw-codes/blob/main/src/state/AppStateStore.ts"
click node_n_hooks "https://github.com/0xkarl-dev/claw-codes/blob/main/src/hooks/useQueueProcessor.ts"
click node_n_tasks "https://github.com/0xkarl-dev/claw-codes/blob/main/src/tasks.ts"
click node_n_tools "https://github.com/0xkarl-dev/claw-codes/blob/main/src/tools.ts"
click node_n_toolsvc "https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/tools/toolOrchestration.ts"
click node_n_permsvc "https://github.com/0xkarl-dev/claw-codes/blob/main/src/utils/permissions/permissions.ts"
click node_n_modelsvc "https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/api/client.ts"
click node_n_plugins "https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/plugins/pluginOperations.ts"
click node_n_remote "https://github.com/0xkarl-dev/claw-codes/blob/main/src/bridge/bridgeMain.ts"
click node_n_memory "https://github.com/0xkarl-dev/claw-codes/blob/main/src/history.ts"
click node_n_bg "https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/compact/compact.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_n_ui,node_n_prompt,node_n_messages,node_n_perms,node_n_tasks_ui toneBlue
class node_n_state,node_n_hooks,node_n_tasks,node_n_tools,node_n_toolsvc,node_n_permsvc toneAmber
class node_n_modelsvc,node_n_plugins,node_n_remote,node_n_memory,node_n_bg toneMint
class node_n_entry,node_n_main,node_n_ink toneRose
```

## Components

### Terminal UI

Ink/React presentation and user interaction surfaces

- [App UI](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/App.tsx): ink/react UI · Primary terminal screens and interactive components · `src/components/App.tsx`
- [Prompt Flow](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/PromptInput/PromptInput.tsx): input orchestration · Prompt entry, command queue, and user intent capture · `src/components/PromptInput/PromptInput.tsx`
- [Message Feed](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/Messages.tsx): conversation UI · Streaming conversation, tool results, and status messages · `src/components/Messages.tsx`
- [Permission Gate](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/permissions/PermissionDialog.tsx): safety boundary · Approval dialogs and permission request handling · `src/components/permissions/PermissionDialog.tsx`
- [Task Views](https://github.com/0xkarl-dev/claw-codes/blob/main/src/components/tasks/BackgroundTasksDialog.tsx): task UI · Task, shell, agent, and background activity displays · `src/components/tasks/BackgroundTasksDialog.tsx`

### Core Orchestration

State, hooks, tasks, permissions, and execution control

- [App State](https://github.com/0xkarl-dev/claw-codes/blob/main/src/state/AppStateStore.ts): reactive state · Global app state, store, and selectors · `src/state/AppStateStore.ts`
- [Orchestration Hooks](https://github.com/0xkarl-dev/claw-codes/blob/main/src/hooks/useQueueProcessor.ts): coordination hooks · Hooks bridging UI events to services and state · `src/hooks/useQueueProcessor.ts`
- [Task Engine](https://github.com/0xkarl-dev/claw-codes/blob/main/src/tasks.ts): execution model · Local, remote, teammate, and dream task lifecycles · `src/tasks.ts`
- [Tool Runtime](https://github.com/0xkarl-dev/claw-codes/blob/main/src/tools.ts): tooling subsystem · Tool catalog, schemas, UIs, and tool execution surface · `src/tools.ts`
- [Tool Services](https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/tools/toolOrchestration.ts): tool orchestration · Streaming execution and tool orchestration services · `src/services/tools/toolOrchestration.ts`
- [Permission Logic](https://github.com/0xkarl-dev/claw-codes/blob/main/src/utils/permissions/permissions.ts): safety policy · Permission rules, classifiers, and approval policy · `src/utils/permissions/permissions.ts`

### Integrations

External services, plugins, remote transport, and persistence

- [Model/API](https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/api/client.ts): provider integration · Model calls, auth, limits, and API clients · `src/services/api/client.ts`
- [Plugins & MCP](https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/plugins/pluginOperations.ts): extensibility · Plugins, skills, MCP servers, and marketplace loading · `src/services/plugins/pluginOperations.ts`
- [Remote Bridge](https://github.com/0xkarl-dev/claw-codes/blob/main/src/bridge/bridgeMain.ts): transport layer · Remote sessions, relays, direct connect, and session transport · `src/bridge/bridgeMain.ts`
- [Memory & History](https://github.com/0xkarl-dev/claw-codes/blob/main/src/history.ts): context store · Session history, memories, compaction, and context selection · `src/history.ts`
- [Background Services](https://github.com/0xkarl-dev/claw-codes/blob/main/src/services/compact/compact.ts): automation services · Compaction, dreams, tips, voice, notifications, and LSP support · `src/services/compact/compact.ts`

### Runtime Infra

Custom terminal runtime and low-level app bootstrap

- [Bootstrap](https://github.com/0xkarl-dev/claw-codes/blob/main/src/entrypoints/cli.tsx): entry/bootstrap · CLI entrypoints and startup wiring · `src/entrypoints/cli.tsx`
- [Main App](https://github.com/0xkarl-dev/claw-codes/blob/main/src/main.tsx): app bootstrap · Application startup and root composition · `src/main.tsx`
- [Ink Engine](https://github.com/0xkarl-dev/claw-codes/blob/main/src/ink.ts): terminal runtime · Custom terminal rendering, input, and layout system · `src/ink.ts`

## Connections

- Bootstrap → Main App: starts · CLI entry initializes the main application
- Main App → Ink Engine: boots · Main app mounts the terminal runtime
- Ink Engine → App UI: renders · Ink provides the rendering surface for the React UI
- Main App → App State: initializes · App bootstrap wires global state and store
- App UI → Prompt Flow: captures input · Prompt components collect user intents
- App UI → Message Feed: shows output · Conversation feed renders assistant and tool messages
- App UI → Task Views: shows tasks · Task panels render active work and progress
- App UI → Permission Gate: requests approval · UI presents permission prompts and safety dialogs
- Prompt Flow → Orchestration Hooks: submits intent · Prompt events flow into orchestration hooks
- Orchestration Hooks → App State: updates · Hooks coordinate and mutate shared app state
- Orchestration Hooks → Task Engine: creates work · User intent becomes scheduled task execution
- Task Engine → Tool Services: runs via · Tasks invoke the streaming tool execution pipeline
- Tool Services → Tool Runtime: dispatches · Orchestrator routes calls to specific tools
- Tool Runtime → Permission Logic: checks · Tool requests are evaluated against permission policy
- Permission Logic → Permission Gate: surfaces · Permission decisions are presented to the user
- Tool Services → Model/API: calls model · Tool and agent flows depend on model/API services
- Model/API → Memory & History: writes context · Model activity and results contribute to session memory
- Task Engine → Memory & History: records history · Task outcomes are persisted into history and memory
- Plugins & MCP → Tool Runtime: extends · Plugins and MCP can add tools and commands
- Plugins & MCP → Model/API: integrates · Extensibility can depend on provider and auth services
- Remote Bridge → Task Engine: bridges · Remote transport relays task/session activity across clients
- Background Services → Memory & History: compacts · Background services summarize and compact session context
- Background Services → App State: notifies · Automation feeds updates back into app state
- App State → App UI: refreshes · State changes drive terminal UI rerenders
