clew-code 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +292 -299
  2. package/dist/main.js +2745 -2869
  3. package/docs/architecture.html +148 -145
  4. package/docs/architecture.th.html +79 -78
  5. package/docs/clew-code-architecture.html +1125 -0
  6. package/docs/commands.html +224 -223
  7. package/docs/commands.th.html +131 -130
  8. package/docs/configuration.html +147 -145
  9. package/docs/configuration.th.html +108 -106
  10. package/docs/css/styles.css +48 -42
  11. package/docs/daemon.html +129 -128
  12. package/docs/daemon.th.html +73 -72
  13. package/docs/features/bridge-mode.html +99 -98
  14. package/docs/features/bridge-mode.th.html +90 -89
  15. package/docs/features/evals.html +182 -181
  16. package/docs/features/evals.th.html +90 -89
  17. package/docs/features/peer.html +178 -177
  18. package/docs/features/searxng-search.html +151 -150
  19. package/docs/features/searxng-search.th.html +95 -94
  20. package/docs/features/sentry-setup.html +157 -156
  21. package/docs/features/sentry-setup.th.html +97 -96
  22. package/docs/index.html +299 -298
  23. package/docs/index.th.html +292 -290
  24. package/docs/installation.html +105 -103
  25. package/docs/installation.th.html +105 -103
  26. package/docs/internals/growthbook-ab-testing.html +113 -112
  27. package/docs/internals/growthbook-ab-testing.th.html +81 -80
  28. package/docs/internals/hidden-features.html +149 -147
  29. package/docs/internals/hidden-features.th.html +109 -107
  30. package/docs/js/main.js +83 -3
  31. package/docs/loop.html +181 -180
  32. package/docs/loop.th.html +227 -226
  33. package/docs/mcp.html +247 -246
  34. package/docs/mcp.th.html +207 -206
  35. package/docs/models.html +111 -110
  36. package/docs/models.th.html +61 -60
  37. package/docs/peer.html +236 -235
  38. package/docs/peer.th.html +280 -279
  39. package/docs/permission-model.html +102 -101
  40. package/docs/permission-model.th.html +67 -66
  41. package/docs/plugins.html +102 -101
  42. package/docs/plugins.th.html +79 -78
  43. package/docs/providers.html +126 -117
  44. package/docs/providers.th.html +80 -78
  45. package/docs/quick-start.html +93 -92
  46. package/docs/quick-start.th.html +40 -39
  47. package/docs/research-memory.html +82 -79
  48. package/docs/research-memory.th.html +72 -71
  49. package/docs/skills.html +117 -116
  50. package/docs/skills.th.html +90 -89
  51. package/docs/tools.html +170 -169
  52. package/docs/tools.th.html +84 -83
  53. package/docs/troubleshooting.html +106 -105
  54. package/docs/troubleshooting.th.html +85 -84
  55. package/package.json +164 -162
  56. package/docs/taste.html +0 -436
  57. package/docs/taste.th.html +0 -236
