# prassamin/claw-code architecture

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

## Overview

1. This is a Bun-built TypeScript/React CLI, not a web app. The runtime entrypoint is `src/entrypoints/cli.tsx` / `src/main.tsx`, and the UI is rendered with a custom Ink terminal framework in `src/ink`. The build script bundles everything into a single portable ESM artifact, `dist/cli.mjs`.

2. The core product surface is an interactive agentic terminal session: user input comes through `src/components/PromptInput`, command processing in `src/utils/processUserInput`, and the main app shell in `src/components/App.tsx`. The app state lives in `src/state`, with contexts in `src/context` coordinating prompt, modal, notification, stats, and voice state.

3. The central execution loop is agent/task driven. High-level task objects are defined in `src/tasks`, while orchestration logic sits in `src/services/tools`, `src/services/toolUseSummary`, `src/services/compact`, and `src/utils/task`. Messages, tool calls, and task progress are all rendered as terminal UI components under `src/components/messages`, `src/components/tasks`, and `src/components/StatusLine`.

4. Tooling is a first-class subsystem. Each tool has its own module under `src/tools/*` plus a UI/prompt layer. The major capabilities include shell execution, file read/write/edit, search, LSP, MCP, web fetch/search, task management, agents/subagents, skills, notebooks, cron/scheduling, and remote triggers. Tool execution is coordinated by `src/services/tools/toolOrchestration.ts` and gated through permission hooks.

5. Permission and safety boundaries are explicit and deep. `src/hooks/toolPermission`, `src/components/permissions`, and `src/utils/permissions` define how bash/file/network/tool actions are approved or denied. There are separate policies for destructive shell commands, filesystem writes, sandboxed execution, plan mode, and auto-mode behavior, with dialog-driven user approvals in the TUI.

6. The repository supports multiple execution environments. Local shell and terminal features are handled in `src/utils/shell`, `src/utils/terminal`, and `src/tasks/LocalShellTask`. Remote and distributed execution are handled by `src/remote`, `src/server`, `src/bridge`, and `src/utils/remote*`-related code, including session bridges, WebSocket transports, and direct-connect session creation.

7. The `bridge` subsystem is a major architectural boundary. Files under `src/bridge` implement a remote-control/session bridge for REPL and remote session attachment, message transport, permission callbacks, session creation, wake/poll logic, and device trust. This layer sits between local UI state and remote or long-running session state.

8. Plugin and extension loading is another core boundary. `src/services/plugins`, `src/utils/plugins`, and `src/plugins` manage installation, validation, marketplace access, bundled plugins, auto-update, policy checks, and dynamic loading of commands, hooks, agents, output styles, and MCP integrations. Commands in `src/commands/plugin` expose the user-facing management flow.

9. Model/API integration is centralized under `src/services/api`, `src/services/oauth`, `src/services/analytics`, and `src/utils/model`. This layer handles Anthropic API calls, auth, usage/rate limits, telemetry, prompt/usage logging, and model selection/capability validation. It is the primary boundary to external cloud services.

10. Session state, history, and recovery are first-class concerns. `src/history.ts`, `src/utils/sessionStorage`, `src/utils/sessionRestore`, `src/commands/resume`, and `src/screens/ResumeConversation.tsx` support continuity across restarts. Memory and context subsystems in `src/memdir`, `src/services/SessionMemory`, `src/services/extractMemories`, and `src/services/compact` manage long-running conversations and context collapse.

11. Several “side channels” extend the assistant beyond plain chat. `src/services/mcp` and `src/components/mcp` handle Model Context Protocol servers and tool connections; `src/services/lsp` integrates language servers; `src/voice` and `src/services/voice*` support speech input/output; and `src/utils/computerUse` plus `src/utils/claudeInChrome` enable browser/computer-use style automation when available.

12. The command layer is broad but mostly a thin orchestration surface. `src/commands/*` maps slash-style and top-level commands to specific screens, wizards, or operational flows: onboarding, auth, config, sessions, plugins, agents, remote setup, review, resume, sandbox toggles, and diagnostics. These commands primarily assemble the lower-level services and UI components rather than implementing core execution logic themselves.

13. The overall data flow is: terminal input → command parsing/state update → permission and policy checks → tool/task execution → API/remote/sandbox side effects → message/event accumulation → Ink/React rendering back to the terminal. That loop is supported by caching, telemetry, and persistence utilities in `src/utils`, which are used across nearly every subsystem.

