Architecture

Clew Code is a single-entry Bun bundle built with TypeScript (ESM, strict mode).

Layer Overview

The architecture is layered: CLI entrypoint → Orchestrator → Context/Tools/Policy/Provider → Session logger.

CLI (parseArgs)
   ↓
Orchestrator (Agent loop)
   ↓
Context ── Tools ── Policy ── Provider
   ↓
Session Logger

Source Layout

src/
├── main.tsx                 # Entry point
├── query.ts / QueryEngine.ts
├── agentRuntime/            # Background agent orchestration
├── commands/                # Slash command implementations
├── tools/                   # 50+ built-in tools
├── services/
│   ├── ai/                  # Provider manager + 27 providers
│   ├── mcp/                 # MCP client + auth + transports
│   ├── plugins/             # Plugin hooks + marketplace
│   ├── autonomous/          # Agent loop + task queue + cron
│   ├── lsp/                 # LSP integration
│   └── Supervisor/          # Agent supervisor IPC
├── peer/                    # PeerServer + PeerDiscovery
├── bridge/                  # WebSocket bridge + relay
├── components/              # Ink terminal UI components
├── state/                   # AppState management
└── hooks/                   # React hooks

Execution Layers

Clew Code has several agent execution layers:

Layer	Duration	Use Case
Agent	Session-long	Main chat, custom agents in .clew/agents/*.md
Subagent	One-shot	Explore codebase, test triage, review
Teammate/Swarm	Multi-turn	Coordinated long-running agent teams
LAN Peer	Persistent	Cross-machine coordination via /peer
Process Peer	One-shot	External CLI workers (Codex exec/pty)

Key Concepts

Multi-Pass Compaction

Automatic chunk-based context compression with recursive re-compaction when context exceeds the model window. Trigger manually with /compact.

Plan Mode

Full-access planning mode with bypass permissions. Plans persist to .clew/plans/ with progress snapshots.

Provider Manager

The ProviderManager routes all LLM calls through a unified interface. Each provider has an adapter that normalizes requests and responses. The provider can be switched mid-session via /model.