Architecture

Clew is a terminal-based AI coding assistant — a React/Ink TUI, Commander.js CLI, multi-provider AI engine, and extensible tool/plugin runtime all in one process.

Layered Design

The application is structured as four cooperative layers:

1. Terminal UI (React 19 + Ink 6)

Renders the interactive REPL: prompt input, streaming markdown output, status bar with context meter, arc spinner, permission dialogs, file explorer, inline images, buddy (duck) companion, and fullscreen mode. Components live in src/components/, state management in src/state/, and React context in src/context/.

2. CLI & Command Layer (Commander.js 13)

Entry point at src/main.tsx — parses CLI flags (--model, --print, --permission-mode, --mcp-config, etc.), loads config, initializes providers and telemetry, then launches the REPL or print-mode query. Slash commands are registered in src/commands.ts and implemented under src/commands/. Commands are categorized as local (runs in-terminal), prompt (skills that expand to text), or local-jsx (Ink UI panels).

3. AI Provider & Adapter Layer

ProviderManager (src/services/ai/ProviderManager.ts) resolves API keys, selects models, and manages provider config. Provider metadata is declared in src/services/ai/providers.json — currently 27 providers with model listings, capabilities, base URLs, and env key mappings. Non-Anthropic providers are wrapped by the AnthropicAdapter or GoogleAdapter, which normalize content blocks (contentBlockUtils.ts), tool calls (toolCallParser.ts), errors (errorNormalizer.ts), and usage (usageNormalizer.ts) to a uniform format.

4. Tool Execution & Query Loop

Tools use Zod schemas and are executed by the StreamingToolExecutor (src/services/tools/StreamingToolExecutor.ts). Permission gating via hooks in src/utils/permissions/permissions.ts. The query loop in src/query.ts + src/QueryEngine.ts orchestrates message building, context management, streaming, and tool call cycling. MCP tools (src/services/mcp/) are discovered at runtime and merged into the tool pool.

Data Flow

  Terminal input
       |
       v
  + Query Engine (query.ts + QueryEngine.ts)
  |    Message building and context assembly
  |    Tool call loop (model tool results)
  |    Streaming response handling
  |
  + Provider Manager Adapter AI Model API
  |    27 providers via providers.json
  |    AnthropicAdapter / GoogleAdapter normalization
  |
  + Tool Executor (StreamingToolExecutor)
  |    Permission check (permissions.ts)
  |    Pre/Post tool hooks (plugins)
  |    Tool execution result
  |
  + Terminal UI (React/Ink)
       Streaming text and tool renders
       Status bar, spinner, context meter
       Permission dialogs

Key Subsystems

MCP (Model Context Protocol)

src/services/mcp/ — manages external MCP server connections, tool discovery, resource access, and paginated tools/list responses. Servers configured via --mcp-config or /mcp command. See MCP for detailed setup and configuration.

Plugins & Hooks

src/services/plugins/ — plugin loading, installation, marketplace reconciliation, and hook dispatch. Hook points: PreToolUse, PostToolUse, PreBash, PostPrompt, PreAcceptEdit. Plugins can provide commands, agents, skills, MCP servers, and LSP integrations.

LSP (Language Server Protocol)

src/services/lsp/ — language-aware code intelligence via LSP servers. Diagnostics, completions, and symbol navigation. Enable with ENABLE_LSP_TOOL=1.

Bridge Mode

src/bridge/bridgeMain.ts — WebSocket remote control and collaboration. Gated behind BRIDGE_MODE=1. Remote clients can send commands and receive responses.

Session System

src/services/SessionBridge/ — cross-session context persistence. src/services/SessionMemory/ — persistent knowledge with cross-lingual semantic search and auto-memory capture.

GrowthBook Feature Flags

src/services/analytics/growthbook.js — A/B testing and feature flag platform. Initialized at startup, evaluates flags locally with caching.

Agent Runtime

src/agentRuntime/ — manages multi-agent orchestration. The orchestrator coordinates agent sessions, runStore persists agent run data, toolGateway routes tools between agents, and workflowRegistry / agentRegistry declare named workflows and agent configurations.

Autonomous / Daemon

src/services/autonomous/ — enables 24/7 background execution. The taskQueue is a file-backed queue with priorities, leases, and dead-letter handling. agentLoop runs the continuous dequeue spawn worker monitor retry cycle. daemonMode provides the supervisor-managed background process entry point, and supervisorIntegration handles health checks and auto-respawn. See Daemon Mode for detailed configuration and usage.

Coordinator (Multi-Agent)

src/coordinator/ — supports multi-agent collaboration. coordinatorMode delegates tasks to sub-agents, and workerAgent provides standalone workers for delegated subtasks.

Research & Memory

src/research/ — built-in deep research capabilities: citation extraction, claim verification, dossier generation, truth checking, and source ranking. src/memdir/ — semantic memory with text embedding search, memory age tracking, auto-memory capture, and cross-session recall. See Research & Memory for detailed usage.

Voice Mode

src/voice/ — compile-time gated voice input support (VOICE_MODE=1). Provides speech-to-text and voice command processing for hands-free operation.

State Management

The app uses a lightweight observable store pattern (createStore<T> in src/state/store.ts). Stores are plain functions with getState, setState, and subscribe. React components subscribe via the AppState React context (src/state/AppState.tsx).

Important Source Paths

Build System

Built with Bun bundler — bun run build outputs a single binary to dist/. TypeScript with strict mode and ESM/NodeNext module resolution. External dependencies include Electron, chromium-bidi, AWS SDK, Google Auth, and platform-specific native modules. Lint/format via Biome 2.4.