14. Architecturally, the repo is split into three stable layers: UI/rendering (`src/ink`, `src/components`, `src/screens`), orchestration/state (`src/state`, `src/hooks`, `src/services`, `src/tasks`, `src/bridge`), and adapters/integration (`src/tools`, `src/utils`, `src/plugins`, `src/remote`, `src/server`). This makes it suitable for a diagram that shows a terminal client core with multiple extension and execution backends around it.

Main entry points: [`src/services/tools/toolOrchestration.ts`](https://github.com/prassamin/claw-code/blob/main/src/services/tools/toolOrchestration.ts) (Tool orchestration), [`src/components/App.tsx`](https://github.com/prassamin/claw-code/blob/main/src/components/App.tsx) (App shell), [`src/tasks`](https://github.com/prassamin/claw-code/tree/main/src/tasks) (Task engine), [`src/services/plugins`](https://github.com/prassamin/claw-code/tree/main/src/services/plugins) (Plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI / TUI"]
  node_node_ink["Ink core<br/>terminal ui framework"]
  node_node_app["App shell<br/>root ui<br/>[App.tsx]"]
  node_node_prompt["Prompt flow<br/>input pipeline"]
  node_node_messages["Message views<br/>terminal views"]
  node_node_permissions_ui["Permission UI<br/>approval dialogs"]
  node_node_tasks_ui["Task views<br/>task panels"]
end

subgraph group_group_core["Core Orchestration"]
  node_node_state[("App state<br/>state store")]
  node_node_commands["Commands<br/>command layer"]
  node_node_input["Input processing<br/>command parser"]
  node_node_tools["Tool orchestration<br/>execution hub"]
  node_node_tasks["Task engine<br/>agent/task loop"]
  node_node_permissions["Safety policy<br/>policy engine"]
  node_node_session["Session memory<br/>continuity<br/>[history.ts]"]
end

subgraph group_group_adapters["Adapters / Integrations"]
  node_node_api["Cloud API<br/>external api"]
  node_node_plugins["Plugins<br/>extension system"]
  node_node_remote["Remote control<br/>distributed runtime"]
  node_node_bridge["Bridge layer<br/>session bridge"]
  node_node_tools_impl["Tool modules<br/>tool implementations"]
  node_node_builtins["Built-in skills<br/>prompt assets"]
end

subgraph group_group_runtime["Runtime / Build"]
  node_node_entry["CLI entry<br/>entrypoint<br/>[cli.tsx]"]
  node_node_main["Main shell<br/>bootstrap<br/>[main.tsx]"]
end

node_node_entry -->|"starts"| node_node_main
node_node_main -->|"renders in"| node_node_ink
node_node_ink -->|"hosts"| node_node_app
node_node_app -->|"accepts input"| node_node_prompt
node_node_app -->|"shows conversation"| node_node_messages
node_node_app -->|"shows tasks"| node_node_tasks_ui
node_node_app -->|"asks approval"| node_node_permissions_ui
node_node_prompt -->|"parses"| node_node_input
node_node_input -->|"dispatches"| node_node_commands
node_node_input -->|"starts tools"| node_node_tools
node_node_commands -->|"updates"| node_node_state
node_node_state -->|"tracks"| node_node_tasks
node_node_tasks -->|"invokes"| node_node_tools
node_node_tools -->|"gated by"| node_node_permissions
node_node_permissions -->|"prompts"| node_node_permissions_ui
node_node_tasks -->|"persists"| node_node_session
node_node_session -->|"syncs"| node_node_api
node_node_tools -->|"calls cloud"| node_node_api
node_node_tools -->|"uses"| node_node_tools_impl
node_node_tools_impl -.->|"extends"| node_node_builtins
node_node_remote -->|"connects via"| node_node_bridge
node_node_bridge -->|"feeds state"| node_node_state
node_node_remote -->|"runs tasks"| node_node_tasks
node_node_plugins -->|"adds tools"| node_node_tools
node_node_plugins -->|"adds commands"| node_node_commands
node_node_plugins -.->|"marketplace"| node_node_api

click node_node_entry "https://github.com/prassamin/claw-code/blob/main/src/entrypoints/cli.tsx"
click node_node_main "https://github.com/prassamin/claw-code/blob/main/src/main.tsx"
click node_node_ink "https://github.com/prassamin/claw-code/tree/main/src/ink"
click node_node_app "https://github.com/prassamin/claw-code/blob/main/src/components/App.tsx"
click node_node_prompt "https://github.com/prassamin/claw-code/tree/main/src/components/PromptInput"
click node_node_messages "https://github.com/prassamin/claw-code/tree/main/src/components/messages"
click node_node_permissions_ui "https://github.com/prassamin/claw-code/tree/main/src/components/permissions"
click node_node_tasks_ui "https://github.com/prassamin/claw-code/tree/main/src/components/tasks"
click node_node_state "https://github.com/prassamin/claw-code/tree/main/src/state"
click node_node_commands "https://github.com/prassamin/claw-code/tree/main/src/commands"
click node_node_input "https://github.com/prassamin/claw-code/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_node_tools "https://github.com/prassamin/claw-code/blob/main/src/services/tools/toolOrchestration.ts"
click node_node_tasks "https://github.com/prassamin/claw-code/tree/main/src/tasks"
click node_node_permissions "https://github.com/prassamin/claw-code/tree/main/src/utils/permissions"
click node_node_session "https://github.com/prassamin/claw-code/blob/main/src/history.ts"
click node_node_api "https://github.com/prassamin/claw-code/tree/main/src/services/api"
click node_node_plugins "https://github.com/prassamin/claw-code/tree/main/src/services/plugins"
click node_node_remote "https://github.com/prassamin/claw-code/tree/main/src/remote"
click node_node_bridge "https://github.com/prassamin/claw-code/tree/main/src/bridge"
click node_node_tools_impl "https://github.com/prassamin/claw-code/tree/main/src/tools"
click node_node_builtins "https://github.com/prassamin/claw-code/tree/main/src/skills/bundled"

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_node_ink,node_node_app,node_node_prompt,node_node_messages,node_node_permissions_ui,node_node_tasks_ui toneBlue
class node_node_state,node_node_commands,node_node_input,node_node_tools,node_node_tasks,node_node_permissions,node_node_session toneAmber
class node_node_api,node_node_plugins,node_node_remote,node_node_bridge,node_node_tools_impl,node_node_builtins toneMint
class node_node_entry,node_node_main toneRose
```

## Components

### UI / TUI

Ink-rendered terminal interface, screens, dialogs, and input handling.

- [Ink core](https://github.com/prassamin/claw-code/tree/main/src/ink): terminal ui framework · Custom Ink-like renderer, terminal primitives, input/event loop, and layout engine. · `src/ink`
- [App shell](https://github.com/prassamin/claw-code/blob/main/src/components/App.tsx): root ui · Main app composition, screens, dialogs, and visual state presentation. · `src/components/App.tsx`
- [Prompt flow](https://github.com/prassamin/claw-code/tree/main/src/components/PromptInput): input pipeline · User prompt entry, queued commands, and command submission handling. · `src/components/PromptInput`
- [Message views](https://github.com/prassamin/claw-code/tree/main/src/components/messages): terminal views · Rendered conversation, tool-use, task, and status messages. · `src/components/messages`
- [Permission UI](https://github.com/prassamin/claw-code/tree/main/src/components/permissions): approval dialogs · Interactive approval dialogs for shell, filesystem, network, plan, and sandbox actions. · `src/components/permissions`
- [Task views](https://github.com/prassamin/claw-code/tree/main/src/components/tasks): task panels · Terminal panels for background tasks, shells, remote sessions, and teammates. · `src/components/tasks`

### Core Orchestration

App state, session loop, commands, permissions, tasks, and service coordination.

- [App state](https://github.com/prassamin/claw-code/tree/main/src/state): state store · Central state container and selectors coordinating prompt, modal, notifications, stats, and voice. · `src/state`
- [Commands](https://github.com/prassamin/claw-code/tree/main/src/commands): command layer · Slash and top-level command orchestration for onboarding, config, sessions, plugins, remote, and diagnostics. · `src/commands`
- [Input processing](https://github.com/prassamin/claw-code/blob/main/src/utils/processUserInput/processUserInput.ts): command parser · Turns raw terminal input into prompts, slash commands, or shell commands. · `src/utils/processUserInput/processUserInput.ts`
- [Tool orchestration](https://github.com/prassamin/claw-code/blob/main/src/services/tools/toolOrchestration.ts): execution hub · Registers tools, executes them, summarizes results, and coordinates tool-side hooks. · `src/services/tools/toolOrchestration.ts`
- [Task engine](https://github.com/prassamin/claw-code/tree/main/src/tasks): agent/task loop · Task definitions and execution primitives for local, remote, shell, and in-process agent work. · `src/tasks`
- [Safety policy](https://github.com/prassamin/claw-code/tree/main/src/utils/permissions): policy engine · Permission rules, approval hooks, denial tracking, and auto/plan mode behavior. · `src/utils/permissions`
- [Session memory](https://github.com/prassamin/claw-code/blob/main/src/history.ts): continuity · Conversation history, restore/resume, memory extraction, and context compaction. · `src/history.ts`

### Adapters / Integrations

External execution backends, cloud services, plugins, remote control, and platform integrations.

- [Cloud API](https://github.com/prassamin/claw-code/tree/main/src/services/api): external api · Anthropic/API access, OAuth, analytics, usage, and model capability validation. · `src/services/api`
- [Plugins](https://github.com/prassamin/claw-code/tree/main/src/services/plugins): extension system · Plugin install, validation, loading, marketplace, bundled plugins, and plugin commands. · `src/services/plugins`
- [Remote control](https://github.com/prassamin/claw-code/tree/main/src/remote): distributed runtime · Remote sessions, WebSocket transports, direct-connect setup, and server-side session creation. · `src/remote`
- [Bridge layer](https://github.com/prassamin/claw-code/tree/main/src/bridge): session bridge · Remote/session bridge for attachment, wake/poll, transport, trust, and permission callbacks. · `src/bridge`
- [Tool modules](https://github.com/prassamin/claw-code/tree/main/src/tools): tool implementations · Concrete tools such as shell, file, search, LSP, MCP, web, tasks, agents, skills, cron, and triggers. · `src/tools`
- [Built-in skills](https://github.com/prassamin/claw-code/tree/main/src/skills/bundled): prompt assets · Bundled skills and reusable behavior templates that augment tool and agent workflows. · `src/skills/bundled`

### Runtime / Build

Entrypoints and packaging for the portable Bun/TypeScript CLI.

- [CLI entry](https://github.com/prassamin/claw-code/blob/main/src/entrypoints/cli.tsx): entrypoint · Bun/TSX startup path for the terminal app and bundled CLI artifact. · `src/entrypoints/cli.tsx`
- [Main shell](https://github.com/prassamin/claw-code/blob/main/src/main.tsx): bootstrap · Application bootstrap and top-level wiring into the CLI runtime. · `src/main.tsx`

## Connections

- CLI entry → Main shell: starts · The CLI entrypoint boots the main application shell.
- Main shell → Ink core: renders in · Bootstrapping mounts the interactive terminal UI runtime.
- Ink core → App shell: hosts · Ink provides the rendering substrate for the app shell.
- App shell → Prompt flow: accepts input · The app shell centers around prompt entry and queued commands.
- App shell → Message views: shows conversation · Conversation, tool activity, and status events are rendered as terminal messages.
- App shell → Task views: shows tasks · Task and session status are surfaced in task-oriented panels.
- App shell → Permission UI: asks approval · Sensitive actions are mediated by dialog-driven permission UI.
- Prompt flow → Input processing: parses · Prompt submission flows into command and text processing.
- Input processing → Commands: dispatches · Slash-style and operational commands are routed to the command layer.
- Input processing → Tool orchestration: starts tools · Plain user requests can become tool-backed execution requests.
- Commands → App state: updates · Commands mostly orchestrate state changes and screen transitions.
- App state → Task engine: tracks · Core state holds the active task/session graph and progress.
- Task engine → Tool orchestration: invokes · Agent and shell tasks drive tool execution.
- Tool orchestration → Safety policy: gated by · Tool execution is checked against permission and safety policy.
- Safety policy → Permission UI: prompts · Policy decisions can surface interactive approval dialogs.
- Task engine → Session memory: persists · Task progress feeds session history, memory, and resume data.
- Session memory → Cloud API: syncs · Conversation memory and summarization interact with model/API services.
- Tool orchestration → Cloud API: calls cloud · Web, model, auth, telemetry, and remote-assisted features depend on API services.
- Tool orchestration → Tool modules: uses · The orchestration hub delegates to concrete tool modules.
- Tool modules → Built-in skills: extends · Tools and agents are augmented by bundled skills/templates.
- Remote control → Bridge layer: connects via · Remote sessions attach through the bridge boundary.
- Bridge layer → App state: feeds state · Bridge events and session attachment update local session/UI state.
- Remote control → Task engine: runs tasks · Remote and distributed execution share the task model.
- Plugins → Tool orchestration: adds tools · Plugins can contribute commands, hooks, agents, and MCP integrations.
- Plugins → Commands: adds commands · Plugin management is exposed through the command layer.
- Plugins → Cloud API: marketplace · Plugin install and validation depend on external service integration.
