How prassamin/claw-code works
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: toolOrchestration.ts Tool orchestration · App.tsx App shell · tasks Task engine · plugins Plugins
Components 21
UI / TUI
Ink-rendered terminal interface, screens, dialogs, and input handling.
- Ink core · Custom Ink-like renderer, terminal primitives, input/event loop, and layout engine.
src/ink - App shell · Main app composition, screens, dialogs, and visual state presentation.
src/components/App.tsx - Prompt flow · User prompt entry, queued commands, and command submission handling.
src/components/PromptInput - Message views · Rendered conversation, tool-use, task, and status messages.
src/components/messages - Permission UI · Interactive approval dialogs for shell, filesystem, network, plan, and sandbox actions.
src/components/permissions - Task views · 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 · Central state container and selectors coordinating prompt, modal, notifications, stats, and voice.
src/state - Commands · Slash and top-level command orchestration for onboarding, config, sessions, plugins, remote, and diagnostics.
src/commands - Input processing · Turns raw terminal input into prompts, slash commands, or shell commands.
src/utils/processUserInput/processUserInput.ts - Tool orchestration · Registers tools, executes them, summarizes results, and coordinates tool-side hooks.
src/services/tools/toolOrchestration.ts - Task engine · Task definitions and execution primitives for local, remote, shell, and in-process agent work.
src/tasks - Safety policy · Permission rules, approval hooks, denial tracking, and auto/plan mode behavior.
src/utils/permissions - Session memory · 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 · Anthropic/API access, OAuth, analytics, usage, and model capability validation.
src/services/api - Plugins · Plugin install, validation, loading, marketplace, bundled plugins, and plugin commands.
src/services/plugins - Remote control · Remote sessions, WebSocket transports, direct-connect setup, and server-side session creation.
src/remote - Bridge layer · Remote/session bridge for attachment, wake/poll, transport, trust, and permission callbacks.
src/bridge - Tool modules · Concrete tools such as shell, file, search, LSP, MCP, web, tasks, agents, skills, cron, and triggers.
src/tools - Built-in skills · 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 · Bun/TSX startup path for the terminal app and bundled CLI artifact.
src/entrypoints/cli.tsx - Main shell · Application bootstrap and top-level wiring into the CLI runtime.
src/main.tsx
Connections 26
- 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.