package/docs/architecture.html CHANGED
@@ -1,145 +1,148 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Architecture — Clew</title>
7
- <meta name="description" content="Runtime architecture, layered design, and data flow for Clew CLI.">
8
- <link rel="preconnect" href="https://fonts.googleapis.com">
9
- <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
- <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
- <link rel="stylesheet" href="css/styles.css">
12
- <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
- </head>
14
- <body>
15
- <header class="header"></header>
16
- <div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
17
- <div class="content-wrap"><main class="content">
18
- <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Architecture</span></div>
19
- <h1>Architecture</h1>
20
- <p class="section-subtitle">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.</p>
21
-
22
- <h2>Layered Design</h2>
23
- <p>The application is structured as four cooperative layers:</p>
24
-
25
- <h3>1. Terminal UI (React 19 + Ink 6)</h3>
26
- <p>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 <code>src/components/</code>, state management in <code>src/state/</code>, and React context in <code>src/context/</code>.</p>
27
-
28
- <h3>2. CLI &amp; Command Layer (Commander.js 13)</h3>
29
- <p>Entry point at <code>src/main.tsx</code> — parses CLI flags (<code>--model</code>, <code>--print</code>, <code>--permission-mode</code>, <code>--mcp-config</code>, etc.), loads config, initializes providers and telemetry, then launches the REPL or print-mode query. Slash commands are registered in <code>src/commands.ts</code> and implemented under <code>src/commands/</code>. Commands are categorized as <code>local</code> (runs in-terminal), <code>prompt</code> (skills that expand to text), or <code>local-jsx</code> (Ink UI panels).</p>
30
-
31
- <h3>3. AI Provider &amp; Adapter Layer</h3>
32
- <p><strong>ProviderManager</strong> (<code>src/services/ai/ProviderManager.ts</code>) resolves API keys, selects models, and manages provider config. Provider metadata is declared in <code>src/services/ai/providers.json</code> — currently 27 providers with model listings, capabilities, base URLs, and env key mappings. Non-Anthropic providers are wrapped by the <strong>AnthropicAdapter</strong> or <strong>GoogleAdapter</strong>, which normalize content blocks (<code>contentBlockUtils.ts</code>), tool calls (<code>toolCallParser.ts</code>), errors (<code>errorNormalizer.ts</code>), and usage (<code>usageNormalizer.ts</code>) to a uniform format.</p>
33
-
34
- <h3>4. Tool Execution &amp; Query Loop</h3>
35
- <p>Tools use Zod schemas and are executed by the <strong>StreamingToolExecutor</strong> (<code>src/services/tools/StreamingToolExecutor.ts</code>). Permission gating via hooks in <code>src/utils/permissions/permissions.ts</code>. The query loop in <code>src/query.ts</code> + <code>src/QueryEngine.ts</code> orchestrates message building, context management, streaming, and tool call cycling. MCP tools (<code>src/services/mcp/</code>) are discovered at runtime and merged into the tool pool.</p>
36
-
37
- <h2>Data Flow</h2>
38
- <pre><code> Terminal input
39
- |
40
- v
41
- + Query Engine (query.ts + QueryEngine.ts)
42
- | Message building and context assembly
43
- | Tool call loop (model tool results)
44
- | Streaming response handling
45
- |
46
- + Provider Manager Adapter AI Model API
47
- | 27 providers via providers.json
48
- | AnthropicAdapter / GoogleAdapter normalization
49
- |
50
- + Tool Executor (StreamingToolExecutor)
51
- | Permission check (permissions.ts)
52
- | Pre/Post tool hooks (plugins)
53
- | Tool execution result
54
- |
55
- + Terminal UI (React/Ink)
56
- Streaming text and tool renders
57
- Status bar, spinner, context meter
58
- Permission dialogs</code></pre>
59
-
60
- <h2>Key Subsystems</h2>
61
-
62
- <h3>MCP (Model Context Protocol)</h3>
63
- <p><code>src/services/mcp/</code> — manages external MCP server connections, tool discovery, resource access, and paginated <code>tools/list</code> responses. Servers configured via <code>--mcp-config</code> or <code>/mcp</code> command. See <a href="mcp.html">MCP</a> for detailed setup and configuration.</p>
64
-
65
- <h3>Plugins &amp; Hooks</h3>
66
- <p><code>src/services/plugins/</code> — plugin loading, installation, marketplace reconciliation, and hook dispatch. Hook points: <code>PreToolUse</code>, <code>PostToolUse</code>, <code>PreBash</code>, <code>PostPrompt</code>, <code>PreAcceptEdit</code>. Plugins can provide commands, agents, skills, MCP servers, and LSP integrations.</p>
67
-
68
- <h3>LSP (Language Server Protocol)</h3>
69
- <p><code>src/services/lsp/</code> — language-aware code intelligence via LSP servers. Diagnostics, completions, and symbol navigation. Enable with <code>ENABLE_LSP_TOOL=1</code>.</p>
70
-
71
- <h3>Bridge Mode</h3>
72
- <p><code>src/bridge/bridgeMain.ts</code> — WebSocket remote control and collaboration. Gated behind <code>BRIDGE_MODE=1</code>. Remote clients can send commands and receive responses.</p>
73
-
74
- <h3>Session System</h3>
75
- <p><code>src/services/SessionBridge/</code> — cross-session context persistence. <code>src/services/SessionMemory/</code> — persistent knowledge with cross-lingual semantic search and auto-memory capture.</p>
76
-
77
- <h3>GrowthBook Feature Flags</h3>
78
- <p><code>src/services/analytics/growthbook.js</code> — A/B testing and feature flag platform. Initialized at startup, evaluates flags locally with caching.</p>
79
-
80
- <h3>Agent Runtime</h3>
81
- <p><code>src/agentRuntime/</code> — manages multi-agent orchestration. The <strong>orchestrator</strong> coordinates agent sessions, <strong>runStore</strong> persists agent run data, <strong>toolGateway</strong> routes tools between agents, and <strong>workflowRegistry</strong> / <strong>agentRegistry</strong> declare named workflows and agent configurations.</p>
82
-
83
- <h3>Autonomous / Daemon</h3>
84
- <p><code>src/services/autonomous/</code> — enables 24/7 background execution. The <strong>taskQueue</strong> is a file-backed queue with priorities, leases, and dead-letter handling. <strong>agentLoop</strong> runs the continuous dequeue spawn worker monitor retry cycle. <strong>daemonMode</strong> provides the supervisor-managed background process entry point, and <strong>supervisorIntegration</strong> handles health checks and auto-respawn. See <a href="daemon.html">Daemon Mode</a> for detailed configuration and usage.</p>
85
-
86
- <h3>Coordinator (Multi-Agent)</h3>
87
- <p><code>src/coordinator/</code> — supports multi-agent collaboration. <strong>coordinatorMode</strong> delegates tasks to sub-agents, and <strong>workerAgent</strong> provides standalone workers for delegated subtasks.</p>
88
-
89
- <h3>Research &amp; Memory</h3>
90
- <p><code>src/research/</code> — built-in deep research capabilities: citation extraction, claim verification, dossier generation, truth checking, and source ranking. <code>src/memdir/</code> — semantic memory with text embedding search, memory age tracking, auto-memory capture, and cross-session recall. See <a href="research-memory.html">Research &amp; Memory</a> for detailed usage.</p>
91
-
92
- <h3>Voice Mode</h3>
93
- <p><code>src/voice/</code> — compile-time gated voice input support (<code>VOICE_MODE=1</code>). Provides speech-to-text and voice command processing for hands-free operation.</p>
94
-
95
- <h3>State Management</h3>
96
- <p>The app uses a lightweight observable store pattern (<code>createStore&lt;T&gt;</code> in <code>src/state/store.ts</code>). Stores are plain functions with <code>getState</code>, <code>setState</code>, and <code>subscribe</code>. React components subscribe via the <strong>AppState</strong> React context (<code>src/state/AppState.tsx</code>).</p>
97
-
98
- <h2>Important Source Paths</h2>
99
- <table>
100
- <tr><th>Path</th><th>Role</th></tr>
101
- <tr><td><code>src/main.tsx</code></td><td>CLI entry, Commander program, option parsing, REPL launch</td></tr>
102
- <tr><td><code>src/query.ts</code></td><td>Core query processing, message building, tool call loop</td></tr>
103
- <tr><td><code>src/QueryEngine.ts</code></td><td>Query orchestration, caching, deduplication, rate limiting</td></tr>
104
- <tr><td><code>src/commands.ts</code></td><td>Slash command registry (80+ commands)</td></tr>
105
- <tr><td><code>src/tools.ts</code></td><td>Tool registry (40+ built-in tools)</td></tr>
106
- <tr><td><code>src/Tool.ts</code></td><td>Base tool types, schemas, buildTool() helper</td></tr>
107
- <tr><td><code>src/services/ai/ProviderManager.ts</code></td><td>Provider selection, API key resolution</td></tr>
108
- <tr><td><code>src/services/ai/providers.json</code></td><td>Declarative provider config (27 providers)</td></tr>
109
- <tr><td><code>src/services/ai/adapter/</code></td><td>AnthropicAdapter, GoogleAdapter</td></tr>
110
- <tr><td><code>src/services/tools/StreamingToolExecutor.ts</code></td><td>Streaming tool execution</td></tr>
111
- <tr><td><code>src/utils/permissions/permissions.ts</code></td><td>Permission evaluation logic</td></tr>
112
- <tr><td><code>src/services/mcp/</code></td><td>MCP server management</td></tr>
113
- <tr><td><code>src/services/plugins/</code></td><td>Plugin loader and hook dispatch</td></tr>
114
- <tr><td><code>src/state/store.ts</code></td><td>Lightweight observable store (createStore&lt;T&gt;)</td></tr>
115
- <tr><td><code>src/state/AppState.tsx</code></td><td>Root app state (React context)</td></tr>
116
- <tr><td><code>src/state/AppStateStore.ts</code></td><td>App state store implementation</td></tr>
117
- <tr><td><code>src/state/selectors.ts</code></td><td>State selectors</td></tr>
118
- <tr><td><code>src/agentRuntime/</code></td><td>Agent orchestration, run store, tool gateway</td></tr>
119
- <tr><td><code>src/services/autonomous/</code></td><td>Task queue, agent loop, daemon mode, supervisor</td></tr>
120
- <tr><td><code>src/coordinator/</code></td><td>Multi-agent coordinator and worker agents</td></tr>
121
- <tr><td><code>src/research/</code></td><td>Deep research, dossier generation, truth checking</td></tr>
122
- <tr><td><code>src/memdir/</code></td><td>Semantic memory search and storage</td></tr>
123
- <tr><td><code>src/voice/</code></td><td>Voice mode support (compile-time gated)</td></tr>
124
- <tr><td><code>src/entrypoints/init.ts</code></td><td>Startup initialization (Sentry, configs, telemetry)</td></tr>
125
- <tr><td><code>src/entrypoints/cli.tsx</code></td><td>Alternative CLI entry point (Commander-based)</td></tr>
126
- <tr><td><code>src/entrypoints/mcp.ts</code></td><td>MCP server entry point</td></tr>
127
- </table>
128
-
129
- <h2>Build System</h2>
130
- <p>Built with Bun bundler — <code>bun run build</code> outputs a single binary to <code>dist/</code>. 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.</p>
131
-
132
- <footer class="footer">
133
- <span>Clew Code v0.2.4 — Open Source</span>
134
- <div class="footer-links">
135
- <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
136
- <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
137
- </div>
138
- </footer>
139
- </main>
140
- <nav class="toc-sidebar"></nav>
141
- </div>
142
- </div>
143
- <script src="js/main.js"></script>
144
- </body>
145
- </html>
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Architecture — Clew</title>
7
+ <meta name="description" content="Runtime architecture, layered design, and data flow for Clew CLI.">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
+ <link rel="stylesheet" href="css/styles.css">
12
+ <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
+ </head>
14
+ <body>
15
+ <header class="header"></header>
16
+ <div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
17
+ <div class="content-wrap"><main class="content">
18
+ <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Architecture</span></div>
19
+ <h1>Architecture</h1>
20
+ <p class="section-subtitle">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.</p>
21
+
22
+ <h2>Layered Design</h2>
23
+ <p>The application is structured as four cooperative layers:</p>
24
+
25
+ <h3>1. Terminal UI (React 19 + Ink 6)</h3>
26
+ <p>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 <code>src/components/</code>, state management in <code>src/state/</code>, and React context in <code>src/context/</code>.</p>
27
+
28
+ <h3>2. CLI &amp; Command Layer (Commander.js 13)</h3>
29
+ <p>Entry point at <code>src/main.tsx</code> — parses CLI flags (<code>--model</code>, <code>--print</code>, <code>--permission-mode</code>, <code>--mcp-config</code>, etc.), loads config, initializes providers and telemetry, then launches the REPL or print-mode query. Slash commands are registered in <code>src/commands.ts</code> and implemented under <code>src/commands/</code>. Commands are categorized as <code>local</code> (runs in-terminal), <code>prompt</code> (skills that expand to text), or <code>local-jsx</code> (Ink UI panels).</p>
30
+
31
+ <h3>3. AI Provider &amp; Adapter Layer</h3>
32
+ <p><strong>ProviderManager</strong> (<code>src/services/ai/ProviderManager.ts</code>) resolves API keys, selects models, and manages provider config. Provider metadata is declared in <code>src/services/ai/providers.json</code> — currently <strong>32 providers</strong> (9 dedicated classes + 23 OpenAI-compatible) with model listings, capabilities, base URLs, and env key mappings. Non-Anthropic providers are wrapped by the <strong>AnthropicAdapter</strong> or <strong>GoogleAdapter</strong>, which normalize content blocks (<code>contentBlockUtils.ts</code>), tool calls (<code>toolCallParser.ts</code>), errors (<code>errorNormalizer.ts</code>), and usage (<code>usageNormalizer.ts</code>) to a uniform format.</p>
33
+
34
+ <h3>4. Tool Execution &amp; Query Loop</h3>
35
+ <p>Tools use Zod schemas and are executed by the <strong>StreamingToolExecutor</strong> (<code>src/services/tools/StreamingToolExecutor.ts</code>). Permission gating via hooks in <code>src/utils/permissions/permissions.ts</code>. The query loop in <code>src/query.ts</code> + <code>src/QueryEngine.ts</code> orchestrates message building, context management, streaming, and tool call cycling. MCP tools (<code>src/services/mcp/</code>) are discovered at runtime and merged into the tool pool.</p>
36
+
37
+ <h2>Data Flow</h2>
38
+ <pre><code> Terminal input
39
+ |
40
+ v
41
+ + Query Engine (query.ts + QueryEngine.ts)
42
+ | Message building and context assembly
43
+ | Tool call loop (model tool results)
44
+ | Streaming response handling
45
+ |
46
+ + Provider Manager Adapter AI Model API
47
+ | 27 providers via providers.json
48
+ | AnthropicAdapter / GoogleAdapter normalization
49
+ |
50
+ + Tool Executor (StreamingToolExecutor)
51
+ | Permission check (permissions.ts)
52
+ | Pre/Post tool hooks (plugins)
53
+ | Tool execution result
54
+ |
55
+ + Terminal UI (React/Ink)
56
+ Streaming text and tool renders
57
+ Status bar, spinner, context meter
58
+ Permission dialogs</code></pre>
59
+
60
+ <h2>Key Subsystems</h2>
61
+
62
+ <h3>MCP (Model Context Protocol)</h3>
63
+ <p><code>src/services/mcp/</code> — manages external MCP server connections, tool discovery, resource access, and paginated <code>tools/list</code> responses. Servers configured via <code>--mcp-config</code> or <code>/mcp</code> command. See <a href="mcp.html">MCP</a> for detailed setup and configuration.</p>
64
+
65
+ <h3>Plugins &amp; Hooks</h3>
66
+ <p><code>src/services/plugins/</code> — plugin loading, installation, marketplace reconciliation, and hook dispatch. Hook points: <code>PreToolUse</code>, <code>PostToolUse</code>, <code>PreBash</code>, <code>PostPrompt</code>, <code>PreAcceptEdit</code>. Plugins can provide commands, agents, skills, MCP servers, and LSP integrations.</p>
67
+
68
+ <h3>LSP (Language Server Protocol)</h3>
69
+ <p><code>src/services/lsp/</code> — language-aware code intelligence via LSP servers. Diagnostics, completions, and symbol navigation. Enable with <code>ENABLE_LSP_TOOL=1</code>.</p>
70
+
71
+ <h3>Bridge Mode</h3>
72
+ <p><code>src/bridge/bridgeMain.ts</code> — WebSocket remote control and collaboration. Gated behind <code>BRIDGE_MODE=1</code>. Remote clients can send commands and receive responses.</p>
73
+
74
+ <h3>Session System</h3>
75
+ <p><code>src/services/SessionLifecycle/</code> — cross-session context persistence. <code>src/services/SessionMemory/</code> — persistent knowledge with cross-lingual semantic search and auto-memory capture.</p>
76
+
77
+ <h3>GrowthBook Feature Flags</h3>
78
+ <p><code>src/services/analytics/growthbook.js</code> — A/B testing and feature flag platform. Initialized at startup, evaluates flags locally with caching.</p>
79
+
80
+ <h3>Agent Runtime</h3>
81
+ <p><code>src/agentRuntime/</code> — manages multi-agent orchestration. The <strong>orchestrator</strong> coordinates agent sessions, <strong>runStore</strong> persists agent run data, <strong>toolGateway</strong> routes tools between agents, and <strong>workflowRegistry</strong> / <strong>agentRegistry</strong> declare named workflows and agent configurations.</p>
82
+
83
+ <h3>Autonomous / Daemon</h3>
84
+ <p><code>src/services/autonomous/</code> — enables 24/7 background execution. The <strong>taskQueue</strong> is a file-backed queue with priorities, leases, and dead-letter handling. <strong>agentLoop</strong> runs the continuous dequeue spawn worker monitor retry cycle. <strong>daemonMode</strong> provides the supervisor-managed background process entry point, and <strong>supervisorIntegration</strong> handles health checks and auto-respawn. See <a href="daemon.html">Daemon Mode</a> for detailed configuration and usage.</p>
85
+
86
+ <h3>Coordinator (Multi-Agent)</h3>
87
+ <p><code>src/coordinator/</code> — supports multi-agent collaboration. <strong>coordinatorMode</strong> delegates tasks to sub-agents, and <strong>workerAgent</strong> provides standalone workers for delegated subtasks.</p>
88
+
89
+ <h3>Memory</h3>
90
+ <p><code>src/memory/</code> — local embedding-free memory with SQLite FTS5 full-text search. Token-aware chunking (3000 tokens), truth priority scoring, secret redaction, and auto-ingest from <code>.claude/memory/</code>. See <a href="research-memory.html">Memory</a> for detailed usage.</p>
91
+
92
+ <h3>Voice Mode</h3>
93
+ <p><code>src/voice/</code> — compile-time gated voice input support (<code>VOICE_MODE=1</code>). Provides speech-to-text and voice command processing for hands-free operation.</p>
94
+
95
+ <h3>State Management</h3>
96
+ <p>The app uses a lightweight observable store pattern (<code>createStore&lt;T&gt;</code> in <code>src/state/store.ts</code>). Stores are plain functions with <code>getState</code>, <code>setState</code>, and <code>subscribe</code>. React components subscribe via the <strong>AppState</strong> React context (<code>src/state/AppState.tsx</code>).</p>
97
+
98
+ <h2>Important Source Paths</h2>
99
+ <table>
100
+ <tr><th>Path</th><th>Role</th></tr>
101
+ <tr><td><code>src/main.tsx</code></td><td>CLI entry, Commander program, option parsing, REPL launch</td></tr>
102
+ <tr><td><code>src/query.ts</code></td><td>Core query processing, message building, tool call loop</td></tr>
103
+ <tr><td><code>src/QueryEngine.ts</code></td><td>Query orchestration, caching, deduplication, rate limiting</td></tr>
104
+ <tr><td><code>src/commands.ts</code></td><td>Slash command registry (80+ commands)</td></tr>
105
+ <tr><td><code>src/tools.ts</code></td><td>Tool registry (40+ built-in tools)</td></tr>
106
+ <tr><td><code>src/Tool.ts</code></td><td>Base tool types, schemas, buildTool() helper</td></tr>
107
+ <tr><td><code>src/services/ai/ProviderManager.ts</code></td><td>Provider selection, API key resolution</td></tr>
108
+ <tr><td><code>src/services/ai/providers.json</code></td><td>Declarative provider config (27 providers)</td></tr>
109
+ <tr><td><code>src/services/ai/adapter/</code></td><td>AnthropicAdapter, GoogleAdapter</td></tr>
110
+ <tr><td><code>src/services/tools/StreamingToolExecutor.ts</code></td><td>Streaming tool execution</td></tr>
111
+ <tr><td><code>src/utils/permissions/permissions.ts</code></td><td>Permission evaluation logic</td></tr>
112
+ <tr><td><code>src/services/mcp/</code></td><td>MCP server management</td></tr>
113
+ <tr><td><code>src/services/plugins/</code></td><td>Plugin loader and hook dispatch</td></tr>
114
+ <tr><td><code>src/state/store.ts</code></td><td>Lightweight observable store (createStore&lt;T&gt;)</td></tr>
115
+ <tr><td><code>src/state/AppState.tsx</code></td><td>Root app state (React context)</td></tr>
116
+ <tr><td><code>src/state/AppStateStore.ts</code></td><td>App state store implementation</td></tr>
117
+ <tr><td><code>src/state/selectors.ts</code></td><td>State selectors</td></tr>
118
+ <tr><td><code>src/agentRuntime/</code></td><td>Agent orchestration, run store, tool gateway</td></tr>
119
+ <tr><td><code>src/services/autonomous/</code></td><td>Task queue, agent loop, daemon mode, supervisor</td></tr>
120
+ <tr><td><code>src/coordinator/</code></td><td>Multi-agent coordinator and worker agents</td></tr>
121
+ <tr><td><code>src/research/</code></td><td>Deep research, dossier generation, truth checking</td></tr>
122
+ <tr><td><code>src/memory/</code></td><td>SQLite FTS5 memory search (14 files)</td></tr>
123
+ <tr><td><code>src/voice/</code></td><td>Voice mode support (compile-time gated)</td></tr>
124
+ <tr><td><code>src/entrypoints/init.ts</code></td><td>Startup initialization (Sentry, configs, telemetry)</td></tr>
125
+ <tr><td><code>src/entrypoints/cli.tsx</code></td><td>Alternative CLI entry point (Commander-based)</td></tr>
126
+ <tr><td><code>src/entrypoints/mcp.ts</code></td><td>MCP server entry point</td></tr>
127
+ </table>
128
+
129
+ <h2>Build System</h2>
130
+ <p>Built with Bun bundler — <code>bun run build</code> outputs a single binary to <code>dist/</code>. 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.</p>
131
+
132
+ <footer class="footer">
133
+ <span>Clew Code v0.2.7 — Open Source</span>
134
+ <div class="footer-links">
135
+ <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
136
+ <a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
137
+ </div>
138
+ </footer>
139
+ </main>
140
+ <nav class="toc-sidebar"></nav>
141
+ </div>
142
+ </div>
143
+ <script src="js/main.js"></script>
144
+ </body>
145
+ </html>
146
+ dy>
147
+ </html>
148
+
package/docs/architecture.th.html CHANGED
@@ -1,78 +1,79 @@
1
- <!DOCTYPE html>
2
- <html lang="th">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>สถาปัตยกรรม — Clew</title>
7
- <meta name="description" content="สถาปัตยกรรมรันไทม์, การออกแบบแบบชั้น, และการไหลของข้อมูลสำหรับ Clew CLI">
8
- <link rel="preconnect" href="https://fonts.googleapis.com">
9
- <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
- <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Noto+Sans+Thai:wght@400;500;600;700&display=swap" rel="stylesheet">
11
- <link rel="stylesheet" href="css/styles.css">
12
- <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
- </head>
14
- <body>
15
- <header class="header"></header>
16
- <div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
17
- <div class="content-wrap"><main class="content">
18
- <div class="breadcrumbs"><a href="index.th.html">หน้าแรก</a><span class="sep">/</span><span>สถาปัตยกรรม</span></div>
19
- <h1>สถาปัตยกรรม</h1>
20
- <p class="section-subtitle">Clew คือผู้ช่วยเขียนโค้ด AI บนเทอร์มินัล — React/Ink TUI, CLI Commander.js, เครื่องยนต์ AI หลายผู้ให้บริการ, และรันไทม์เครื่องมือ/ปลั๊กอินที่ขยายได้ในกระบวนการเดียว</p>
21
-
22
- <h2>การออกแบบแบบชั้น</h2>
23
- <p>แอปพลิเคชันถูกจัดโครงสร้างเป็นสี่ชั้นที่ทำงานร่วมกัน:</p>
24
-
25
- <h3>1. Terminal UI (React 19 + Ink 6)</h3>
26
- <p>แสดง REPL แบบโต้ตอบ: อินพุต prompt, ผลลัพธ์ markdown แบบสตรีม, แถบสถานะพร้อมมาตรวัดบริบท, สไปนเนอร์, กล่องโต้ตอบสิทธิ์, ตัวสำรวจไฟล์, และโหมดเต็มหน้าจอ</p>
27
-
28
- <h3>2. CLI และชั้นคำสั่ง (Commander.js 13)</h3>
29
- <p>จุดเข้าที่ <code>src/main.tsx</code> — แยกวิเคราะห์ CLI flags, โหลดการตั้งค่า, เริ่มต้นผู้ให้บริการและ telemetry, แล้วเปิด REPL หรือโหมดพิมพ์</p>
30
-
31
- <h3>3. ชั้นผู้ให้บริการ AI และ Adapter</h3>
32
- <p><strong>ProviderManager</strong> (<code>src/services/ai/ProviderManager.ts</code>) จัดการการแก้ไขคีย์ API, เลือกโมเดล, และจัดการการตั้งค่าผู้ให้บริการ ขณะนี้มี 27 ผู้ให้บริการ</p>
33
-
34
- <h3>4. การดำเนินการเครื่องมือและ Query Loop</h3>
35
- <p>เครื่องมือใช้ Zod schemas และดำเนินการโดย <strong>StreamingToolExecutor</strong> (<code>src/services/tools/StreamingToolExecutor.ts</code>)</p>
36
-
37
- <h2>ระบบย่อยหลัก</h2>
38
-
39
- <h3>MCP (Model Context Protocol)</h3>
40
- <p><code>src/services/mcp/</code> — จัดการการเชื่อมต่อเซิร์ฟเวอร์ MCP ภายนอก, การค้นพบเครื่องมือ, การเข้าถึงทรัพยากร ดู <a href="mcp.th.html">MCP</a> สำหรับรายละเอียด</p>
41
-
42
- <h3>ปลั๊กอินและฮุค</h3>
43
- <p><code>src/services/plugins/</code> — การโหลดปลั๊กอิน, การติดตั้ง, การรวม marketplace, และการส่งฮุค</p>
44
-
45
- <h3>โหมด Bridge</h3>
46
- <p><code>src/bridge/bridgeMain.ts</code> — การควบคุมระยะไกลและการทำงานร่วมกันผ่าน WebSocket</p>
47
-
48
- <h3>รันไทม์เอเจนต์</h3>
49
- <p><code>src/agentRuntime/</code> — จัดการการจัดระเบียบหลายเอเจนต์</p>
50
-
51
- <h3>อัตโนมัติ / Daemon</h3>
52
- <p><code>src/services/autonomous/</code> — เปิดใช้งานการดำเนินการพื้นหลัง 24/7 คิวงาน, วนซ้ำเอเจนต์, โหมด daemon ดู <a href="daemon.th.html">โหมด Daemon</a></p>
53
-
54
- <h2>พาธซอร์สที่สำคัญ</h2>
55
- <table>
56
- <tr><th>พาธ</th><th>บทบาท</th></tr>
57
- <tr><td><code>src/main.tsx</code></td><td>จุดเข้า CLI, โปรแกรม Commander, การแยกวิเคราะห์ตัวเลือก, การเปิด REPL</td></tr>
58
- <tr><td><code>src/query.ts</code></td><td>การประมวลผลคำถามหลัก, การสร้างข้อความ, วนซ้ำการเรียกใช้เครื่องมือ</td></tr>
59
- <tr><td><code>src/commands.ts</code></td><td>ทะเบียนคำสั่ง slash (80+ คำสั่ง)</td></tr>
60
- <tr><td><code>src/tools.ts</code></td><td>ทะเบียนเครื่องมือ (40+ เครื่องมือในตัว)</td></tr>
61
- <tr><td><code>src/services/ai/ProviderManager.ts</code></td><td>การเลือกผู้ให้บริการ, การแก้ไขคีย์ API</td></tr>
62
- <tr><td><code>src/services/ai/providers.json</code></td><td>การตั้งค่าผู้ให้บริการ (27 ผู้ให้บริการ)</td></tr>
63
- </table>
64
-
65
- <footer class="footer">
66
- <span>Clew Code v0.2.4 — โอเพนซอร์ส</span>
67
- <div class="footer-links">
68
- <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
69
- <a href="https://github.com/JonusNattapong/ClewCode/issues">ปัญหา</a>
70
- </div>
71
- </footer>
72
- </main>
73
- <nav class="toc-sidebar"></nav>
74
- </div>
75
- </div>
76
- <script src="js/main.js"></script>
77
- </body>
78
- </html>
1
+ <!DOCTYPE html>
2
+ <html lang="th">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>สถาปัตยกรรม — Clew</title>
7
+ <meta name="description" content="สถาปัตยกรรมรันไทม์, การออกแบบแบบชั้น, และการไหลของข้อมูลสำหรับ Clew CLI">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Noto+Sans+Thai:wght@400;500;600;700&display=swap" rel="stylesheet">
11
+ <link rel="stylesheet" href="css/styles.css">
12
+ <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
+ </head>
14
+ <body>
15
+ <header class="header"></header>
16
+ <div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
17
+ <div class="content-wrap"><main class="content">
18
+ <div class="breadcrumbs"><a href="index.th.html">หน้าแรก</a><span class="sep">/</span><span>สถาปัตยกรรม</span></div>
19
+ <h1>สถาปัตยกรรม</h1>
20
+ <p class="section-subtitle">Clew คือผู้ช่วยเขียนโค้ด AI บนเทอร์มินัล — React/Ink TUI, CLI Commander.js, เครื่องยนต์ AI หลายผู้ให้บริการ, และรันไทม์เครื่องมือ/ปลั๊กอินที่ขยายได้ในกระบวนการเดียว</p>
21
+
22
+ <h2>การออกแบบแบบชั้น</h2>
23
+ <p>แอปพลิเคชันถูกจัดโครงสร้างเป็นสี่ชั้นที่ทำงานร่วมกัน:</p>
24
+
25
+ <h3>1. Terminal UI (React 19 + Ink 6)</h3>
26
+ <p>แสดง REPL แบบโต้ตอบ: อินพุต prompt, ผลลัพธ์ markdown แบบสตรีม, แถบสถานะพร้อมมาตรวัดบริบท, สไปนเนอร์, กล่องโต้ตอบสิทธิ์, ตัวสำรวจไฟล์, และโหมดเต็มหน้าจอ</p>
27
+
28
+ <h3>2. CLI และชั้นคำสั่ง (Commander.js 13)</h3>
29
+ <p>จุดเข้าที่ <code>src/main.tsx</code> — แยกวิเคราะห์ CLI flags, โหลดการตั้งค่า, เริ่มต้นผู้ให้บริการและ telemetry, แล้วเปิด REPL หรือโหมดพิมพ์</p>
30
+
31
+ <h3>3. ชั้นผู้ให้บริการ AI และ Adapter</h3>
32
+ <p><strong>ProviderManager</strong> (<code>src/services/ai/ProviderManager.ts</code>) จัดการการแก้ไขคีย์ API, เลือกโมเดล, และจัดการการตั้งค่าผู้ให้บริการ ขณะนี้มี 27 ผู้ให้บริการ</p>
33
+
34
+ <h3>4. การดำเนินการเครื่องมือและ Query Loop</h3>
35
+ <p>เครื่องมือใช้ Zod schemas และดำเนินการโดย <strong>StreamingToolExecutor</strong> (<code>src/services/tools/StreamingToolExecutor.ts</code>)</p>
36
+
37
+ <h2>ระบบย่อยหลัก</h2>
38
+
39
+ <h3>MCP (Model Context Protocol)</h3>
40
+ <p><code>src/services/mcp/</code> — จัดการการเชื่อมต่อเซิร์ฟเวอร์ MCP ภายนอก, การค้นพบเครื่องมือ, การเข้าถึงทรัพยากร ดู <a href="mcp.th.html">MCP</a> สำหรับรายละเอียด</p>
41
+
42
+ <h3>ปลั๊กอินและฮุค</h3>
43
+ <p><code>src/services/plugins/</code> — การโหลดปลั๊กอิน, การติดตั้ง, การรวม marketplace, และการส่งฮุค</p>
44
+
45
+ <h3>โหมด Bridge</h3>
46
+ <p><code>src/bridge/bridgeMain.ts</code> — การควบคุมระยะไกลและการทำงานร่วมกันผ่าน WebSocket</p>
47
+
48
+ <h3>รันไทม์เอเจนต์</h3>
49
+ <p><code>src/agentRuntime/</code> — จัดการการจัดระเบียบหลายเอเจนต์</p>
50
+
51
+ <h3>อัตโนมัติ / Daemon</h3>
52
+ <p><code>src/services/autonomous/</code> — เปิดใช้งานการดำเนินการพื้นหลัง 24/7 คิวงาน, วนซ้ำเอเจนต์, โหมด daemon ดู <a href="daemon.th.html">โหมด Daemon</a></p>
53
+
54
+ <h2>พาธซอร์สที่สำคัญ</h2>
55
+ <table>
56
+ <tr><th>พาธ</th><th>บทบาท</th></tr>
57
+ <tr><td><code>src/main.tsx</code></td><td>จุดเข้า CLI, โปรแกรม Commander, การแยกวิเคราะห์ตัวเลือก, การเปิด REPL</td></tr>
58
+ <tr><td><code>src/query.ts</code></td><td>การประมวลผลคำถามหลัก, การสร้างข้อความ, วนซ้ำการเรียกใช้เครื่องมือ</td></tr>
59
+ <tr><td><code>src/commands.ts</code></td><td>ทะเบียนคำสั่ง slash (80+ คำสั่ง)</td></tr>
60
+ <tr><td><code>src/tools.ts</code></td><td>ทะเบียนเครื่องมือ (40+ เครื่องมือในตัว)</td></tr>
61
+ <tr><td><code>src/services/ai/ProviderManager.ts</code></td><td>การเลือกผู้ให้บริการ, การแก้ไขคีย์ API</td></tr>
62
+ <tr><td><code>src/services/ai/providers.json</code></td><td>การตั้งค่าผู้ให้บริการ (27 ผู้ให้บริการ)</td></tr>
63
+ </table>
64
+
65
+ <footer class="footer">
66
+ <span>Clew Code v0.2.7 — โอเพนซอร์ส</span>
67
+ <div class="footer-links">
68
+ <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
69
+ <a href="https://github.com/ClewCode/ClewCode/issues">ปัญหา</a>
70
+ </div>
71
+ </footer>
72
+ </main>
73
+ <nav class="toc-sidebar"></nav>
74
+ </div>
75
+ </div>
76
+ <script src="js/main.js"></script>
77
+ </body>
78
+ </html>
79
+