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.
- package/README.md +292 -299
- package/dist/main.js +2745 -2869
- package/docs/architecture.html +148 -145
- package/docs/architecture.th.html +79 -78
- package/docs/clew-code-architecture.html +1125 -0
- package/docs/commands.html +224 -223
- package/docs/commands.th.html +131 -130
- package/docs/configuration.html +147 -145
- package/docs/configuration.th.html +108 -106
- package/docs/css/styles.css +48 -42
- package/docs/daemon.html +129 -128
- package/docs/daemon.th.html +73 -72
- package/docs/features/bridge-mode.html +99 -98
- package/docs/features/bridge-mode.th.html +90 -89
- package/docs/features/evals.html +182 -181
- package/docs/features/evals.th.html +90 -89
- package/docs/features/peer.html +178 -177
- package/docs/features/searxng-search.html +151 -150
- package/docs/features/searxng-search.th.html +95 -94
- package/docs/features/sentry-setup.html +157 -156
- package/docs/features/sentry-setup.th.html +97 -96
- package/docs/index.html +299 -298
- package/docs/index.th.html +292 -290
- package/docs/installation.html +105 -103
- package/docs/installation.th.html +105 -103
- package/docs/internals/growthbook-ab-testing.html +113 -112
- package/docs/internals/growthbook-ab-testing.th.html +81 -80
- package/docs/internals/hidden-features.html +149 -147
- package/docs/internals/hidden-features.th.html +109 -107
- package/docs/js/main.js +83 -3
- package/docs/loop.html +181 -180
- package/docs/loop.th.html +227 -226
- package/docs/mcp.html +247 -246
- package/docs/mcp.th.html +207 -206
- package/docs/models.html +111 -110
- package/docs/models.th.html +61 -60
- package/docs/peer.html +236 -235
- package/docs/peer.th.html +280 -279
- package/docs/permission-model.html +102 -101
- package/docs/permission-model.th.html +67 -66
- package/docs/plugins.html +102 -101
- package/docs/plugins.th.html +79 -78
- package/docs/providers.html +126 -117
- package/docs/providers.th.html +80 -78
- package/docs/quick-start.html +93 -92
- package/docs/quick-start.th.html +40 -39
- package/docs/research-memory.html +82 -79
- package/docs/research-memory.th.html +72 -71
- package/docs/skills.html +117 -116
- package/docs/skills.th.html +90 -89
- package/docs/tools.html +170 -169
- package/docs/tools.th.html +84 -83
- package/docs/troubleshooting.html +106 -105
- package/docs/troubleshooting.th.html +85 -84
- package/package.json +164 -162
- package/docs/taste.html +0 -436
- package/docs/taste.th.html +0 -236
|
@@ -0,0 +1,1125 @@
|
|
|
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>Clew Code — Architecture & Systems Documentation</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root {
|
|
9
|
+
--bg: #0d1117;
|
|
10
|
+
--bg-card: #161b22;
|
|
11
|
+
--bg-hover: #1c2333;
|
|
12
|
+
--border: #30363d;
|
|
13
|
+
--text: #e6edf3;
|
|
14
|
+
--text-dim: #8b949e;
|
|
15
|
+
--accent: #58a6ff;
|
|
16
|
+
--accent2: #3fb950;
|
|
17
|
+
--accent3: #d2a8ff;
|
|
18
|
+
--accent4: #f0883e;
|
|
19
|
+
--accent5: #ff7b72;
|
|
20
|
+
--accent6: #79c0ff;
|
|
21
|
+
--heading: #f0f6fc;
|
|
22
|
+
--code-bg: #1c2333;
|
|
23
|
+
--tag-bg: #1f6feb33;
|
|
24
|
+
--tag-text: #58a6ff;
|
|
25
|
+
--complexity-low: #3fb950;
|
|
26
|
+
--complexity-medium: #d29922;
|
|
27
|
+
--complexity-high: #f0883e;
|
|
28
|
+
--complexity-very-high: #ff7b72;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
32
|
+
|
|
33
|
+
body {
|
|
34
|
+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif;
|
|
35
|
+
background: var(--bg);
|
|
36
|
+
color: var(--text);
|
|
37
|
+
line-height: 1.6;
|
|
38
|
+
padding: 0;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
.hero {
|
|
42
|
+
background: linear-gradient(135deg, #0d1117 0%, #161b22 50%, #1c2333 100%);
|
|
43
|
+
border-bottom: 1px solid var(--border);
|
|
44
|
+
padding: 48px 24px 32px;
|
|
45
|
+
text-align: center;
|
|
46
|
+
}
|
|
47
|
+
.hero h1 {
|
|
48
|
+
font-size: 2.2rem;
|
|
49
|
+
color: var(--heading);
|
|
50
|
+
letter-spacing: -0.5px;
|
|
51
|
+
margin-bottom: 8px;
|
|
52
|
+
}
|
|
53
|
+
.hero h1 em { color: var(--accent); font-style: normal; }
|
|
54
|
+
.hero p {
|
|
55
|
+
color: var(--text-dim);
|
|
56
|
+
font-size: 1.05rem;
|
|
57
|
+
max-width: 600px;
|
|
58
|
+
margin: 0 auto 16px;
|
|
59
|
+
}
|
|
60
|
+
.hero .badge {
|
|
61
|
+
display: inline-block;
|
|
62
|
+
background: var(--tag-bg);
|
|
63
|
+
color: var(--tag-text);
|
|
64
|
+
padding: 4px 12px;
|
|
65
|
+
border-radius: 12px;
|
|
66
|
+
font-size: 0.85rem;
|
|
67
|
+
margin: 4px;
|
|
68
|
+
}
|
|
69
|
+
.hero .badge.orange { background: #f0883e33; color: var(--accent4); }
|
|
70
|
+
.hero .badge.green { background: #3fb95033; color: var(--accent2); }
|
|
71
|
+
|
|
72
|
+
.container { max-width: 1200px; margin: 0 auto; padding: 24px; }
|
|
73
|
+
|
|
74
|
+
.toc {
|
|
75
|
+
background: var(--bg-card);
|
|
76
|
+
border: 1px solid var(--border);
|
|
77
|
+
border-radius: 12px;
|
|
78
|
+
padding: 20px 24px;
|
|
79
|
+
margin-bottom: 32px;
|
|
80
|
+
}
|
|
81
|
+
.toc h2 { font-size: 1rem; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 1px; }
|
|
82
|
+
.toc-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 8px; }
|
|
83
|
+
.toc-item { display: flex; align-items: center; gap: 10px; padding: 6px 10px; border-radius: 6px; text-decoration: none; color: var(--text); font-size: 0.9rem; transition: background 0.15s; }
|
|
84
|
+
.toc-item:hover { background: var(--bg-hover); }
|
|
85
|
+
.toc-num { width: 24px; height: 24px; border-radius: 6px; display: flex; align-items: center; justify-content: center; font-size: 0.75rem; font-weight: 600; flex-shrink: 0; }
|
|
86
|
+
.toc-num.core { background: #58a6ff22; color: var(--accent); }
|
|
87
|
+
.toc-num.high { background: #f0883e22; color: var(--accent4); }
|
|
88
|
+
.toc-num.very-high { background: #ff7b7222; color: var(--accent5); }
|
|
89
|
+
.toc-num.medium { background: #3fb95022; color: var(--accent2); }
|
|
90
|
+
|
|
91
|
+
.system { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; margin-bottom: 24px; overflow: hidden; }
|
|
92
|
+
.system-header { padding: 20px 24px; display: flex; align-items: flex-start; gap: 16px; border-bottom: 1px solid var(--border); cursor: default; }
|
|
93
|
+
.system-header .num { width: 36px; height: 36px; border-radius: 8px; display: flex; align-items: center; justify-content: center; font-weight: 700; font-size: 1rem; flex-shrink: 0; }
|
|
94
|
+
.system-header .num.core { background: #58a6ff22; color: var(--accent); }
|
|
95
|
+
.system-header .num.high { background: #f0883e22; color: var(--accent4); }
|
|
96
|
+
.system-header .num.very-high { background: #ff7b7222; color: var(--accent5); }
|
|
97
|
+
.system-header .num.medium { background: #3fb95022; color: var(--accent2); }
|
|
98
|
+
.system-header .meta { flex: 1; }
|
|
99
|
+
.system-header .meta h2 { font-size: 1.25rem; color: var(--heading); margin-bottom: 4px; }
|
|
100
|
+
.system-header .meta h2 code { font-size: 0.85rem; color: var(--accent6); background: var(--code-bg); padding: 2px 6px; border-radius: 4px; }
|
|
101
|
+
.system-header .meta .sub { color: var(--text-dim); font-size: 0.9rem; display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
|
|
102
|
+
.complexity-tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.75rem; font-weight: 600; text-transform: uppercase; }
|
|
103
|
+
.complexity-tag.core { background: #3fb95022; color: var(--complexity-low); }
|
|
104
|
+
.complexity-tag.high { background: #d2992222; color: var(--complexity-medium); }
|
|
105
|
+
.complexity-tag.very-high { background: #f0883e22; color: var(--complexity-high); }
|
|
106
|
+
.complexity-tag.extreme { background: #ff7b7222; color: var(--complexity-very-high); }
|
|
107
|
+
.system-body { padding: 20px 24px; }
|
|
108
|
+
|
|
109
|
+
.sys-section { margin-bottom: 20px; }
|
|
110
|
+
.sys-section:last-child { margin-bottom: 0; }
|
|
111
|
+
.sys-section h3 { font-size: 0.95rem; color: var(--accent); margin-bottom: 8px; display: flex; align-items: center; gap: 6px; }
|
|
112
|
+
.sys-section h3::before { content: 'â–¸'; opacity: 0.6; }
|
|
113
|
+
.sys-section p, .sys-section li { font-size: 0.9rem; color: var(--text-dim); line-height: 1.7; }
|
|
114
|
+
.sys-section ul { padding-left: 20px; margin: 6px 0; }
|
|
115
|
+
.sys-section li { margin-bottom: 3px; }
|
|
116
|
+
.sys-section li strong { color: var(--text); }
|
|
117
|
+
|
|
118
|
+
pre { background: var(--code-bg); border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px; margin: 10px 0; overflow-x: auto; font-size: 0.82rem; font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace; line-height: 1.5; color: var(--text); }
|
|
119
|
+
pre .kw { color: #ff7b72; }
|
|
120
|
+
pre .str { color: #a5d6ff; }
|
|
121
|
+
pre .type { color: #ffa657; }
|
|
122
|
+
pre .comment { color: #8b949e; }
|
|
123
|
+
pre .fn { color: #d2a8ff; }
|
|
124
|
+
|
|
125
|
+
table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 0.88rem; }
|
|
126
|
+
th, td { border: 1px solid var(--border); padding: 8px 12px; text-align: left; }
|
|
127
|
+
th { background: var(--bg-hover); color: var(--text); font-weight: 600; font-size: 0.82rem; text-transform: uppercase; letter-spacing: 0.5px; }
|
|
128
|
+
td { color: var(--text-dim); }
|
|
129
|
+
td code { font-size: 0.82rem; background: var(--code-bg); padding: 1px 5px; border-radius: 3px; color: var(--accent6); }
|
|
130
|
+
|
|
131
|
+
.flow { background: var(--code-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px 20px; margin: 10px 0; font-family: 'JetBrains Mono', 'Consolas', monospace; font-size: 0.8rem; line-height: 1.8; white-space: pre; overflow-x: auto; color: var(--text); }
|
|
132
|
+
.flow .step { color: var(--accent6); }
|
|
133
|
+
.flow .arrow { color: var(--text-dim); }
|
|
134
|
+
.flow .label { color: var(--accent2); }
|
|
135
|
+
.flow .branch { color: var(--accent4); }
|
|
136
|
+
.flow .loop { color: var(--accent3); }
|
|
137
|
+
|
|
138
|
+
.kv { display: inline-flex; gap: 4px; align-items: center; }
|
|
139
|
+
.kv-key { color: var(--text-dim); font-size: 0.82rem; }
|
|
140
|
+
.kv-val { color: var(--accent6); font-size: 0.82rem; background: var(--code-bg); padding: 1px 5px; border-radius: 3px; }
|
|
141
|
+
|
|
142
|
+
.highlight { background: var(--bg-hover); border-left: 3px solid var(--accent); padding: 12px 16px; border-radius: 0 8px 8px 0; margin: 10px 0; font-size: 0.88rem; color: var(--text); }
|
|
143
|
+
.highlight.warn { border-left-color: var(--accent4); }
|
|
144
|
+
.highlight.good { border-left-color: var(--accent2); }
|
|
145
|
+
|
|
146
|
+
@media (max-width: 768px) {
|
|
147
|
+
.hero h1 { font-size: 1.6rem; }
|
|
148
|
+
.toc-grid { grid-template-columns: 1fr; }
|
|
149
|
+
.system-header { flex-direction: column; }
|
|
150
|
+
table { font-size: 0.8rem; }
|
|
151
|
+
th, td { padding: 6px 8px; }
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
.stats-bar { display: flex; flex-wrap: wrap; gap: 16px; justify-content: center; padding: 16px 24px; border-top: 1px solid var(--border); border-bottom: 1px solid var(--border); background: var(--bg-card); margin-bottom: 24px; }
|
|
155
|
+
.stat-item { text-align: center; }
|
|
156
|
+
.stat-num { font-size: 1.5rem; font-weight: 700; color: var(--accent); display: block; }
|
|
157
|
+
.stat-label { font-size: 0.78rem; color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.5px; }
|
|
158
|
+
|
|
159
|
+
.footer { text-align: center; padding: 32px 24px; color: var(--text-dim); font-size: 0.85rem; border-top: 1px solid var(--border); margin-top: 32px; }
|
|
160
|
+
</style>
|
|
161
|
+
</head>
|
|
162
|
+
<body>
|
|
163
|
+
|
|
164
|
+
<div class="hero">
|
|
165
|
+
<h1><em>Clew Code v0.2.7</em> — Complete Architecture</h1>
|
|
166
|
+
<p>18 interconnected systems powering a multi-provider AI coding agent CLI with terminal UI, P2P mesh, preference learning, and autonomous operation. Fork of Anthropic's Claude Code.</p>
|
|
167
|
+
<div>
|
|
168
|
+
<span class="badge">Bun + React 19 + Ink</span>
|
|
169
|
+
<span class="badge orange">32 AI Providers</span>
|
|
170
|
+
<span class="badge green">78 Tool Dirs</span>
|
|
171
|
+
<span class="badge">P2P LAN Mesh</span>
|
|
172
|
+
<span class="badge orange">MCP Client</span>
|
|
173
|
+
<span class="badge green">Autonomous Agent</span>
|
|
174
|
+
</div>
|
|
175
|
+
</div>
|
|
176
|
+
|
|
177
|
+
<div class="stats-bar">
|
|
178
|
+
<div class="stat-item"><span class="stat-num">18</span><span class="stat-label">Systems</span></div>
|
|
179
|
+
<div class="stat-item"><span class="stat-num">32</span><span class="stat-label">AI Providers</span></div>
|
|
180
|
+
<div class="stat-item"><span class="stat-num">78</span><span class="stat-label">Tool Dirs</span></div>
|
|
181
|
+
<div class="stat-item"><span class="stat-num">461</span><span class="stat-label">Components</span></div>
|
|
182
|
+
<div class="stat-item"><span class="stat-num">411</span><span class="stat-label">Command Files</span></div>
|
|
183
|
+
<div class="stat-item"><span class="stat-num">27</span><span class="stat-label">Hook Events</span></div>
|
|
184
|
+
<div class="stat-item"><span class="stat-num">6</span><span class="stat-label">Transports</span></div>
|
|
185
|
+
<div class="stat-item"><span class="stat-num">6475</span><span class="stat-label">main.tsx Lines</span></div>
|
|
186
|
+
</div>
|
|
187
|
+
|
|
188
|
+
<div class="container">
|
|
189
|
+
|
|
190
|
+
<div class="toc">
|
|
191
|
+
<h2>All 18 Systems</h2>
|
|
192
|
+
<div class="toc-grid">
|
|
193
|
+
<a href="#sys1" class="toc-item"><span class="toc-num core">1</span><span>Entry Point — 6475-line bootstrap</span></a>
|
|
194
|
+
<a href="#sys2" class="toc-item"><span class="toc-num high">2</span><span>AI Providers — 32 provider adapters</span></a>
|
|
195
|
+
<a href="#sys3" class="toc-item"><span class="toc-num high">3</span><span>Query Engine — 1219-line orchestrator</span></a>
|
|
196
|
+
<a href="#sys4" class="toc-item"><span class="toc-num very-high">4</span><span>Tool System — 78 tool dirs, 353 files</span></a>
|
|
197
|
+
<a href="#sys5" class="toc-item"><span class="toc-num high">5</span><span>Peer-to-Peer — UDP + file registry</span></a>
|
|
198
|
+
<a href="#sys6" class="toc-item"><span class="toc-num high">6</span><span>Taste — contextual bandit + neural scorer</span></a>
|
|
199
|
+
<a href="#sys7" class="toc-item"><span class="toc-num medium">7</span><span>Autonomous Agent — daemon + task queue</span></a>
|
|
200
|
+
<a href="#sys8" class="toc-item"><span class="toc-num very-high">8</span><span>MCP — 2207-line OAuth, 6 transports</span></a>
|
|
201
|
+
<a href="#sys9" class="toc-item"><span class="toc-num very-high">9</span><span>Bridge — 31 files, v1+v2, JWT</span></a>
|
|
202
|
+
<a href="#sys10" class="toc-item"><span class="toc-num medium">10</span><span>Plugins — hooks, marketplace, lifecycle</span></a>
|
|
203
|
+
<a href="#sys11" class="toc-item"><span class="toc-num medium">11</span><span>AppState — monolithic store (~80 fields)</span></a>
|
|
204
|
+
<a href="#sys12" class="toc-item"><span class="toc-num medium">12</span><span>Ink UI — custom React renderer, 97 files</span></a>
|
|
205
|
+
<a href="#sys13" class="toc-item"><span class="toc-num medium">13</span><span>Slash Commands — 120+ subdirectories</span></a>
|
|
206
|
+
<a href="#sys14" class="toc-item"><span class="toc-num medium">14</span><span>Cost & History — tracking + persistence</span></a>
|
|
207
|
+
<a href="#sys15" class="toc-item"><span class="toc-num medium">15</span><span>Context & Permissions — 195 lines</span></a>
|
|
208
|
+
<a href="#sys16" class="toc-item"><span class="toc-num medium">16</span><span>Voice — gateway + auth checks</span></a>
|
|
209
|
+
<a href="#sys17" class="toc-item"><span class="toc-num medium">17</span><span>Memory — SQLite FTS5, 14 files</span></a>
|
|
210
|
+
<a href="#sys18" class="toc-item"><span class="toc-num medium">18</span><span>Architecture Flow — full system map</span></a>
|
|
211
|
+
</div>
|
|
212
|
+
</div>
|
|
213
|
+
|
|
214
|
+
<!-- ============================================================ -->
|
|
215
|
+
<!-- SYSTEM 1 -->
|
|
216
|
+
<!-- ============================================================ -->
|
|
217
|
+
<div class="system" id="sys1">
|
|
218
|
+
<div class="system-header">
|
|
219
|
+
<span class="num core">1</span>
|
|
220
|
+
<div class="meta">
|
|
221
|
+
<h2>Entry Point <code>main.tsx (6475 lin)</code></h2>
|
|
222
|
+
<div class="sub">
|
|
223
|
+
<span class="complexity-tag core">Core</span>
|
|
224
|
+
<span>Bootstrap • CLI • Lifecycle</span>
|
|
225
|
+
<span><span class="kv"><span class="kv-key">Key files:</span><span class="kv-val">main.tsx</span><span class="kv-val">setup.ts (423)</span><span class="kv-val">commands.ts (740)</span></span></span>
|
|
226
|
+
</div>
|
|
227
|
+
</div>
|
|
228
|
+
</div>
|
|
229
|
+
<div class="system-body">
|
|
230
|
+
|
|
231
|
+
<div class="sys-section">
|
|
232
|
+
<h3>Startup Sequence (5 Phases)</h3>
|
|
233
|
+
<div class="flow"><span class="step">Phase 0</span> <span class="arrow">→</span> Pre-import: TTY force, version check, MDM raw read, keychain prefetch, MACRO injection
|
|
234
|
+
<span class="step">Phase 1</span> <span class="arrow">→</span> Module evaluation (~135ms imports resolve)
|
|
235
|
+
<span class="step">Phase 2</span> <span class="arrow">→</span> main() + run(): PATH security, signal handlers (SIGINT/SIGCONT/SIGTSTP), argv preprocess (`--`, `cc://` URLs, SSH), mode detection, Commander setup
|
|
236
|
+
<span class="step">Phase 3</span> <span class="arrow">→</span> preAction hook: MDM + keychain await, <span class="label">init()</span> (memoized), taste init, sinks, plugin dir, migrations, remote managed settings, policy limits
|
|
237
|
+
<span class="step">Phase 4</span> <span class="arrow">→</span> Action handler: prompt parse, peer auto-start, MCP config, system prompt assembly, agent selection, model resolution
|
|
238
|
+
<span class="step">Phase 5</span> <span class="arrow">→</span> Interactive REPL (Ink-based TUI) or headless --print path</div>
|
|
239
|
+
</div>
|
|
240
|
+
|
|
241
|
+
<div class="sys-section">
|
|
242
|
+
<h3>CLI Argument Parsing</h3>
|
|
243
|
+
<p>Uses <strong>Commander.js</strong> with ~70+ options. Custom sorted help config. <strong><code>run()</code></strong> creates the program with <code>preAction</code> hook for init and <code>.action()</code> for main dispatch. Mode detection branches interactive vs headless vs init-only.</p>
|
|
244
|
+
</div>
|
|
245
|
+
|
|
246
|
+
<div class="sys-section">
|
|
247
|
+
<h3>Command Dispatching</h3>
|
|
248
|
+
<p><strong><code>COMMANDS</code></strong> — memoized lazy loader returning 150+ built-in commands. <strong><code>getCommands(cwd)</code></strong> merges bundled skills, built-in plugin skills, skill directory commands, workflow commands, plugin commands, plugin skills, and core COMMANDS(). Resolution: exact match → prefix match → colon-separated fallback.</p>
|
|
249
|
+
</div>
|
|
250
|
+
|
|
251
|
+
<div class="sys-section">
|
|
252
|
+
<h3>Key Init Steps (<code>setup.ts</code>, 423 lines)</h3>
|
|
253
|
+
<ul>
|
|
254
|
+
<li>Node version check (≥ 18), custom session ID, UDS messaging</li>
|
|
255
|
+
<li><strong>FileChanged watcher</strong> — <code>initializeFileChangedWatcher(cwd)</code></li>
|
|
256
|
+
<li><strong>Worktree</strong> — git worktree + tmux session if <code>--worktree</code></li>
|
|
257
|
+
<li><strong>Session memory</strong> — <code>initSessionMemory()</code>, context collapse (gated)</li>
|
|
258
|
+
<li><strong>Plugin prefetch</strong> — <code>getCommands()</code> + <code>loadPluginHooks()</code> as void promises</li>
|
|
259
|
+
<li><strong>Teammate snapshot</strong> — captures agent swarm configuration</li>
|
|
260
|
+
<li><strong>Bootstrap state</strong> — global <code>STATE</code> singleton with ~100+ accessor functions exported</li>
|
|
261
|
+
</ul>
|
|
262
|
+
</div>
|
|
263
|
+
|
|
264
|
+
</div>
|
|
265
|
+
</div>
|
|
266
|
+
|
|
267
|
+
<!-- ============================================================ -->
|
|
268
|
+
<!-- SYSTEM 2 -->
|
|
269
|
+
<!-- ============================================================ -->
|
|
270
|
+
<div class="system" id="sys2">
|
|
271
|
+
<div class="system-header">
|
|
272
|
+
<span class="num high">2</span>
|
|
273
|
+
<div class="meta">
|
|
274
|
+
<h2>AI Providers <code>32 providers · 9 dedicated + 23 compatible</code></h2>
|
|
275
|
+
<div class="sub">
|
|
276
|
+
<span class="complexity-tag high">High</span>
|
|
277
|
+
<span>ProviderManager singleton • 10 provider files • 2197-line providers.json</span>
|
|
278
|
+
</div>
|
|
279
|
+
</div>
|
|
280
|
+
</div>
|
|
281
|
+
<div class="system-body">
|
|
282
|
+
|
|
283
|
+
<div class="sys-section">
|
|
284
|
+
<h3>Provider Categories</h3>
|
|
285
|
+
<table>
|
|
286
|
+
<tr><th>Type</th><th>Count</th><th>Providers</th></tr>
|
|
287
|
+
<tr><td><strong>Dedicated Provider classes</strong></td><td>10</td><td><code>AnthropicProvider</code>, <code>OpenAIProvider</code>, <code>GoogleProvider</code>, <code>CohereProvider</code>, <code>OpenRouterProvider</code>, <code>KiloCodeProvider</code>, <code>OllamaProvider</code>, <code>ClewGatewayProvider</code>, <code>OpenAICompatibleProvider</code>, <code>ProviderInterface</code></td></tr>
|
|
288
|
+
<tr><td><strong>OpenAI-compatible (driven by providers.json)</strong></td><td>23</td><td><code>deepseek</code>, <code>opencode</code>, <code>opencode-go</code>, <code>groq</code>, <code>xai</code>, <code>mistral</code>, <code>together</code>, <code>fireworks</code>, <code>nvidia</code>, <code>deepinfra</code>, <code>perplexity</code>, <code>cerebras</code>, <code>siliconflow</code>, <code>moonshot</code>, <code>zhipu</code>, <code>huggingface</code>, <code>poe</code>, <code>digitalocean</code>, <code>cline</code>, and <code>custom</code></td></tr>
|
|
289
|
+
</table>
|
|
290
|
+
</div>
|
|
291
|
+
|
|
292
|
+
<div class="sys-section">
|
|
293
|
+
<h3>ProviderManager Singleton (369 lines)</h3>
|
|
294
|
+
<p><strong>Selection priority chain</strong> (<code>getActiveProviderName</code>):</p>
|
|
295
|
+
<div class="flow">Session override <span class="arrow">→</span> AI_PROVIDER env <span class="arrow">→</span> provider.json (persisted) <span class="arrow">→</span> Legacy env vars (BEDROCK/VERTEX/FOUNDRY) <span class="arrow">→</span> 'openai' (fallback)</div>
|
|
296
|
+
<p><strong>Config persistence:</strong> User-level <code>~/.claude/provider.json</code>, project-level <code>.claude/provider.json</code> (takes priority). Auth resolved via <code>getApiKeyForProvider()</code> — checks session keys → OAuth tokens → persisted config → environment variables.</p>
|
|
297
|
+
</div>
|
|
298
|
+
|
|
299
|
+
<div class="sys-section">
|
|
300
|
+
<h3>Common Interface</h3>
|
|
301
|
+
<pre><span class="kw">interface</span> ProviderInterface {
|
|
302
|
+
readonly providerId: ProviderId;
|
|
303
|
+
readonly label: <span class="type">string</span>;
|
|
304
|
+
getProviderId(): ProviderId;
|
|
305
|
+
getProviderLabel(): <span class="type">string</span>;
|
|
306
|
+
getProviderApiKeyEnvVar(): <span class="type">string</span>;
|
|
307
|
+
createClient(options: ProviderInitOptions): <span class="kw">Promise</span><ProviderClient>;
|
|
308
|
+
listModels(options: ProviderInitOptions): <span class="kw">Promise</span><{ id: <span class="type">string</span>; label: <span class="type">string</span> }[]>;
|
|
309
|
+
}</pre>
|
|
310
|
+
</div>
|
|
311
|
+
|
|
312
|
+
<div class="sys-section">
|
|
313
|
+
<h3>Streaming — Two-Layer Architecture</h3>
|
|
314
|
+
<p><strong>Layer 1 — Provider SDK:</strong> <code>chat.completions.create({ stream: true })</code> returns SSE <code>AsyncGenerator</code>.</p>
|
|
315
|
+
<p><strong>Layer 2 — AnthropicAdapter:</strong> Wraps any provider into Anthropic-compatible <code>BetaRawMessageStreamEvent</code> types via <code>wrapStream()</code>. Converts OpenAI delta chunks → Anthropic events (<code>message_start</code>, <code>content_block_start</code>, <code>content_block_delta</code>, etc.). Supports <code>thinking</code>/<code>reasoning_content</code> blocks.</p>
|
|
316
|
+
<p><strong>Stream watchdog:</strong> 45s (OpenAI-compatible), 60s (Google), 30s (default). Throws stall error if no chunk arrives.</p>
|
|
317
|
+
</div>
|
|
318
|
+
|
|
319
|
+
<div class="sys-section">
|
|
320
|
+
<h3>Additional Services</h3>
|
|
321
|
+
<p>The <code>src/services/ai/</code> module also includes: <code>ModelDiscoveryService</code>, <code>BrowserAgent</code>, <code>contentBlockUtils</code>, <code>errorNormalizer</code>, <code>providerMetadata</code>, <code>providerModels</code>, <code>toolCallParser</code>, <code>usageNormalizer</code>, <code>usageTypes</code> (130 lines).</p>
|
|
322
|
+
</div>
|
|
323
|
+
|
|
324
|
+
</div>
|
|
325
|
+
</div>
|
|
326
|
+
|
|
327
|
+
<!-- ============================================================ -->
|
|
328
|
+
<!-- SYSTEM 3 -->
|
|
329
|
+
<!-- ============================================================ -->
|
|
330
|
+
<div class="system" id="sys3">
|
|
331
|
+
<div class="system-header">
|
|
332
|
+
<span class="num high">3</span>
|
|
333
|
+
<div class="meta">
|
|
334
|
+
<h2>Query Engine <code>QueryEngine.ts (1219) · query.ts (1623)</code></h2>
|
|
335
|
+
<div class="sub">
|
|
336
|
+
<span class="complexity-tag high">High</span>
|
|
337
|
+
<span>Conversation orchestrator • Core 10-step AI loop • Dependency injection</span>
|
|
338
|
+
</div>
|
|
339
|
+
</div>
|
|
340
|
+
</div>
|
|
341
|
+
<div class="system-body">
|
|
342
|
+
|
|
343
|
+
<div class="sys-section">
|
|
344
|
+
<h3>QueryEngine (1219 lines)</h3>
|
|
345
|
+
<p>One instance per conversation. Manages <code>mutableMessages</code>, <code>abortController</code>, <code>totalUsage</code>, <code>readFileState</code> (file cache), <code>discoveredSkillNames</code>, <code>loadedNestedMemoryPaths</code>.</p>
|
|
346
|
+
<p><strong>Key method:</strong> <code>submitMessage()</code> — AsyncGenerator that orchestrates user input → system init → AI loop → post-processing → result.</p>
|
|
347
|
+
</div>
|
|
348
|
+
|
|
349
|
+
<div class="sys-section">
|
|
350
|
+
<h3>Core AI Loop (<code>query() → queryLoop()</code>)</h3>
|
|
351
|
+
<div class="flow"><span class="step">1. Snip compact</span> <span class="arrow">→</span> Remove zombie messages, GC stale markers
|
|
352
|
+
<span class="step">2. Microcompact</span> <span class="arrow">→</span> Compress individual tool results
|
|
353
|
+
<span class="step">3. Context collapse</span> <span class="arrow">→</span> Read-time projection (gated)
|
|
354
|
+
<span class="step">4. Auto-compact</span> <span class="arrow">→</span> Summarize old context when token budget tight
|
|
355
|
+
<span class="step">5. API call</span> <span class="arrow">→</span> Streaming model request with fallback
|
|
356
|
+
<span class="step">6. Tool execution</span> <span class="arrow">→</span> runTools() or StreamingToolExecutor
|
|
357
|
+
<span class="step">7. Post-sampling hooks</span>
|
|
358
|
+
<span class="step">8. Stop hooks</span> <span class="arrow">→</span> Goal evaluator, memory extraction, job classification
|
|
359
|
+
<span class="step">9. Token budget check</span> <span class="arrow">→</span> Auto-continue if within budget
|
|
360
|
+
<span class="step">10. Max turns / goal check</span> <span class="arrow">→</span> Continue loop or return completed</div>
|
|
361
|
+
</div>
|
|
362
|
+
|
|
363
|
+
<div class="sys-section">
|
|
364
|
+
<h3>System Prompt Construction</h3>
|
|
365
|
+
<ol>
|
|
366
|
+
<li><code>fetchSystemPromptParts()</code> — default + user context + system context (tools, model, MCP clients, working dirs)</li>
|
|
367
|
+
<li>Custom system prompt (SDK-provided) replaces default if present</li>
|
|
368
|
+
<li><strong>Memory mechanics prompt</strong> — when <code>CLAUDE_COWORK_MEMORY_PATH_OVERRIDE</code> is set</li>
|
|
369
|
+
<li><strong>Taste/Rules injection</strong> — <code>getTasteInjectionBlock()</code> + evaluated rules with confidence ≥ 55%</li>
|
|
370
|
+
<li><code>appendSystemPrompt</code> — additional prompt appended</li>
|
|
371
|
+
</ol>
|
|
372
|
+
</div>
|
|
373
|
+
|
|
374
|
+
<div class="sys-section">
|
|
375
|
+
<h3>Loop Continuation Signals</h3>
|
|
376
|
+
<p><code>State.transition</code> controls loop iteration: <code>max_output_tokens_escalate</code>, <code>max_output_tokens_recovery</code>, <code>reactive_compact_retry</code>, <code>collapse_drain_retry</code>, <code>stop_hook_blocking</code>, <code>goal_continuation</code>, <code>token_budget_continuation</code>, <code>brief_mode_retry</code>, <code>completed</code>.</p>
|
|
377
|
+
</div>
|
|
378
|
+
|
|
379
|
+
<div class="sys-section">
|
|
380
|
+
<h3>Key Features</h3>
|
|
381
|
+
<ul>
|
|
382
|
+
<li><strong>Dependency injection</strong> via <code>QueryDeps</code> — tests can inject fakes for <code>callModel</code>, <code>microcompact</code>, <code>autocompact</code></li>
|
|
383
|
+
<li><strong>Streaming tool execution</strong> — gated by Statsig flag, tools execute concurrently while model streams</li>
|
|
384
|
+
<li><strong>Ultracode bridge</strong> — <code>tryAutoRunDynamicWorkflow()</code> classifies task complexity, spawns parallel coordinator workflows</li>
|
|
385
|
+
<li><strong>Query config</strong> (<code>query/config.ts</code>) — snapshots immutable values at query entry</li>
|
|
386
|
+
</ul>
|
|
387
|
+
</div>
|
|
388
|
+
|
|
389
|
+
</div>
|
|
390
|
+
</div>
|
|
391
|
+
|
|
392
|
+
<!-- ============================================================ -->
|
|
393
|
+
<!-- SYSTEM 4 -->
|
|
394
|
+
<!-- ============================================================ -->
|
|
395
|
+
<div class="system" id="sys4">
|
|
396
|
+
<div class="system-header">
|
|
397
|
+
<span class="num very-high">4</span>
|
|
398
|
+
<div class="meta">
|
|
399
|
+
<h2>Tool System <code>78 dirs · 353 files · Tool.ts (782 lin)</code></h2>
|
|
400
|
+
<div class="sub">
|
|
401
|
+
<span class="complexity-tag extreme">Very High</span>
|
|
402
|
+
<span>Structural type system • 17 categories • Permission framework • Execution pipeline</span>
|
|
403
|
+
</div>
|
|
404
|
+
</div>
|
|
405
|
+
</div>
|
|
406
|
+
<div class="system-body">
|
|
407
|
+
|
|
408
|
+
<div class="sys-section">
|
|
409
|
+
<h3>Base Tool Type</h3>
|
|
410
|
+
<p>Structural type (<code>Tool<Input, Output, P></code>), not a class. Created via <code>buildTool(def)</code> which fills safe defaults. ~30+ lifecycle/UI/safety methods per tool.</p>
|
|
411
|
+
</div>
|
|
412
|
+
|
|
413
|
+
<div class="sys-section">
|
|
414
|
+
<h3>Tool Categories</h3>
|
|
415
|
+
<table>
|
|
416
|
+
<tr><th>Category</th><th>Tools</th></tr>
|
|
417
|
+
<tr><td><strong>Filesystem</strong></td><td><code>FileRead</code>, <code>FileEdit</code>, <code>FileWrite</code>, <code>Glob</code>, <code>Grep</code>, <code>NotebookEdit</code></td></tr>
|
|
418
|
+
<tr><td><strong>Execution</strong></td><td><code>Bash</code>, <code>PowerShell</code>, <code>REPL</code>, <code>ComputerUse</code></td></tr>
|
|
419
|
+
<tr><td><strong>Web</strong></td><td><code>WebSearch</code>, <code>WebFetch</code>, <code>MultiSearch</code>, <code>Browser</code>, <code>BrowserAgent</code></td></tr>
|
|
420
|
+
<tr><td><strong>Planning/Mode</strong></td><td><code>EnterPlanMode</code>, <code>ExitPlanMode</code>, <code>EnterWorktree</code>, <code>ExitWorktree</code>, <code>Brief</code></td></tr>
|
|
421
|
+
<tr><td><strong>Peer Collaboration (17)</strong></td><td><code>PeerDiscover</code>, <code>PeerSendMessage</code>, <code>PeerSpawn</code>, <code>PeerShare</code>, <code>PeerInfo</code>, <code>PeerRun</code>, <code>PeerJoin</code>, <code>PeerSetName</code>, <code>PeerSetRole</code>, <code>PeerListRoles</code>, <code>PeerPing</code>, <code>PeerDisconnect</code>, <code>PeerBroadcast</code>, <code>PeerListMessages</code>, <code>PeerHelp</code>, <code>ProcessPeer</code>, <code>ListPeers</code></td></tr>
|
|
422
|
+
<tr><td><strong>MCP</strong></td><td><code>MCPTool</code>, <code>McpAuthTool</code>, <code>ListMcpResourcesTool</code>, <code>ReadMcpResourceTool</code></td></tr>
|
|
423
|
+
<tr><td><strong>Task Management</strong></td><td><code>TaskCreate</code>, <code>TaskGet</code>, <code>TaskUpdate</code>, <code>TaskList</code>, <code>TaskOutput</code>, <code>TaskStop</code></td></tr>
|
|
424
|
+
<tr><td><strong>Skill & Taste</strong></td><td><code>Skill</code>, <code>TasteLearn</code>, <code>TasteForget</code>, <code>TasteProfile</code>, <code>TasteSuggest</code></td></tr>
|
|
425
|
+
<tr><td><strong>Code/Dev</strong></td><td><code>LSP</code>, <code>PR</code>, <code>PrSubscription</code>, <code>JsonPath</code>, <code>Tungsten</code>, <code>Research</code></td></tr>
|
|
426
|
+
<tr><td><strong>Team</strong></td><td><code>TeamCreate</code>, <code>TeamDelete</code></td></tr>
|
|
427
|
+
<tr><td><strong>Automation (10)</strong></td><td><code>ScheduleCron</code>, <code>Sleep</code>, <code>RemoteTrigger</code>, <code>Workflow</code>, <code>Monitor</code>, <code>PushNotification</code>, <code>SubscribePR</code>, <code>SuggestBackgroundPR</code>, <code>VerifyPlanExecution</code>, <code>SendUserFile</code></td></tr>
|
|
428
|
+
<tr><td><strong>Meta/Search</strong></td><td><code>ToolSearch</code>, <code>SessionSearch</code>, <code>TodoWrite</code>, <code>SyntheticOutput</code></td></tr>
|
|
429
|
+
<tr><td><strong>Communication</strong></td><td><code>SendMessage</code>, <code>AskUserQuestion</code>, <code>Config</code>, <code>RequestShutdown</code></td></tr>
|
|
430
|
+
<tr><td><strong>Agent</strong></td><td><code>AgentTool</code></td></tr>
|
|
431
|
+
</table>
|
|
432
|
+
</div>
|
|
433
|
+
|
|
434
|
+
<div class="sys-section">
|
|
435
|
+
<h3>Tool Execution Pipeline</h3>
|
|
436
|
+
<div class="flow">LLM returns tool_use block
|
|
437
|
+
<span class="arrow">→</span> <span class="step">[1]</span> Parse via Zod schema
|
|
438
|
+
<span class="arrow">→</span> <span class="step">[2]</span> Validate via tool.validateInput?.()
|
|
439
|
+
<span class="arrow">→</span> <span class="step">[3]</span> Run PreToolUse hooks
|
|
440
|
+
<span class="arrow">→</span> <span class="step">[4]</span> Check permissions (classifier + rules + prompts)
|
|
441
|
+
<span class="arrow">→</span> <span class="step">[5]</span> Call tool.call() with ToolUseContext (~30+ fields)
|
|
442
|
+
<span class="arrow">→</span> <span class="step">[6]</span> Run PostToolUse hooks
|
|
443
|
+
<span class="arrow">→</span> <span class="step">[7]</span> Map result to API format
|
|
444
|
+
<span class="arrow">→</span> <span class="step">[8]</span> Return MessageUpdateLazy</div>
|
|
445
|
+
</div>
|
|
446
|
+
|
|
447
|
+
<div class="sys-section">
|
|
448
|
+
<h3>Registration (<code>tools.ts</code>)</h3>
|
|
449
|
+
<p>Core tools statically imported. Feature-gated tools (<code>REPLTool</code>, <code>ComputerUseTool</code>, <code>LSPTool</code>, worktree, team, PowerShell, <code>ToolSearchTool</code>) lazy-loaded via helper getters.</p>
|
|
450
|
+
<p>Pipeline: <code>getAllBaseTools()</code> → <code>getTools(permissionContext)</code> (filter by SIMPLE mode, isEnabled, deny rules) → <code>assembleToolPool(permCtx, mcpTools)</code> (merge + dedup).</p>
|
|
451
|
+
</div>
|
|
452
|
+
|
|
453
|
+
</div>
|
|
454
|
+
</div>
|
|
455
|
+
|
|
456
|
+
<!-- ============================================================ -->
|
|
457
|
+
<!-- SYSTEM 5 -->
|
|
458
|
+
<!-- ============================================================ -->
|
|
459
|
+
<div class="system" id="sys5">
|
|
460
|
+
<div class="system-header">
|
|
461
|
+
<span class="num high">5</span>
|
|
462
|
+
<div class="meta">
|
|
463
|
+
<h2>Peer-to-Peer <code>6 files · UDP multicast + file registry</code></h2>
|
|
464
|
+
<div class="sub">
|
|
465
|
+
<span class="complexity-tag high">High</span>
|
|
466
|
+
<span>PeerServer • PeerDiscovery • PeerStore • ProcessPeerProvider • 17 peer tools</span>
|
|
467
|
+
</div>
|
|
468
|
+
</div>
|
|
469
|
+
</div>
|
|
470
|
+
<div class="system-body">
|
|
471
|
+
|
|
472
|
+
<div class="sys-section">
|
|
473
|
+
<h3>4 Core Modules</h3>
|
|
474
|
+
<table>
|
|
475
|
+
<tr><th>Module</th><th>Role</th></tr>
|
|
476
|
+
<tr><td><strong>PeerServer</strong></td><td>Lightweight HTTP server on 127.0.0.1 (random OS port). Endpoints: <code>GET /peer-info</code>, <code>GET /peer-events</code> (SSE), <code>POST /peer-msg</code>, <code>POST /peer-todo</code>, <code>POST /peer-exec</code>, WebSocket upgrade <code>/peer-chat</code> (currently destroyed)</td></tr>
|
|
477
|
+
<tr><td><strong>PeerDiscovery</strong></td><td>Two-layer: file registry (<code>~/.claude/peers/{pid}.json</code>, 30s heartbeat, 90s stale timeout) + UDP multicast (<code>239.255.37.37:42069</code>, currently disabled for localhost safety)</td></tr>
|
|
478
|
+
<tr><td><strong>PeerStore</strong></td><td>In-memory peer registry with auto-eviction, message queuing (chunked reassembly), liveness pings (60s interval)</td></tr>
|
|
479
|
+
<tr><td><strong>ProcessPeerProvider</strong></td><td>Runs AI tasks as subprocesses — exec mode (spawn with stdin) or PTY mode (node-pty for interactive). Default command: <code>codex</code></td></tr>
|
|
480
|
+
</table>
|
|
481
|
+
</div>
|
|
482
|
+
|
|
483
|
+
<div class="sys-section">
|
|
484
|
+
<h3>Peer Tools (17)</h3>
|
|
485
|
+
<p><code>PeerDiscover</code>, <code>PeerSendMessage</code>, <code>PeerSpawn</code>, <code>PeerShare</code>, <code>PeerInfo</code>, <code>PeerRun</code>, <code>PeerJoin</code>, <code>PeerSetName</code>, <code>PeerSetRole</code>, <code>PeerListRoles</code>, <code>PeerPing</code>, <code>PeerDisconnect</code>, <code>PeerBroadcast</code>, <code>PeerListMessages</code>, <code>PeerHelp</code>, <code>ProcessPeer</code>, <code>ListPeers</code>.</p>
|
|
486
|
+
</div>
|
|
487
|
+
|
|
488
|
+
<div class="sys-section">
|
|
489
|
+
<h3>Connection Lifecycle</h3>
|
|
490
|
+
<div class="flow">DISCOVERED <span class="arrow">→</span> File registry or UDP beacon detected
|
|
491
|
+
JOINED <span class="arrow">→</span> Explicit connection, liveness pings every 60s (5s timeout)
|
|
492
|
+
ACTIVE <span class="arrow">→</span> Messages + todos + exec via HTTP, SSE for real-time push
|
|
493
|
+
OFFLINE <span class="arrow">→</span> No heartbeat >90s or HTTP ping fails
|
|
494
|
+
DESTROY <span class="arrow">→</span> stopAdvertising() removes file, clears timers</div>
|
|
495
|
+
</div>
|
|
496
|
+
|
|
497
|
+
</div>
|
|
498
|
+
</div>
|
|
499
|
+
|
|
500
|
+
<!-- ============================================================ -->
|
|
501
|
+
<!-- SYSTEM 6 -->
|
|
502
|
+
<!-- ============================================================ -->
|
|
503
|
+
<div class="system" id="sys6">
|
|
504
|
+
<div class="system-header">
|
|
505
|
+
<span class="num high">6</span>
|
|
506
|
+
<div class="meta">
|
|
507
|
+
<h2>Taste (Preferences) <code>8 core files · 5 subdirs</code></h2>
|
|
508
|
+
<div class="sub">
|
|
509
|
+
<span class="complexity-tag high">High</span>
|
|
510
|
+
<span>Epsilon-greedy bandit • Lexical neural scorer • Half-life decay • 3-tiers</span>
|
|
511
|
+
</div>
|
|
512
|
+
</div>
|
|
513
|
+
</div>
|
|
514
|
+
<div class="system-body">
|
|
515
|
+
|
|
516
|
+
<div class="sys-section">
|
|
517
|
+
<h3>System Layout</h3>
|
|
518
|
+
<p><code>src/services/taste/</code> — <code>TasteIntegration.ts</code> + 7 subdirectories:</p>
|
|
519
|
+
<table>
|
|
520
|
+
<tr><th>Subdir</th><th>Files</th><th>Contents</th></tr>
|
|
521
|
+
<tr><td><code>core/</code></td><td>9</td><td><code>TasteBandit</code>, <code>TasteDecay</code>, <code>TasteMemory</code>, <code>TasteNeuralScorer</code>, <code>TastePolicy</code>, <code>TasteRewardModel</code>, <code>TasteRuntime</code>, <code>TasteSymbolicEngine</code>, <code>TasteTypes</code></td></tr>
|
|
522
|
+
<tr><td><code>auto-learn/</code></td><td>4</td><td><code>AutoLearnEngine</code>, <code>PatternDetector</code>, <code>TasteCodebaseAnalyzer</code></td></tr>
|
|
523
|
+
<tr><td><code>signals/</code></td><td>4</td><td><code>AcceptRejectTracker</code>, <code>DiffSignalExtractor</code>, <code>EditDistanceReward</code>, <code>TasteSignalCollector</code></td></tr>
|
|
524
|
+
<tr><td><code>prompt/</code></td><td>2</td><td><code>TasteConstraintCompiler</code>, <code>TastePromptInjector</code></td></tr>
|
|
525
|
+
<tr><td><code>storage/</code></td><td>—</td><td>Profile store, event log</td></tr>
|
|
526
|
+
<tr><td><code>eval/</code></td><td>—</td><td>Evaluation utilities</td></tr>
|
|
527
|
+
</table>
|
|
528
|
+
</div>
|
|
529
|
+
|
|
530
|
+
<div class="sys-section">
|
|
531
|
+
<h3>Epsilon-Greedy Bandit</h3>
|
|
532
|
+
<p><strong>6 arms:</strong> <code>minimal</code>, <code>strict_style</code>, <code>architecture_first</code>, <code>test_first</code>, <code>safety_first</code>, <code>refactor_heavy</code>. Exploit (80%): pick highest <code>averageReward</code>. Explore (ε=0.2): pick random arm weighted by inverse pulls. Epsilon decays by 0.99×/update, floor 0.05. Supports future <code>BanditContext</code> extension (file ext, command type, model provider).</p>
|
|
533
|
+
</div>
|
|
534
|
+
|
|
535
|
+
<div class="sys-section">
|
|
536
|
+
<h3>Neural Scorer</h3>
|
|
537
|
+
<p>Provider-agnostic — uses <strong>Jaccard similarity + TF-IDF tokenization</strong>. Tokenization: strip punctuation, lowercase, remove 100+ stop words, filter <2 chars. Scoring: <code>Jaccard|tokens∩|/|tokens∪| + tag bonus (0.05/tag)</code>. Combined: <code>finalScore = (avgSimilarity × 0.5) + (outputScore × 0.5)</code>.</p>
|
|
538
|
+
</div>
|
|
539
|
+
|
|
540
|
+
<div class="sys-section">
|
|
541
|
+
<h3>Tiers & Persistence</h3>
|
|
542
|
+
<p><strong>Project</strong> (<code>{cwd}/.clew/taste/profile.json</code>), <strong>Global</strong> (<code>~/.clew/taste/profile.json</code>), <strong>Session</strong> (RAM ring buffer: 200 events, 100 rules). Load order: Project → Global → new project-level created.</p>
|
|
543
|
+
<p><strong>Auto-Learn:</strong> <code>PatternDetector</code> — min 5 events, min 3 occurrences to suggest, auto-accept at confidence ≥ 0.7, 30-min cooldown. <strong>Decay:</strong> half-life 30 days, <code>decayedExcess = excess × 0.5^(daysSinceUse/30)</code>, floor at 0.5.</p>
|
|
544
|
+
</div>
|
|
545
|
+
|
|
546
|
+
<div class="sys-section">
|
|
547
|
+
<h3>Model Influence</h3>
|
|
548
|
+
<ol>
|
|
549
|
+
<li><strong>Prompt injection:</strong> <code><clew_taste></code> block (max 8 rules, min confidence 0.55)</li>
|
|
550
|
+
<li><strong>Edit validation:</strong> <code>TastePolicy.evaluate()</code> — symbolic + neural scorer, scores ≥ 0.85 can block edits</li>
|
|
551
|
+
<li><strong>Bandit strategy:</strong> Selected arm queries via <code>getCurrentArm()</code></li>
|
|
552
|
+
</ol>
|
|
553
|
+
</div>
|
|
554
|
+
|
|
555
|
+
</div>
|
|
556
|
+
</div>
|
|
557
|
+
|
|
558
|
+
<!-- ============================================================ -->
|
|
559
|
+
<!-- SYSTEM 7 -->
|
|
560
|
+
<!-- ============================================================ -->
|
|
561
|
+
<div class="system" id="sys7">
|
|
562
|
+
<div class="system-header">
|
|
563
|
+
<span class="num medium">7</span>
|
|
564
|
+
<div class="meta">
|
|
565
|
+
<h2>Autonomous Agent <code>8 files · daemon · supervisor IPC</code></h2>
|
|
566
|
+
<div class="sub">
|
|
567
|
+
<span class="complexity-tag high">Medium</span>
|
|
568
|
+
<span>24/7 agent loop • File-backed task queue • Cron scheduler • 17 agentRuntime files</span>
|
|
569
|
+
</div>
|
|
570
|
+
</div>
|
|
571
|
+
</div>
|
|
572
|
+
<div class="system-body">
|
|
573
|
+
|
|
574
|
+
<div class="sys-section">
|
|
575
|
+
<h3>Core Files</h3>
|
|
576
|
+
<p><strong>Services:</strong> <code>agentLoop.ts</code>, <code>daemonMode.ts</code>, <code>supervisorIntegration.ts</code>, <code>taskQueue.ts</code>. <strong>Supervisor:</strong> <code>supervisor.ts</code>, <code>ipcClient.ts</code>. <strong>Agent Runtime:</strong> 17 files at <code>src/agentRuntime/</code> — including <code>ultracode.ts</code>, <code>ultracodeBridge.ts</code>, <code>orchestrator.ts</code>, <code>dynamicWorkflow.ts</code>, <code>transcriptClassifier.ts</code>, <code>verifierAgent.ts</code>, <code>workflowRegistry.ts</code>, <code>toolGateway.ts</code>.</p>
|
|
577
|
+
</div>
|
|
578
|
+
|
|
579
|
+
<div class="sys-section">
|
|
580
|
+
<h3>Agent Loop</h3>
|
|
581
|
+
<div class="flow">startLoop() <span class="arrow">→</span> Load queue → Expire stale leases → Start heartbeat (60s) → Cron scheduler → Peer sharing → File watcher
|
|
582
|
+
Main polling: getNextTask() <span class="branch">→</span> if task AND workers < 3: processTask() <span class="branch">→</span> acquire lease → IPC spawn worker → monitor → complete
|
|
583
|
+
<span class="branch">else</span>: sleep(15s)</div>
|
|
584
|
+
<p>Worker spawns child Bun process via Supervisor IPC (<code>main.tsx -p</code>). Max 3 concurrent workers. Task timeout 30 min.</p>
|
|
585
|
+
</div>
|
|
586
|
+
|
|
587
|
+
<div class="sys-section">
|
|
588
|
+
<h3>Task Queue Data Model</h3>
|
|
589
|
+
<p>File-backed at <code>~/.claude/daemon/tasks.json</code>. Key fields: <code>id</code>, <code>priority</code> (critical/high/normal/low), <code>status</code> (pending→in_progress→completed/failed/cancelled/dead_letter), <code>scheduledAt</code>, <code>dependsOn</code>, <code>retryCount</code>/<code>maxRetries</code> (default 3), <code>leaseOwner</code>/<code>leaseExpiresAt</code> (5-min default), <code>projectRoot</code>, <code>tags</code>, <code>errorLog</code> (last 20 lines).</p>
|
|
590
|
+
</div>
|
|
591
|
+
|
|
592
|
+
<div class="sys-section">
|
|
593
|
+
<h3>Supervisor IPC</h3>
|
|
594
|
+
<p>One per user, auto-started. Transport: Windows named pipe or Unix socket. Commands: <code>spawn</code>, <code>attach</code>, <code>stop</code>, <code>respawn</code>, <code>rm</code>, <code>list</code>, <code>logs</code>, <code>shutdown</code>, <code>ping</code>, <code>autonomous_start</code>/<code>stop</code>/<code>status</code>. Auto-exits after 1hr idle. Detects binary upgrades (inode/mtime check every 5min).</p>
|
|
595
|
+
</div>
|
|
596
|
+
|
|
597
|
+
<div class="sys-section">
|
|
598
|
+
<h3>Safety</h3>
|
|
599
|
+
<ul>
|
|
600
|
+
<li><strong>Lease/lock</strong> — prevents duplicate execution across restarts</li>
|
|
601
|
+
<li><strong>Prompt injection boundary</strong> — XML-wrapped task data with explicit system policy, CDATA sanitization, max 4000 chars</li>
|
|
602
|
+
<li><strong>Dead-letter</strong> — stops infinite retries after maxRetries</li>
|
|
603
|
+
<li><strong>Exponential backoff</strong> — <code>base × factor^retryCount</code> (capped at 1h)</li>
|
|
604
|
+
</ul>
|
|
605
|
+
</div>
|
|
606
|
+
|
|
607
|
+
</div>
|
|
608
|
+
</div>
|
|
609
|
+
|
|
610
|
+
<!-- ============================================================ -->
|
|
611
|
+
<!-- SYSTEM 8 -->
|
|
612
|
+
<!-- ============================================================ -->
|
|
613
|
+
<div class="system" id="sys8">
|
|
614
|
+
<div class="system-header">
|
|
615
|
+
<span class="num very-high">8</span>
|
|
616
|
+
<div class="meta">
|
|
617
|
+
<h2>MCP (Model Context Protocol) <code>23 files · 6 transports · OAuth 2207 lin</code></h2>
|
|
618
|
+
<div class="sub">
|
|
619
|
+
<span class="complexity-tag extreme">Very High</span>
|
|
620
|
+
<span>MCP SDK client • 6 transport types • OAuth + XAA • Server lifecycle</span>
|
|
621
|
+
</div>
|
|
622
|
+
</div>
|
|
623
|
+
</div>
|
|
624
|
+
<div class="system-body">
|
|
625
|
+
|
|
626
|
+
<div class="sys-section">
|
|
627
|
+
<h3>23 Files at <code>src/services/mcp/</code></h3>
|
|
628
|
+
<p>Key files: <code>client.ts</code> (connection management + tool/resource fetching), <code>auth.ts</code> (2207 lines — OAuth + XAA), <code>config.ts</code> (multi-source config), <code>types.ts</code> (state enums + types), <code>useManageMCPConnections.ts</code> (React lifecycle), <code>MCPConnectionManager.tsx</code> (React context), <code>InProcessTransport.ts</code>, <code>SdkControlTransport.ts</code>, <code>claudeai.ts</code>, <code>xaa.ts</code>, <code>xaaIdpLogin.ts</code>, <code>elicitationHandler.ts</code>, <code>mcpStringUtils.ts</code>, <code>channelAllowlist.ts</code>, <code>oauthPort.ts</code>, <code>officialRegistry.ts</code>.</p>
|
|
629
|
+
</div>
|
|
630
|
+
|
|
631
|
+
<div class="sys-section">
|
|
632
|
+
<h3>6 Transport Types</h3>
|
|
633
|
+
<table>
|
|
634
|
+
<tr><th>Transport</th><th>Mechanism</th><th>Reconnection</th></tr>
|
|
635
|
+
<tr><td><strong>Stdio</strong></td><td>Child process spawn</td><td>No (process exited)</td></tr>
|
|
636
|
+
<tr><td><strong>HTTP (StreamableHTTP)</strong></td><td>MCP Streamable HTTP spec</td><td>Exponential backoff, 5 attempts</td></tr>
|
|
637
|
+
<tr><td><strong>SSE</strong></td><td>Long-lived SSE + POST messages</td><td>Same as HTTP</td></tr>
|
|
638
|
+
<tr><td><strong>WebSocket</strong></td><td>Custom transport (Bun + ws package)</td><td>—</td></tr>
|
|
639
|
+
<tr><td><strong>SDK</strong></td><td>In-process CLI↔SDK bridge</td><td>—</td></tr>
|
|
640
|
+
<tr><td><strong>In-Process</strong></td><td>Linked transport pair (queueMicrotask)</td><td>—</td></tr>
|
|
641
|
+
</table>
|
|
642
|
+
</div>
|
|
643
|
+
|
|
644
|
+
<div class="sys-section">
|
|
645
|
+
<h3>OAuth (2207 lines)</h3>
|
|
646
|
+
<p><strong>Standard flow:</strong> RFC 8414 discovery → localhost callback server (127.0.0.1:random) → browser popup → CSRF state validation → code exchange → OS keychain storage (keyed by <code>serverName|sha256(configHash)[:16]</code>). Token refresh with lockfile-based cross-process coordination, exponential backoff (1s, 2s, 4s).</p>
|
|
647
|
+
<p><strong>XAA (SEP-990):</strong> Single IdP login across all XAA servers. OIDC + PKCE browser popup → RFC 8693/7523 token exchange (no browser). Silent refresh reuses cached <code>id_token</code> for zero-interaction re-auth.</p>
|
|
648
|
+
<p><strong>Step-Up Auth:</strong> Detects <code>403 insufficient_scope</code>, forces PKCE re-auth.</p>
|
|
649
|
+
</div>
|
|
650
|
+
|
|
651
|
+
<div class="sys-section">
|
|
652
|
+
<h3>Tool & Resource Exposure</h3>
|
|
653
|
+
<p><code>fetchToolsForClient()</code> (memoized) → <code>client.listTools()</code> → wraps each in <code>MCPTool</code>. Tools named <code>mcp__<server>__<toolName></code>. Dynamic updates via <code>tools.listChanged</code> capability. Resources fetched via <code>fetchResourcesForClient()</code>, with subscription support and skills integration.</p>
|
|
654
|
+
</div>
|
|
655
|
+
|
|
656
|
+
<div class="sys-section">
|
|
657
|
+
<h3>Config Sources</h3>
|
|
658
|
+
<p>Precedence: <code>enterprise > local (.claude/settings.local.json) > project (.mcp.json) > user > dynamic (--mcp-config) > claudeai > managed</code>. Each server validated independently. Supports env var expansion (<code>${VAR_NAME}</code>). Enterprise policy: <code>allowedMcpServers</code>, <code>deniedMcpServers</code>, <code>allowManagedMcpServersOnly</code>.</p>
|
|
659
|
+
</div>
|
|
660
|
+
|
|
661
|
+
</div>
|
|
662
|
+
</div>
|
|
663
|
+
|
|
664
|
+
<!-- ============================================================ -->
|
|
665
|
+
<!-- SYSTEM 9 -->
|
|
666
|
+
<!-- ============================================================ -->
|
|
667
|
+
<div class="system" id="sys9">
|
|
668
|
+
<div class="system-header">
|
|
669
|
+
<span class="num very-high">9</span>
|
|
670
|
+
<div class="meta">
|
|
671
|
+
<h2>Bridge <code>31 files · 2651 lin bridgeMain + 2166 lin replBridge</code></h2>
|
|
672
|
+
<div class="sub">
|
|
673
|
+
<span class="complexity-tag extreme">Very High</span>
|
|
674
|
+
<span>v1 env-based + v2 env-less • Remote WebSocket server • JWT refresh • Relay NAT</span>
|
|
675
|
+
</div>
|
|
676
|
+
</div>
|
|
677
|
+
</div>
|
|
678
|
+
<div class="system-body">
|
|
679
|
+
|
|
680
|
+
<div class="sys-section">
|
|
681
|
+
<h3>31 Files at <code>src/bridge/</code></h3>
|
|
682
|
+
<p>Key files: <code>bridgeMain.ts</code> (2651 lines — v1 env-based daemon), <code>replBridge.ts</code> (2166 lines — v1 REPL bridge), <code>remoteBridgeCore.ts</code> (861 lines — v2 env-less), <code>initReplBridge.ts</code>, <code>jwtUtils.ts</code>, <code>replBridgeTransport.ts</code>, <code>bridgeApi.ts</code>, <code>bridgeConfig.ts</code>, <code>bridgeMessaging.ts</code>, <code>sessionRunner.ts</code>, <code>inboundMessages.ts</code>, <code>inboundAttachments.ts</code>, <code>createSession.ts</code>, <code>trustedDevice.ts</code>, <code>flushGate.ts</code>, <code>capacityWake.ts</code>, <code>workSecret.ts</code>, <code>types.ts</code>.</p>
|
|
683
|
+
</div>
|
|
684
|
+
|
|
685
|
+
<div class="sys-section">
|
|
686
|
+
<h3>Two Bridge Paths</h3>
|
|
687
|
+
<p><strong>v1 (Environment-based):</strong> Registers on claude.ai via <code>POST /v1/environments</code>. Poll loop: <code>pollForWork()</code> → <code>WorkSecret</code> (session_ingress_token + api_base_url). Spawns child processes via Session-Ingress WebSocket → <code>HybridTransport</code>. Lifecycle: register → poll → ack → spawn → heartbeat → stop → deregister.</p>
|
|
688
|
+
<p><strong>v2 (Env-less, newer):</strong> Skips Environments API. Connects via <code>POST /v1/code/sessions</code> (OAuth) → <code>POST /v1/code/sessions/{id}/bridge</code> → <code>worker_jwt</code>. Uses <code>SSETransport</code> (reads) + <code>CCRClient</code> (writes via <code>/worker/*</code>). Token refresh bumps epoch. Gated by <code>tengu_bridge_repl_v2</code>.</p>
|
|
689
|
+
</div>
|
|
690
|
+
|
|
691
|
+
<div class="sys-section">
|
|
692
|
+
<h3>JWT Token Refresh</h3>
|
|
693
|
+
<p><code>createTokenRefreshScheduler</code> — reads JWT <code>exp</code>, sets timer for <code>exp - 5min_buffer</code>. Generation counter per session prevents stale refreshes. Retry: up to 3 failures, 60s delay. Fallback every 30min for long-running sessions.</p>
|
|
694
|
+
</div>
|
|
695
|
+
|
|
696
|
+
<div class="sys-section">
|
|
697
|
+
<h3>Remote Control (Self-Hosted)</h3>
|
|
698
|
+
<p><strong>RemoteServer</strong> — HTTP+WS server: <code>GET /health</code>, <code>POST /v1/sessions</code>, <code>GET /ws</code>. Token store: one-time tokens <code>clew-rt-<24-hex></code>, SHA-256 hashed, 24h expiry. <strong>Relay Server</strong> (NAT traversal): JSON over WebSocket, pairs listener + connector, forwards data bidirectionally.</p>
|
|
699
|
+
</div>
|
|
700
|
+
|
|
701
|
+
</div>
|
|
702
|
+
</div>
|
|
703
|
+
|
|
704
|
+
<!-- ============================================================ -->
|
|
705
|
+
<!-- SYSTEM 10 -->
|
|
706
|
+
<!-- ============================================================ -->
|
|
707
|
+
<div class="system" id="sys10">
|
|
708
|
+
<div class="system-header">
|
|
709
|
+
<span class="num medium">10</span>
|
|
710
|
+
<div class="meta">
|
|
711
|
+
<h2>Plugins <code>3 ops files · 27 hook events · builtin + marketplace</code></h2>
|
|
712
|
+
<div class="sub">
|
|
713
|
+
<span class="complexity-tag high">Medium</span>
|
|
714
|
+
<span>pluginOperations • PluginInstallationManager • 10+ builtin plugins</span>
|
|
715
|
+
</div>
|
|
716
|
+
</div>
|
|
717
|
+
</div>
|
|
718
|
+
<div class="system-body">
|
|
719
|
+
|
|
720
|
+
<div class="sys-section">
|
|
721
|
+
<h3>Core Plugin Files</h3>
|
|
722
|
+
<p><strong>Service layer:</strong> <code>src/services/plugins/</code> — <code>pluginOperations.ts</code>, <code>PluginInstallationManager.ts</code>, <code>pluginCliCommands.ts</code>. <strong>Builtin:</strong> <code>src/plugins/builtinPlugins.ts</code>, <code>src/plugins/bundled/</code>. <strong>External:</strong> <code>plugins/</code> directory.</p>
|
|
723
|
+
</div>
|
|
724
|
+
|
|
725
|
+
<div class="sys-section">
|
|
726
|
+
<h3>Lifecycle</h3>
|
|
727
|
+
<div class="flow">Declaration (settings) <span class="arrow">→</span> Materialization (marketplace clone/fetch) <span class="arrow">→</span> Loading (validate + cache) <span class="arrow">→</span> Enablement (settings + transitive deps force-enabled) <span class="arrow">→</span> Execution (commands + hooks + agents + MCP servers) <span class="arrow">→</span> Disable/Uninstall</div>
|
|
728
|
+
</div>
|
|
729
|
+
|
|
730
|
+
<div class="sys-section">
|
|
731
|
+
<h3>27 Hook Events</h3>
|
|
732
|
+
<p>Hook types: <code>command</code> (shell exec), <code>prompt</code> (LLM eval), <code>agent</code> (verifier), <code>http</code> (POST), <code>callback</code> (internal). Events include: <code>Setup</code>, <code>SessionStart</code>, <code>UserPromptSubmit</code>, <code>PreToolUse</code>/<code>PostToolUse</code>/<code>PostToolUseFailure</code>, <code>PermissionRequest</code>/<code>PermissionDenied</code>, <code>Stop</code>/<code>StopFailure</code>, <code>SessionEnd</code>, <code>SubagentStart</code>/<code>Stop</code>, <code>PreCompact</code>/<code>PostCompact</code>, <code>Elicitation</code>, <code>ConfigChange</code>, <code>WorktreeCreate</code>/<code>Remove</code>, <code>FileChanged</code>, <code>CwdChanged</code>, <code>TeammateIdle</code>, <code>TaskCreated</code>/<code>Completed</code>, <code>InstructionsLoaded</code>, <code>MessageDisplay</code>.</p>
|
|
733
|
+
<p>Exit codes: 0 = stdout to Claude, 2 = stderr to model (blocking). Supports <code>async: true</code> (background), <code>once: true</code> (auto-remove), <code>if</code> conditions (permission rule syntax).</p>
|
|
734
|
+
</div>
|
|
735
|
+
|
|
736
|
+
<div class="sys-section">
|
|
737
|
+
<h3>Manifest & Marketplace</h3>
|
|
738
|
+
<p><strong>plugin.json</strong> fields: <code>name</code>, <code>version</code>, <code>dependencies</code>, <code>commands</code>, <code>agents</code>, <code>skills</code>, <code>hooks</code>, <code>mcpServers</code>, <code>lspServers</code>, <code>userConfig</code>, <code>settings</code>, <code>strict</code>. Marketplace sources: <code>github</code>, <code>git</code>, <code>url</code>, <code>npm</code>, <code>file</code>, <code>directory</code>. Dependency resolution: DFS with cycle detection. Cross-marketplace deps blocked by default.</p>
|
|
739
|
+
</div>
|
|
740
|
+
|
|
741
|
+
<div class="sys-section">
|
|
742
|
+
<h3>Builtin Plugins</h3>
|
|
743
|
+
<p><code>commit-commands</code>, <code>code-review</code>, <code>feature-dev</code>, <code>frontend-design</code>, <code>security-guidance</code>, <code>agent-sdk-dev</code>, <code>hookify</code>, <code>plugin-dev</code>, <code>pr-review-toolkit</code>, plus output styles and migrations.</p>
|
|
744
|
+
</div>
|
|
745
|
+
|
|
746
|
+
</div>
|
|
747
|
+
</div>
|
|
748
|
+
|
|
749
|
+
<!-- ============================================================ -->
|
|
750
|
+
<!-- SYSTEM 11 -->
|
|
751
|
+
<!-- ============================================================ -->
|
|
752
|
+
<div class="system" id="sys11">
|
|
753
|
+
<div class="system-header">
|
|
754
|
+
<span class="num medium">11</span>
|
|
755
|
+
<div class="meta">
|
|
756
|
+
<h2>AppState <code>6 files · monolithic store ~80 fields</code></h2>
|
|
757
|
+
<div class="sub">
|
|
758
|
+
<span class="complexity-tag high">Medium</span>
|
|
759
|
+
<span>createStore factory • useSyncExternalStore • Immutable updates</span>
|
|
760
|
+
</div>
|
|
761
|
+
</div>
|
|
762
|
+
</div>
|
|
763
|
+
<div class="system-body">
|
|
764
|
+
|
|
765
|
+
<div class="sys-section">
|
|
766
|
+
<h3>6 Files</h3>
|
|
767
|
+
<p><code>store.ts</code> — generic <code>createStore<T>()</code> returning <code>{ getState, setState, subscribe }</code>. Uses <code>Object.is</code> for no-op skip.</p>
|
|
768
|
+
<p><code>AppStateStore.ts</code> — <code>AppState</code> type (~80 fields): settings, MCP connections, plugins, tasks, tool permissions, bridge, speculation, voice, tmux/tungsten, agent definitions, file history, notifications.</p>
|
|
769
|
+
<p><code>AppState.tsx</code> — React glue: <code>AppStateProvider</code> creates store, provides via context. <code>useAppState(selector)</code> uses <code>useSyncExternalStore</code>. <code>useSetAppState()</code> stable updater ref.</p>
|
|
770
|
+
<p><code>onChangeAppState.ts</code> — side-effect orchestrator: syncs permission mode to CCR/SDK, persists model/settings.</p>
|
|
771
|
+
<p><code>selectors.ts</code> — <code>getViewedTeammateTask()</code>, <code>getActiveAgentForInput()</code>.</p>
|
|
772
|
+
<p><code>teammateViewHelpers.ts</code> — agent view utilities.</p>
|
|
773
|
+
</div>
|
|
774
|
+
|
|
775
|
+
</div>
|
|
776
|
+
</div>
|
|
777
|
+
|
|
778
|
+
<!-- ============================================================ -->
|
|
779
|
+
<!-- SYSTEM 12 -->
|
|
780
|
+
<!-- ============================================================ -->
|
|
781
|
+
<div class="system" id="sys12">
|
|
782
|
+
<div class="system-header">
|
|
783
|
+
<span class="num medium">12</span>
|
|
784
|
+
<div class="meta">
|
|
785
|
+
<h2>Ink UI <code>97 files · custom React renderer</code></h2>
|
|
786
|
+
<div class="sub">
|
|
787
|
+
<span class="complexity-tag high">Medium</span>
|
|
788
|
+
<span>Custom fiber reconciler • Yoga flexbox layout • Full ANSI event system • 461 component files</span>
|
|
789
|
+
</div>
|
|
790
|
+
</div>
|
|
791
|
+
</div>
|
|
792
|
+
<div class="system-body">
|
|
793
|
+
|
|
794
|
+
<div class="sys-section">
|
|
795
|
+
<h3>Custom Renderer (<code>src/ink/</code>, 97 files)</h3>
|
|
796
|
+
<p>A reimplementation of the <code>ink</code> library:</p>
|
|
797
|
+
<ul>
|
|
798
|
+
<li><strong>Reconciler</strong> (<code>reconciler.ts</code>) — custom React fiber reconciler using <code>react-reconciler</code></li>
|
|
799
|
+
<li><strong>Render pipeline</strong> — <code>renderer.ts</code>, <code>render-to-screen.ts</code>, <code>render-node-to-output.ts</code> (virtual tree → ANSI escape sequences)</li>
|
|
800
|
+
<li><strong>Layout</strong> — Yoga (Facebook flexbox) engine for terminal positioning</li>
|
|
801
|
+
<li><strong>Event system</strong> — keyboard, mouse, terminal resize, focus dispatcher</li>
|
|
802
|
+
<li><strong>Terminal I/O</strong> — ANSI/SGR/CSI/DEC parsing, OSC commands, tokenizer</li>
|
|
803
|
+
<li><strong>Components</strong> — <code>Box</code>, <code>Text</code>, <code>Button</code>, <code>Spacer</code>, <code>Newline</code>, <code>Link</code>, <code>ScrollBox</code>, <code>AlternateScreen</code></li>
|
|
804
|
+
<li><strong>Hooks</strong> — <code>use-input</code>, <code>use-app</code>, <code>use-stdin</code>, <code>use-interval</code>, <code>use-animation-frame</code>, <code>use-terminal-viewport</code>, <code>use-selection</code>, <code>use-search-highlight</code>, <code>use-tab-status</code>, <code>use-terminal-focus</code></li>
|
|
805
|
+
</ul>
|
|
806
|
+
</div>
|
|
807
|
+
|
|
808
|
+
<div class="sys-section">
|
|
809
|
+
<h3>UI Components (<code>src/components/</code>, 461 files)</h3>
|
|
810
|
+
<ul>
|
|
811
|
+
<li><strong>Shell:</strong> <code>App.tsx</code> (top-level with AppStateProvider, stats, FPS, Sentry), <code>Messages.tsx</code>, <code>Message.tsx</code>, <code>MessageRow.tsx</code></li>
|
|
812
|
+
<li><strong>Prompt input:</strong> <code>PromptInput/</code> directory — input, footer, voice indicator, history search, suggestions</li>
|
|
813
|
+
<li><strong>Messages:</strong> <code>UserPromptMessage</code>, <code>AssistantTextMessage</code>, <code>AssistantThinkingMessage</code>, <code>AssistantToolUseMessage</code>, <code>UserBashInputMessage</code>, <code>UserToolResultMessage</code>, <code>SystemTextMessage</code> + many more</li>
|
|
814
|
+
<li><strong>Permissions:</strong> Dialogs for bash, file write, file edit, PowerShell, sandbox, web fetch, skills, notebook edit, plan mode, computer use</li>
|
|
815
|
+
<li><strong>Design system:</strong> <code>ThemedText</code>, <code>ThemedBox</code>, <code>Dialog</code>, <code>Pane</code>, <code>Tabs</code>, <code>Divider</code>, <code>ListItem</code>, <code>ProgressBar</code>, <code>StatusIcon</code></li>
|
|
816
|
+
<li><strong>Management:</strong> MCP servers, plugins, agents (create wizard with 10+ steps), skills, hooks</li>
|
|
817
|
+
</ul>
|
|
818
|
+
</div>
|
|
819
|
+
|
|
820
|
+
<div class="sys-section">
|
|
821
|
+
<h3>Screens (<code>src/screens/</code>, 3 files)</h3>
|
|
822
|
+
<p><code>REPL.tsx</code> — main read-eval-print loop. <code>Doctor.tsx</code> — diagnostics screen. <code>ResumeConversation.tsx</code> — session picker with progressive loading.</p>
|
|
823
|
+
</div>
|
|
824
|
+
|
|
825
|
+
</div>
|
|
826
|
+
</div>
|
|
827
|
+
|
|
828
|
+
<!-- ============================================================ -->
|
|
829
|
+
<!-- SYSTEM 13 -->
|
|
830
|
+
<!-- ============================================================ -->
|
|
831
|
+
<div class="system" id="sys13">
|
|
832
|
+
<div class="system-header">
|
|
833
|
+
<span class="num medium">13</span>
|
|
834
|
+
<div class="meta">
|
|
835
|
+
<h2>Slash Commands <code>120+ dirs · 411 files</code></h2>
|
|
836
|
+
<div class="sub">
|
|
837
|
+
<span class="complexity-tag high">Medium</span>
|
|
838
|
+
<span>Organized in subdirectories, each exports call() + index.ts</span>
|
|
839
|
+
</div>
|
|
840
|
+
</div>
|
|
841
|
+
</div>
|
|
842
|
+
<div class="system-body">
|
|
843
|
+
|
|
844
|
+
<div class="sys-section">
|
|
845
|
+
<h3>Command Categories</h3>
|
|
846
|
+
<table>
|
|
847
|
+
<tr><th>Category</th><th>Commands</th></tr>
|
|
848
|
+
<tr><td><strong>Core session</strong></td><td><code>/clear</code>, <code>/compact</code>, <code>/exit</code>, <code>/resume</code>, <code>/session</code>, <code>/status</code>, <code>/version</code></td></tr>
|
|
849
|
+
<tr><td><strong>Configuration</strong></td><td><code>/config</code>, <code>/model</code>, <code>/provider-select</code>, <code>/theme</code>, <code>/color</code>, <code>/output-style</code>, <code>/effort</code>, <code>/fast</code>, <code>/thinking</code>, <code>/keybindings</code>, <code>/scroll-speed</code></td></tr>
|
|
850
|
+
<tr><td><strong>Collaboration</strong></td><td><code>/buddy</code>, <code>/peer</code>, <code>/bridge</code>, <code>/remote</code>, <code>/teleport</code>, <code>/session</code></td></tr>
|
|
851
|
+
<tr><td><strong>Code review</strong></td><td><code>/review</code>, <code>/pr</code>, <code>/diff</code>, <code>/commit</code>, <code>/commit-push-pr</code>, <code>/branch</code>, <code>/autofix-pr</code></td></tr>
|
|
852
|
+
<tr><td><strong>Agent management</strong></td><td><code>/agent</code>, <code>/agents</code>, <code>/skill</code>, <code>/skills</code>, <code>/task</code>, <code>/tasks</code>, <code>/daemon</code></td></tr>
|
|
853
|
+
<tr><td><strong>Utilities</strong></td><td><code>/help</code>, <code>/doctor</code>, <code>/cost</code>, <code>/usage</code>, <code>/stats</code>, <code>/export</code>, <code>/install</code>, <code>/upgrade</code>, <code>/feedback</code>, <code>/recap</code></td></tr>
|
|
854
|
+
<tr><td><strong>MCP/Plugin</strong></td><td><code>/plugin</code>, <code>/mcp</code>, <code>/reload-plugins</code>, <code>/searxng</code>, <code>/tools</code></td></tr>
|
|
855
|
+
<tr><td><strong>Voice/UI</strong></td><td><code>/voice</code>, <code>/vim</code>, <code>/desktop</code>, <code>/mobile</code>, <code>/sandbox-toggle</code></td></tr>
|
|
856
|
+
<tr><td><strong>Advanced</strong></td><td><code>/ultraplan</code>, <code>/ultracode</code>, <code>/goal</code>, <code>/plan</code>, <code>/research</code>, <code>/workflow</code>, <code>/thinkback</code>, <code>/thinkback-play</code>, <code>/bg</code>, <code>/explorer</code></td></tr>
|
|
857
|
+
<tr><td><strong>Auth</strong></td><td><code>/login</code>, <code>/logout</code>, <code>/oauth-refresh</code></td></tr>
|
|
858
|
+
</table>
|
|
859
|
+
<p>Also includes: <code>/taste</code>, <code>/taste1</code>, <code>/memory</code>, <code>/context</code>, <code>/rename</code>, <code>/tag</code>, <code>/insights</code>, <code>/guardian</code>, <code>/approve</code>, <code>/brief</code>, <code>/copy</code>, <code>/onboarding</code>, <code>/powerup</code>, <code>/looplock</code>, <code>/passes</code>, <code>/privacy-settings</code>, <code>/permissions</code>, <code>/env</code>, <code>/files</code>, advisory commands, and many more.</p>
|
|
860
|
+
</div>
|
|
861
|
+
|
|
862
|
+
</div>
|
|
863
|
+
</div>
|
|
864
|
+
|
|
865
|
+
<!-- ============================================================ -->
|
|
866
|
+
<!-- SYSTEM 14 -->
|
|
867
|
+
<!-- ============================================================ -->
|
|
868
|
+
<div class="system" id="sys14">
|
|
869
|
+
<div class="system-header">
|
|
870
|
+
<span class="num medium">14</span>
|
|
871
|
+
<div class="meta">
|
|
872
|
+
<h2>Cost & History <code>cost-tracker.ts (350) · history.ts (451)</code></h2>
|
|
873
|
+
<div class="sub">
|
|
874
|
+
<span class="complexity-tag high">Medium</span>
|
|
875
|
+
<span>Token accounting per model • JSONL persistence • Paste store</span>
|
|
876
|
+
</div>
|
|
877
|
+
</div>
|
|
878
|
+
</div>
|
|
879
|
+
<div class="system-body">
|
|
880
|
+
|
|
881
|
+
<div class="sys-section">
|
|
882
|
+
<h3>Cost Tracker (350 lines)</h3>
|
|
883
|
+
<p><code>addToTotalSessionCost(cost, usage, model)</code> — accepts both Anthropic (snake_case) and generic (camelCase) usage. Accumulates input/output/cache tokens per model. Tracks advisor usage costs. Sends OpenTelemetry metrics.</p>
|
|
884
|
+
<p><strong>Session persistence:</strong> <code>restoreCostStateForSession(sessionId)</code> reads from project config; <code>saveCurrentSessionCosts()</code> writes back with FPS metrics and per-model usage. Re-exports from bootstrap/state: <code>getTotalCost</code>, <code>getTotalInputTokens</code>, <code>getTotalOutputTokens</code>, <code>getTotalDuration</code>, <code>getTotalAPIDuration</code>, <code>getModelUsage</code>.</p>
|
|
885
|
+
</div>
|
|
886
|
+
|
|
887
|
+
<div class="sys-section">
|
|
888
|
+
<h3>History System (451 lines)</h3>
|
|
889
|
+
<p>Prompt history persists to <code>~/.claude/history.jsonl</code>:</p>
|
|
890
|
+
<ul>
|
|
891
|
+
<li><code>addToHistory(entry)</code> — deduplicates consecutive identical entries. Large paste contents hashed to <code>pasteStore</code>.</li>
|
|
892
|
+
<li><code>getHistory()</code> — async generator: current-session first (newest-first), then cross-session. Max 1000 items.</li>
|
|
893
|
+
<li><code>getTimestampedHistory()</code> — for ctrl+R picker: deduplicated by display text, lazy <code>resolve()</code> for paste contents.</li>
|
|
894
|
+
<li><code>removeLastFromHistory()</code> — undo last entry (Esc-rewind): fast path pops pending buffer.</li>
|
|
895
|
+
<li><strong>File I/O:</strong> JSONL with pid-based file locking, retry logic, batch flushing.</li>
|
|
896
|
+
</ul>
|
|
897
|
+
</div>
|
|
898
|
+
|
|
899
|
+
</div>
|
|
900
|
+
</div>
|
|
901
|
+
|
|
902
|
+
<!-- ============================================================ -->
|
|
903
|
+
<!-- SYSTEM 15 -->
|
|
904
|
+
<!-- ============================================================ -->
|
|
905
|
+
<div class="system" id="sys15">
|
|
906
|
+
<div class="system-header">
|
|
907
|
+
<span class="num medium">15</span>
|
|
908
|
+
<div class="meta">
|
|
909
|
+
<h2>Context & Permissions <code>context.ts (195 lines)</code></h2>
|
|
910
|
+
<div class="sub">
|
|
911
|
+
<span class="complexity-tag high">Medium</span>
|
|
912
|
+
<span>System context • Git status • CLAUDE.md • Tool permissions in AppState</span>
|
|
913
|
+
</div>
|
|
914
|
+
</div>
|
|
915
|
+
</div>
|
|
916
|
+
<div class="system-body">
|
|
917
|
+
|
|
918
|
+
<div class="sys-section">
|
|
919
|
+
<h3>System Context (<code>getSystemContext()</code>)</h3>
|
|
920
|
+
<ul>
|
|
921
|
+
<li><strong><code>gitStatus</code></strong> — Git branch, short status, recent commits (memoized, capped 2000 chars, async exec)</li>
|
|
922
|
+
<li><strong><code>capabilities</code></strong> — detected system tools available</li>
|
|
923
|
+
<li><strong><code>computerUseHint</code></strong> — prompt injection when computer use enabled</li>
|
|
924
|
+
<li><strong><code>cacheBreaker</code></strong> — ephemeral injection (ant-only, cache breaking)</li>
|
|
925
|
+
</ul>
|
|
926
|
+
</div>
|
|
927
|
+
|
|
928
|
+
<div class="sys-section">
|
|
929
|
+
<h3>User Context (<code>getUserContext()</code>)</h3>
|
|
930
|
+
<ul>
|
|
931
|
+
<li><strong><code>claudeMd</code></strong> — parsed CLAUDE.md / memory files from <code>.claude/memory/</code></li>
|
|
932
|
+
<li><strong><code>currentDate</code></strong> — today's date string</li>
|
|
933
|
+
</ul>
|
|
934
|
+
</div>
|
|
935
|
+
|
|
936
|
+
<div class="sys-section">
|
|
937
|
+
<h3>Permissions</h3>
|
|
938
|
+
<p><code>toolPermissionContext</code> lives in AppState (not context.ts). This module provides the <strong>context window content</strong> for the LLM's workspace understanding. Tool permissions use classifier + rules + prompt approval in the tool execution pipeline. <code>initializeToolPermissionContext()</code> is called with allowed/disallowed tool lists.</p>
|
|
939
|
+
</div>
|
|
940
|
+
|
|
941
|
+
</div>
|
|
942
|
+
</div>
|
|
943
|
+
|
|
944
|
+
<!-- ============================================================ -->
|
|
945
|
+
<!-- SYSTEM 16 -->
|
|
946
|
+
<!-- ============================================================ -->
|
|
947
|
+
<div class="system" id="sys16">
|
|
948
|
+
<div class="system-header">
|
|
949
|
+
<span class="num medium">16</span>
|
|
950
|
+
<div class="meta">
|
|
951
|
+
<h2>Voice <code>voiceModeEnabled.ts (58 lines)</code></h2>
|
|
952
|
+
<div class="sub">
|
|
953
|
+
<span class="complexity-tag high">Medium</span>
|
|
954
|
+
<span>Gateway checks • OAuth auth • Alternative STT backends</span>
|
|
955
|
+
</div>
|
|
956
|
+
</div>
|
|
957
|
+
</div>
|
|
958
|
+
<div class="system-body">
|
|
959
|
+
|
|
960
|
+
<div class="sys-section">
|
|
961
|
+
<h3>Gateway Checks</h3>
|
|
962
|
+
<ul>
|
|
963
|
+
<li><strong><code>isVoiceGrowthBookEnabled()</code></strong> — always <code>true</code> in OSS build</li>
|
|
964
|
+
<li><strong><code>hasVoiceAuth()</code></strong> — requires valid Anthropic OAuth tokens (<code>voice_stream</code> endpoint)</li>
|
|
965
|
+
<li><strong><code>hasAlternativeSttKey()</code></strong> — true if <code>OPENAI_API_KEY</code>, <code>GROQ_API_KEY</code>, or <code>WHISPER_API_KEY + WHISPER_API_URL</code> set</li>
|
|
966
|
+
<li><strong><code>isVoiceModeEnabled()</code></strong> — full check: <code>hasVoiceAuth() || hasAlternativeSttKey()</code> AND GrowthBook gate</li>
|
|
967
|
+
</ul>
|
|
968
|
+
</div>
|
|
969
|
+
|
|
970
|
+
<div class="sys-section">
|
|
971
|
+
<h3>Wider Implementation</h3>
|
|
972
|
+
<p>Spans into <code>src/commands/voice/</code> (<code>/voice</code> command), <code>src/services/voice.ts</code>, <code>voiceStreamSTT.ts</code>, <code>voiceKeyterms.ts</code>, and UI components <code>VoiceIndicator</code>, <code>VoiceModeNotice</code>. Supports Anthropic voice streaming + alternative STT (OpenAI, Groq, Whisper).</p>
|
|
973
|
+
</div>
|
|
974
|
+
|
|
975
|
+
</div>
|
|
976
|
+
</div>
|
|
977
|
+
|
|
978
|
+
<!-- ============================================================ -->
|
|
979
|
+
<!-- SYSTEM 17 -->
|
|
980
|
+
<!-- ============================================================ -->
|
|
981
|
+
<div class="system" id="sys17">
|
|
982
|
+
<div class="system-header">
|
|
983
|
+
<span class="num medium">17</span>
|
|
984
|
+
<div class="meta">
|
|
985
|
+
<h2>Memory <code>14 files · SQLite FTS5</code></h2>
|
|
986
|
+
<div class="sub">
|
|
987
|
+
<span class="complexity-tag high">Medium</span>
|
|
988
|
+
<span>No embeddings • Full-text search • Chunk-based indexing</span>
|
|
989
|
+
</div>
|
|
990
|
+
</div>
|
|
991
|
+
</div>
|
|
992
|
+
<div class="system-body">
|
|
993
|
+
|
|
994
|
+
<div class="sys-section">
|
|
995
|
+
<h3>14 Files at <code>src/memory/</code></h3>
|
|
996
|
+
<table>
|
|
997
|
+
<tr><th>File</th><th>Purpose</th></tr>
|
|
998
|
+
<tr><td><code>db.ts</code></td><td>SQLite bootstrap: <code>sources</code>, <code>chunks</code>, <code>chunks_fts</code> (FTS5). WAL mode. DB at <code>.claude/index/chunks.db</code></td></tr>
|
|
999
|
+
<tr><td><code>store.ts</code></td><td>CRUD: <code>getSource</code>, <code>upsertSource</code>, <code>deleteSource</code>, <code>insertChunks</code> (FTS transaction), <code>searchChunksFTS</code> (sanitized prefix search)</td></tr>
|
|
1000
|
+
<tr><td><code>search.ts</code></td><td><code>searchMemories(cwd, query, limit)</code> — FTS + scoring: priority (0-1) × recency (0-0.15 for <24h) × lexical. Returns sorted <code>MemorySearchResult[]</code></td></tr>
|
|
1001
|
+
<tr><td><code>ingest.ts</code></td><td><code>ingestMemoryWorkspace(cwd, config)</code> — full re-scan, content hash compare, re-chunk changed files, delete removed</td></tr>
|
|
1002
|
+
<tr><td><code>chunker.ts</code></td><td><code>chunkMarkdown()</code> — splits by word boundary, default 3000 tokens/chunk</td></tr>
|
|
1003
|
+
<tr><td><code>redact.ts</code></td><td><code>redactSecrets()</code> — strips API keys, tokens before indexing</td></tr>
|
|
1004
|
+
<tr><td><code>types.ts</code></td><td><code>MemoryType</code>: <code>user</code>, <code>project</code>, <code>feedback</code>, <code>agent</code>, <code>pending</code>, <code>wiki</code>, <code>run</code>, <code>index</code></td></tr>
|
|
1005
|
+
<tr><td><code>runs/runWriter.ts</code></td><td>Writes conversation summaries to memory</td></tr>
|
|
1006
|
+
</table>
|
|
1007
|
+
</div>
|
|
1008
|
+
|
|
1009
|
+
<div class="sys-section">
|
|
1010
|
+
<h3>Scoring & Config</h3>
|
|
1011
|
+
<p><strong>Truth priority:</strong> <code>user</code>=80, <code>feedback</code>=70, <code>project</code>=60, default=50. <strong>Content hashing:</strong> quick stat-based (relPath + size + mtime) avoids re-indexing. <strong>Config:</strong> memory dir, wiki dir, index dir, max chunk tokens (3000), auto-capture, auto-sync, exclude globs.</p>
|
|
1012
|
+
</div>
|
|
1013
|
+
|
|
1014
|
+
</div>
|
|
1015
|
+
</div>
|
|
1016
|
+
|
|
1017
|
+
<!-- ============================================================ -->
|
|
1018
|
+
<!-- SYSTEM 18: FULL ARCHITECTURE FLOW -->
|
|
1019
|
+
<!-- ============================================================ -->
|
|
1020
|
+
<div class="system" id="sys18">
|
|
1021
|
+
<div class="system-header">
|
|
1022
|
+
<span class="num medium">18</span>
|
|
1023
|
+
<div class="meta">
|
|
1024
|
+
<h2>Architecture Flow <code>end-to-end system map</code></h2>
|
|
1025
|
+
<div class="sub">
|
|
1026
|
+
<span class="complexity-tag high">Medium</span>
|
|
1027
|
+
<span>Data flow • Component relationships • Execution paths</span>
|
|
1028
|
+
</div>
|
|
1029
|
+
</div>
|
|
1030
|
+
</div>
|
|
1031
|
+
<div class="system-body">
|
|
1032
|
+
|
|
1033
|
+
<div class="sys-section">
|
|
1034
|
+
<h3>End-to-End Data Flow</h3>
|
|
1035
|
+
<div class="flow"><span class="step">CLI</span> (bin/clew.cjs)
|
|
1036
|
+
<span class="arrow">→</span> <span class="step">main.tsx</span> (bootstrap + init, 6475 lines)
|
|
1037
|
+
<span class="arrow">→</span> setup.ts (env, git, worktree, plugins, memory, 423 lines)
|
|
1038
|
+
<span class="arrow">→</span> AppStateProvider + Ink renderer
|
|
1039
|
+
<span class="arrow">→</span> REPL screen
|
|
1040
|
+
<span class="arrow">→</span> User types prompt (or slash command /)
|
|
1041
|
+
<span class="arrow">→</span> <span class="step">QueryEngine.submitMessage()</span>
|
|
1042
|
+
<span class="arrow">→</span> Process user input (slash commands, attachments)
|
|
1043
|
+
<span class="arrow">→</span> Build system init (tools, MCP, model, agents, skills)
|
|
1044
|
+
<span class="arrow">→</span> <span class="step">query() → queryLoop()</span> (1623 lines)
|
|
1045
|
+
<span class="arrow">→</span> Compact history (snip → micro → collapse → auto)
|
|
1046
|
+
<span class="arrow">→</span> <span class="step">ProviderAdapter</span> → <span class="step">AI Provider</span> (streaming)
|
|
1047
|
+
<span class="arrow">→</span> <span class="step">Tool Execution</span> (runTools or StreamingToolExecutor)
|
|
1048
|
+
<span class="arrow">→</span> Post-sampling hooks + Stop hooks
|
|
1049
|
+
<span class="arrow">→</span> Token budget check → continue or complete
|
|
1050
|
+
<span class="arrow">→</span> Yield result (success/error/budget-exceeded)
|
|
1051
|
+
<span class="arrow">→</span> Update AppState → Ink re-renders UI
|
|
1052
|
+
<span class="arrow">→</span> Taste learns from accept/reject/edit
|
|
1053
|
+
<span class="arrow">→</span> Cost tracker accumulates
|
|
1054
|
+
<span class="arrow">→</span> History appended to history.jsonl</div>
|
|
1055
|
+
</div>
|
|
1056
|
+
|
|
1057
|
+
<div class="sys-section">
|
|
1058
|
+
<h3>Execution Paths</h3>
|
|
1059
|
+
<p><strong>Interactive:</strong> main.tsx → showSetupScreens() → LaunchRepl() → Ink TUI → QueryEngine → AI loop → Tool execution → Response</p>
|
|
1060
|
+
<p><strong>Headless (--print):</strong> main.tsx → runHeadless() → headlessStore → QueryEngine → StructuredIO → stdout</p>
|
|
1061
|
+
<p><strong>Autonomous:</strong> Supervisor IPC → daemonMode.ts → agentLoop.ts → taskQueue → spawn workers via IPC → monitor → complete/fail</p>
|
|
1062
|
+
<p><strong>Peer-to-Peer:</strong> /peer share → PeerDiscovery → PeerServer on random port → file registry → HTTP POST/SSE → peers communicate</p>
|
|
1063
|
+
<p><strong>Bridge:</strong> /bridge → initReplBridge() → v1 (env poll loop) or v2 (env-less) → JWT refresh → bidir message relay</p>
|
|
1064
|
+
</div>
|
|
1065
|
+
|
|
1066
|
+
<div class="sys-section">
|
|
1067
|
+
<h3>System Dependencies</h3>
|
|
1068
|
+
<table>
|
|
1069
|
+
<tr><th>#</th><th>System</th><th>Depends On</th><th>Used By</th></tr>
|
|
1070
|
+
<tr><td>1</td><td>Entry Point</td><td>—</td><td>All</td></tr>
|
|
1071
|
+
<tr><td>2</td><td>AI Providers</td><td>—</td><td>QueryEngine, Tools</td></tr>
|
|
1072
|
+
<tr><td>3</td><td>Query Engine</td><td>Providers, Tools, Taste, Context</td><td>REPL, Headless, Workers</td></tr>
|
|
1073
|
+
<tr><td>4</td><td>Tool System</td><td>AppState, MCP</td><td>QueryEngine</td></tr>
|
|
1074
|
+
<tr><td>5</td><td>Peer-to-Peer</td><td>AppState</td><td>Commands, Autonomous</td></tr>
|
|
1075
|
+
<tr><td>6</td><td>Taste</td><td>Storage</td><td>QueryEngine</td></tr>
|
|
1076
|
+
<tr><td>7</td><td>Autonomous</td><td>Supervisor, Queue</td><td>Daemon, Cron</td></tr>
|
|
1077
|
+
<tr><td>8</td><td>MCP</td><td>Auth</td><td>Tools, QueryEngine</td></tr>
|
|
1078
|
+
<tr><td>9</td><td>Bridge</td><td>Providers, Auth</td><td>Remote sessions</td></tr>
|
|
1079
|
+
<tr><td>10</td><td>Plugins</td><td>Settings</td><td>Commands, Hooks, Agents</td></tr>
|
|
1080
|
+
<tr><td>11</td><td>AppState</td><td>—</td><td>All</td></tr>
|
|
1081
|
+
<tr><td>12</td><td>Ink UI</td><td>AppState</td><td>REPL, Interactive</td></tr>
|
|
1082
|
+
<tr><td>13</td><td>Commands</td><td>AppState, Plugins</td><td>REPL</td></tr>
|
|
1083
|
+
<tr><td>14</td><td>Cost & History</td><td>Bootstrap state</td><td>Reporting, Resume</td></tr>
|
|
1084
|
+
<tr><td>15</td><td>Context</td><td>Git, FS</td><td>QueryEngine</td></tr>
|
|
1085
|
+
<tr><td>16</td><td>Voice</td><td>OAuth</td><td>REPL</td></tr>
|
|
1086
|
+
<tr><td>17</td><td>Memory</td><td>SQLite</td><td>QueryEngine</td></tr>
|
|
1087
|
+
</table>
|
|
1088
|
+
</div>
|
|
1089
|
+
|
|
1090
|
+
<div class="sys-section">
|
|
1091
|
+
<h3>Key File Metrics</h3>
|
|
1092
|
+
<table>
|
|
1093
|
+
<tr><th>File</th><th>Lines</th><th>Role</th></tr>
|
|
1094
|
+
<tr><td><code>main.tsx</code></td><td>6,475</td><td>Entry — full bootstrap + CLI + lifecycle</td></tr>
|
|
1095
|
+
<tr><td><code>query.ts</code></td><td>1,623</td><td>Core AI loop</td></tr>
|
|
1096
|
+
<tr><td><code>QueryEngine.ts</code></td><td>1,219</td><td>Conversation orchestrator</td></tr>
|
|
1097
|
+
<tr><td><code>Tool.ts</code></td><td>782</td><td>Base tool type + buildTool()</td></tr>
|
|
1098
|
+
<tr><td><code>commands.ts</code></td><td>740</td><td>Command registrations</td></tr>
|
|
1099
|
+
<tr><td><code>ProviderManager.ts</code></td><td>369</td><td>Provider selection singleton</td></tr>
|
|
1100
|
+
<tr><td><code>setup.ts</code></td><td>423</td><td>Init/setup sequence</td></tr>
|
|
1101
|
+
<tr><td><code>context.ts</code></td><td>195</td><td>System + user context</td></tr>
|
|
1102
|
+
<tr><td><code>history.ts</code></td><td>451</td><td>Prompt history persistence</td></tr>
|
|
1103
|
+
<tr><td><code>cost-tracker.ts</code></td><td>350</td><td>Token/cost accounting</td></tr>
|
|
1104
|
+
<tr><td><code>bridgeMain.ts</code></td><td>2,651</td><td>v1 bridge daemon</td></tr>
|
|
1105
|
+
<tr><td><code>replBridge.ts</code></td><td>2,166</td><td>v1 REPL bridge</td></tr>
|
|
1106
|
+
<tr><td><code>mcp/auth.ts</code></td><td>2,207</td><td>MCP OAuth + XAA</td></tr>
|
|
1107
|
+
<tr><td><code>providers.json</code></td><td>2,197</td><td>AI provider definitions</td></tr>
|
|
1108
|
+
<tr><td><code>remoteBridgeCore.ts</code></td><td>861</td><td>v2 env-less bridge</td></tr>
|
|
1109
|
+
</table>
|
|
1110
|
+
</div>
|
|
1111
|
+
|
|
1112
|
+
</div>
|
|
1113
|
+
</div>
|
|
1114
|
+
|
|
1115
|
+
<br>
|
|
1116
|
+
|
|
1117
|
+
</div><!-- /container -->
|
|
1118
|
+
|
|
1119
|
+
<div class="footer">
|
|
1120
|
+
Generated from Clew Code v0.2.7 source — covers all 18 systems with verified architecture, data flow, and implementation details.
|
|
1121
|
+
</div>
|
|
1122
|
+
|
|
1123
|
+
</body>
|
|
1124
|
+
</html>
|
|
1125
|
+
|