clew-code 0.4.8 → 0.5.0
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 +435 -334
- package/dist/main.js +2318 -2307
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,334 +1,435 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<img src="assets/clew-logo-long.png" alt="Clew Code" width="520" />
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
<
|
|
9
|
-
<a href="https://github.com/ClewCode/ClewCode/
|
|
10
|
-
<a href="https://
|
|
11
|
-
<a href="https://
|
|
12
|
-
<a href="
|
|
13
|
-
<a href="
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
- [
|
|
39
|
-
- [
|
|
40
|
-
- [
|
|
41
|
-
- [
|
|
42
|
-
- [
|
|
43
|
-
- [
|
|
44
|
-
- [
|
|
45
|
-
- [
|
|
46
|
-
- [
|
|
47
|
-
- [
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
##
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
[
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="assets/clew-logo-long.png" alt="Clew Code" width="520" />
|
|
4
|
+
|
|
5
|
+
### *The agent that works where you do.*
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://github.com/ClewCode/ClewCode/stargazers"><img src="https://img.shields.io/github/stars/ClewCode/ClewCode?style=for-the-badge&color=blue" alt="GitHub stars"></a>
|
|
9
|
+
<a href="https://github.com/ClewCode/ClewCode/releases"><img src="https://img.shields.io/github/v/release/ClewCode/ClewCode?style=for-the-badge&color=orange" alt="Release"></a>
|
|
10
|
+
<a href="https://www.npmjs.com/package/clew-code"><img src="https://img.shields.io/npm/v/clew-code?style=for-the-badge&color=red" alt="npm"></a>
|
|
11
|
+
<a href="https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ClewCode/ClewCode/ci.yml?branch=main&style=for-the-badge" alt="CI"></a>
|
|
12
|
+
<a href="LICENSE.md"><img src="https://img.shields.io/badge/License-GPL--3.0-blue.svg?style=for-the-badge" alt="License"></a>
|
|
13
|
+
<a href="https://bun.sh"><img src="https://img.shields.io/badge/built%20with-Bun-ff69b4.svg?style=for-the-badge" alt="Bun"></a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<a href="https://clew-code.org">Website</a> · <a href="https://clew-docs.pages.dev">Docs</a> · <a href="https://github.com/ClewCode/ClewCode/wiki">Wiki</a> · <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<img src="assets/screenshots/clew-code-repl.png" alt="Clew Code REPL" width="680" />
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
Clew Code is a terminal-native AI coding agent that lives in your repo, works with your API keys, and **doesn't phone home**. It reads your code, writes files, runs commands, and talks to any LLM you bring — Claude, GPT, Gemini, DeepSeek, local Ollama models, and 20+ others — all on your machine, no telemetry, no vendor lock-in.
|
|
31
|
+
|
|
32
|
+
If you want a coding assistant that feels local, fast, and doesn't ship your context to a third-party server, this is it.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Table of Contents
|
|
37
|
+
|
|
38
|
+
- [Prerequisites](#prerequisites)
|
|
39
|
+
- [Quick Install](#quick-install)
|
|
40
|
+
- [Getting Started](#getting-started)
|
|
41
|
+
- [Usage Examples](#usage-examples)
|
|
42
|
+
- [Features](#features)
|
|
43
|
+
- [Use Cases](#use-cases)
|
|
44
|
+
- [CLI Quick Reference](#cli-quick-reference)
|
|
45
|
+
- [Configuration](#configuration)
|
|
46
|
+
- [Security](#security)
|
|
47
|
+
- [Documentation](#documentation)
|
|
48
|
+
- [Architecture](#architecture)
|
|
49
|
+
- [Development](#development)
|
|
50
|
+
- [Contributing](#contributing)
|
|
51
|
+
- [Star History](#star-history)
|
|
52
|
+
- [License](#license)
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Prerequisites
|
|
57
|
+
|
|
58
|
+
- **Node.js** 18+ or **Bun** 1.x (recommended for development)
|
|
59
|
+
- An **API key** from at least one supported provider (see [Providers docs](https://clew-docs.pages.dev/providers))
|
|
60
|
+
- *Optional:* Git, Playwright (for browser automation), microphone (for voice input)
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Quick Install
|
|
65
|
+
|
|
66
|
+
### macOS / Linux
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
curl -fsSL https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.sh | bash
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Windows (PowerShell)
|
|
73
|
+
|
|
74
|
+
```powershell
|
|
75
|
+
irm https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.ps1 | iex
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### npm (cross-platform)
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npm install -g clew-code
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
This installs two equivalent binaries: `clew` and `clewcode`.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Getting Started
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
cd your-project
|
|
92
|
+
clew # Launch the REPL
|
|
93
|
+
clew -p "fix the tests" # One-shot mode
|
|
94
|
+
clew --resume last # Pick up where you left off
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
First launch walks you through provider setup — pick a provider (Claude, OpenAI, Gemini, OpenRouter, etc.) and enter an API key. This is saved to your local config, never committed. After that, use `/model` to switch providers mid-session.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Usage Examples
|
|
102
|
+
|
|
103
|
+
### Ask questions about a codebase
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
> how does authentication work in this repo?
|
|
107
|
+
> where is the retry logic for API calls defined?
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Clew Code searches and reads files on its own — no need to paste code in.
|
|
111
|
+
|
|
112
|
+
### Make a change
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
> refactor the UserCard component to use the new Avatar component
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
It reads the relevant files, edits them, and shows a diff-style summary of what changed. Prompts for permission before writing, unless you've set an auto-approve rule.
|
|
119
|
+
|
|
120
|
+
### Fix and verify
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
> fix the bug in src/utils/parser.ts where empty arrays throw
|
|
124
|
+
> run the test suite and fix any failures
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Combines file edits with the Bash tool (`npm test` / `bun test`), looping until tests pass or it needs your input.
|
|
128
|
+
|
|
129
|
+
### Slash commands
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
/help # list all commands
|
|
133
|
+
/model # switch LLM provider/model mid-session
|
|
134
|
+
/code-review # review the current diff for bugs
|
|
135
|
+
/debug # structured debugging workflow
|
|
136
|
+
/loop 5m /deploy-checklist # run a command on a recurring interval
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Run `/help` inside the REPL for the full, current list — commands grow over time via skills and plugins.
|
|
140
|
+
|
|
141
|
+
### Multi-file / multi-step work
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
> migrate all usages of the old Logger class to the new one across src/
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
For larger jobs, Clew Code plans the work (`/plan`, or automatically for complex asks), then executes step by step, checking in at natural checkpoints. `/rewind` restores code or conversation to any prior checkpoint if something goes wrong.
|
|
148
|
+
|
|
149
|
+
### Research a codebase or topic
|
|
150
|
+
|
|
151
|
+
```
|
|
152
|
+
> /research "How does auth work in this repo?"
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Searches code, docs, and the web, then compiles a dossier with source references.
|
|
156
|
+
|
|
157
|
+
### Connect external tools (MCP)
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
> list open PRs assigned to me and summarize what's blocking each one
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Wire in GitHub, Slack, a database, or any [Model Context Protocol](https://modelcontextprotocol.io) server via `/mcp`, and use it from the same session.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Features
|
|
168
|
+
|
|
169
|
+
<table>
|
|
170
|
+
<tr>
|
|
171
|
+
<td><strong>29+ Providers</strong></td>
|
|
172
|
+
<td>OpenAI, Anthropic, DeepSeek, Groq, Google, Ollama (local), and 22+ more. Switch mid-session with <code>/model</code>. No lock-in.</td>
|
|
173
|
+
</tr>
|
|
174
|
+
<tr>
|
|
175
|
+
<td><strong>Persistent Memory</strong></td>
|
|
176
|
+
<td>SQLite-backed store with importance ranking, confidence scoring, and cross-session persistence. Auto-consolidation via Dream + Distill.</td>
|
|
177
|
+
</tr>
|
|
178
|
+
<tr>
|
|
179
|
+
<td><strong>76+ Tools</strong></td>
|
|
180
|
+
<td>Read, Write, Edit, Grep, Bash, Browser, MCP, LSP, git, web search, task management, peer coordination, media generation, voice input.</td>
|
|
181
|
+
</tr>
|
|
182
|
+
<tr>
|
|
183
|
+
<td><strong>LAN Peer Swarm</strong></td>
|
|
184
|
+
<td>Zero-config peer discovery over UDP multicast. Sync memory across machines, delegate tasks, broadcast shell commands with worktree isolation and dependency ordering.</td>
|
|
185
|
+
</tr>
|
|
186
|
+
<tr>
|
|
187
|
+
<td><strong>MCP + Plugins + Skills</strong></td>
|
|
188
|
+
<td>Model Context Protocol over stdio/SSE/WebSocket. Extend with plugins, <code>SKILL.md</code> workflows, or lifecycle hooks.</td>
|
|
189
|
+
</tr>
|
|
190
|
+
<tr>
|
|
191
|
+
<td><strong>Enterprise Audit Logging</strong></td>
|
|
192
|
+
<td>SIEM-compatible NDJSON audit trail with rotation, filtering, and level-based capture. Records tool calls, file access, and command execution.</td>
|
|
193
|
+
</tr>
|
|
194
|
+
<tr>
|
|
195
|
+
<td><strong>Project Rules</strong></td>
|
|
196
|
+
<td>Auto-observed behavioral rules scoped to your repo via <code>/rule</code>. Configured in <code>.clew/rules.json</code> — Clew reads and follows them without being reminded.</td>
|
|
197
|
+
</tr>
|
|
198
|
+
<tr>
|
|
199
|
+
<td><strong>Ultracode Reasoning</strong></td>
|
|
200
|
+
<td>Max-effort reasoning mode (<code>/ultracode</code> or <code>--effort max</code>) for complex debugging, architecture design, and multi-step refactoring.</td>
|
|
201
|
+
</tr>
|
|
202
|
+
<tr>
|
|
203
|
+
<td><strong>Rewind / Undo</strong></td>
|
|
204
|
+
<td><code>/rewind</code> restores code and/or conversation to any previous checkpoint. Integrated with structured 20%/45%/70% progress snapshots.</td>
|
|
205
|
+
</tr>
|
|
206
|
+
<tr>
|
|
207
|
+
<td><strong>Cross-Repo Workspace</strong></td>
|
|
208
|
+
<td><code>/workspace link ../other-repo</code> — edit across linked projects with full context loaded from both. Bidirectional and persistent.</td>
|
|
209
|
+
</tr>
|
|
210
|
+
<tr>
|
|
211
|
+
<td><strong>Background Daemon</strong></td>
|
|
212
|
+
<td>Task queue with lease-based concurrency, cron scheduling, dead-letter retries, memory consolidation, and cross-session task persistence.</td>
|
|
213
|
+
</tr>
|
|
214
|
+
<tr>
|
|
215
|
+
<td><strong>Multi-Agent Architecture</strong></td>
|
|
216
|
+
<td>Agents, Subagents, LAN Peers, Process Peers. Personal profile turns Clew into a command center that delegates to worker agents.</td>
|
|
217
|
+
</tr>
|
|
218
|
+
</table>
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## Use Cases
|
|
223
|
+
|
|
224
|
+
| Scenario | How Clew Code Helps |
|
|
225
|
+
|---|---|
|
|
226
|
+
| **Fix failing tests** | `clew -p "Fix the failing tests and explain what was wrong"` — reads test output, diagnoses root cause, applies fixes. |
|
|
227
|
+
| **Refactor a module** | Point it at a file, describe the target structure. Uses multi-file edit tools, git status awareness, and checkpoint rollback on mistakes. |
|
|
228
|
+
| **Research a codebase** | `/research "How does auth work?"` — searches code, docs, and web, then compiles a dossier with source references. |
|
|
229
|
+
| **Background automation** | Run `/bg` to delegate long-running tasks (migration, lint fixes) to a background agent while you keep working in the REPL. |
|
|
230
|
+
| **Cross-repo changes** | `/workspace link ../other-repo` — edit across linked projects with full context from both. |
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## CLI Quick Reference
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
-p, --prompt <text> One-shot prompt, then exit
|
|
238
|
+
-c, --continue Continue last conversation
|
|
239
|
+
-r, --resume [id] Resume a session (opens picker if no id)
|
|
240
|
+
--model <model> Override model (sonnet, opus, gemini-2.5-flash, etc.)
|
|
241
|
+
--effort <level> Reasoning effort (low|medium|high|max)
|
|
242
|
+
--agent <agent> Custom agent profile
|
|
243
|
+
--permission-mode <mode> default|ask|plan|auto
|
|
244
|
+
--peer-share Start as a LAN worker peer
|
|
245
|
+
--computer Enable OS-level computer use (Windows only)
|
|
246
|
+
--debug Developer debug output
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Notable slash commands: `/model`, `/effort`, `/ultracode`, `/memory`, `/rule`, `/task`, `/goal`, `/compact`, `/rewind`, `/workspace`, `/peer`, `/mcp`, `/agent`, `/plan`, `/voice`, `/research`, `/workflow`, `/skills`, `/code-review`, `/guardian`, `/bg`, `/daemon`, `/buddy`, `/doctor`, `/stats`, `/cost`, `/session`, `/diff`, `/fork`, `/theme`, and [many more](https://clew-docs.pages.dev/cli).
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Configuration
|
|
254
|
+
|
|
255
|
+
### Environment Variables
|
|
256
|
+
|
|
257
|
+
| Variable | Required | Description |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| `ANTHROPIC_API_KEY` | No | Anthropic Claude models |
|
|
260
|
+
| `OPENAI_API_KEY` | No | OpenAI GPT models |
|
|
261
|
+
| `DEEPSEEK_API_KEY` | No | DeepSeek models |
|
|
262
|
+
| `GOOGLE_API_KEY` | No | Google Gemini models |
|
|
263
|
+
| `GROQ_API_KEY` | No | Groq-hosted models |
|
|
264
|
+
| `TAVILY_API_KEY` | No | Enhanced web search provider |
|
|
265
|
+
| `CLEW_DISABLE_TELEMETRY` | No | Disable anonymous usage stats (`1`) |
|
|
266
|
+
|
|
267
|
+
All provider keys can also be set via the `/model` provider setup flow or in `.clew/settings.json` under `env`.
|
|
268
|
+
|
|
269
|
+
### Project Rules
|
|
270
|
+
|
|
271
|
+
Create `.clew/rules.json` in your repo to define auto-observed behavioral rules — Clew reads them at session start and follows them without being reminded. Manage them interactively with `/rule`. Disable temporarily with `/rule off`.
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{
|
|
275
|
+
"rules": [
|
|
276
|
+
"Always use the project's existing test framework for new tests",
|
|
277
|
+
"Prefer named exports over default exports"
|
|
278
|
+
]
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Enterprise Audit Logging
|
|
283
|
+
|
|
284
|
+
Audit logging is opt-in and writes newline-delimited JSON events for SIEM ingestion. When enabled, Clew records tool calls, tool results/failures, file read/write access, and Bash/PowerShell command execution/results.
|
|
285
|
+
|
|
286
|
+
| Variable | Required | Description |
|
|
287
|
+
|---|---|---|
|
|
288
|
+
| `CLEW_AUDIT_LOG` | No | Enable audit logging when set to `1` |
|
|
289
|
+
| `CLEW_AUDIT_LOG_PATH` | No | Audit log directory, relative to the project root by default (`.clew/audit`) |
|
|
290
|
+
| `CLEW_AUDIT_LOG_MAX_BYTES` | No | Rotate `audit.ndjson` after this size in bytes (default: 100 MB) |
|
|
291
|
+
| `CLEW_AUDIT_LOG_MAX_FILES` | No | Number of audit log files to retain, including the active file (default: 10) |
|
|
292
|
+
| `CLEW_AUDIT_LOG_INCLUDE` | No | Comma-separated event allowlist, such as `tool.call,tool.result` |
|
|
293
|
+
| `CLEW_AUDIT_LOG_EXCLUDE` | No | Comma-separated event blocklist |
|
|
294
|
+
| `CLEW_AUDIT_LOG_MIN_LEVEL` | No | Minimum level to write: `info`, `warn`, `error`, or `audit` |
|
|
295
|
+
| `CLEW_AUDIT_LOG_CONSOLE` | No | Also mirror audit summaries to stderr when set to `1` |
|
|
296
|
+
| `CLEW_AUDIT_USER` | No | User identifier to include in each audit event |
|
|
297
|
+
|
|
298
|
+
Example:
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
CLEW_AUDIT_LOG=1 CLEW_AUDIT_LOG_PATH=.clew/audit bun run dev
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## Security
|
|
307
|
+
|
|
308
|
+
Clew Code runs entirely on your machine. No code or context leaves your network unless you explicitly configure a remote provider or send a web fetch.
|
|
309
|
+
|
|
310
|
+
- Prompts for permission before read, write, or terminal execution
|
|
311
|
+
- Fine-tune auto-approve rules per workspace
|
|
312
|
+
- Permission scopes: default, ask, plan, auto
|
|
313
|
+
- Guardian system for auto-review using a secondary LLM
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## Documentation
|
|
318
|
+
|
|
319
|
+
| Guide | Description |
|
|
320
|
+
|---|---|
|
|
321
|
+
| [Quick Start](https://clew-docs.pages.dev/quick-start) | Launch the CLI and start coding |
|
|
322
|
+
| [Installation](https://clew-docs.pages.dev/installation) | One-liner, npm, or build from source |
|
|
323
|
+
| [CLI Reference](https://clew-docs.pages.dev/cli) | Full CLI options, providers, commands |
|
|
324
|
+
| [Configuration](https://clew-docs.pages.dev/configuration) | Settings files, hooks, permission modes |
|
|
325
|
+
| [MCP Guide](https://clew-docs.pages.dev/mcp) | Connect external tools and APIs |
|
|
326
|
+
| [Plugins](https://clew-docs.pages.dev/plugins) | Lifecycle hooks and customization |
|
|
327
|
+
| [Security & Permissions](https://clew-docs.pages.dev/security-permissions) | Permission scopes, guardian system |
|
|
328
|
+
| [Skills System](https://clew-docs.pages.dev/skills) | Automate repeatable workflows |
|
|
329
|
+
| [Memory System](https://clew-docs.pages.dev/memory-system) | SQLite-backed long-term memory |
|
|
330
|
+
| [Peer-to-Peer LAN](https://clew-docs.pages.dev/peer-to-peer) | Discover, delegate, swarm commands |
|
|
331
|
+
| [Architecture](https://clew-docs.pages.dev/concepts-agents-subagents-peers) | Agents, Subagents, Peers |
|
|
332
|
+
| [Troubleshooting](https://clew-docs.pages.dev/troubleshooting) | Common issues and fixes |
|
|
333
|
+
|
|
334
|
+
Also available on the [GitHub Wiki](https://github.com/ClewCode/ClewCode/wiki).
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Architecture
|
|
339
|
+
|
|
340
|
+
```
|
|
341
|
+
┌─ REPL ─────────────────────────────┐
|
|
342
|
+
│ Ink + React 19 ┌───────┐ │
|
|
343
|
+
│ Slash commands / skills │ Tools │ │
|
|
344
|
+
│ Streaming / history └───┬───┘ │
|
|
345
|
+
└────────┬─────────────────────┘ │
|
|
346
|
+
▼ │
|
|
347
|
+
┌─ QueryEngine ──────────────────────┘
|
|
348
|
+
│ Tool loop · Provider routing · Streaming
|
|
349
|
+
│ Context compaction · Checkpoints
|
|
350
|
+
└──┬────┬────┬────┬────┐
|
|
351
|
+
▼ ▼ ▼ ▼ ▼
|
|
352
|
+
┌────┐┌────┐┌────┐┌────┐┌──────────┐
|
|
353
|
+
│ MCP││LSP ││Git ││Web ││ Provider │
|
|
354
|
+
│ ││ ││ ││ ││ Manager │
|
|
355
|
+
└────┘└────┘└────┘└────┘└──────────┘
|
|
356
|
+
│ LAN │
|
|
357
|
+
▼ ▼ ▼
|
|
358
|
+
┌──────┐┌──────────┐┌──────────────┐
|
|
359
|
+
│ SQLite││ Peer ││ AgentRuntime │
|
|
360
|
+
│Memory ││ Server ││ Task Queue │
|
|
361
|
+
└──────┘└──────────┘└──────────────┘
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
- **Entry**: `src/main.tsx` → `src/replLauncher.tsx` boots the Ink/React 19 REPL
|
|
365
|
+
- **REPL screen**: `src/screens/REPL.tsx` routes input to commands or the query engine
|
|
366
|
+
- **Query loop**: `src/QueryEngine.ts` — message construction, tool loop, provider routing, streaming
|
|
367
|
+
- **Providers**: `src/services/ai/` — 29 providers behind one interface, normalized errors/usage
|
|
368
|
+
- **Tools**: `src/tools/<ToolName>/`, each extending `Tool` from `src/Tool.ts`, registered in `src/tools.ts`
|
|
369
|
+
- **Services**: `src/services/` — MCP client, autonomous task queue, memory consolidation, session search, plugin lifecycle hooks, and more
|
|
370
|
+
|
|
371
|
+
Full detail, including the tool inventory and service list: [AGENTS.md](AGENTS.md).
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Development
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
git clone https://github.com/ClewCode/ClewCode.git
|
|
379
|
+
cd ClewCode
|
|
380
|
+
bun install
|
|
381
|
+
bun run dev # Live-reload REPL (with feature flags)
|
|
382
|
+
bun run dev:channels # Dev with development channels loaded
|
|
383
|
+
bun run build # Production build to dist/
|
|
384
|
+
bun run start # Run the compiled build
|
|
385
|
+
bun test # Vitest suite
|
|
386
|
+
bun test --bail # Stop on first failure
|
|
387
|
+
npx vitest run path/to/file.test.ts # Single file
|
|
388
|
+
npx vitest run -t "test name" # By test name
|
|
389
|
+
bun run check:ci # Biome lint + format check (no autofix)
|
|
390
|
+
bun run lint # Biome lint with autofix
|
|
391
|
+
bun run check # Lint + format with autofix
|
|
392
|
+
bun x tsc --noEmit # TypeScript check only
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
### Full Pre-Push Gate
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
bun run check:ci && bun x tsc --noEmit && bun test --bail
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
Or run the `/clew-verify` skill, which runs the full gate and a real CLI smoke test — green tests alone don't prove an Ink TUI feature actually works.
|
|
402
|
+
|
|
403
|
+
### ✅ Shadow `.js` Files — Resolved
|
|
404
|
+
|
|
405
|
+
The JS→TS migration is complete. All 401 `.js` shadow files that sat alongside `.ts`/`.tsx` twins have been removed. **Zero shadow pairs remain** — the `/js-shadow-sync` skill has been removed.
|
|
406
|
+
|
|
407
|
+
Any `.js` file still in `src/` is a genuine JS source module (no `.ts` twin exists).
|
|
408
|
+
|
|
409
|
+
### Release
|
|
410
|
+
|
|
411
|
+
Pushing a `v*` tag triggers the GitHub Actions release and npm publish. Before tagging: bump `package.json`, update `CHANGELOG.md`, run the full gate above. See [AGENTS.md § Release](AGENTS.md#release) or run the `/clew-release` skill.
|
|
412
|
+
|
|
413
|
+
---
|
|
414
|
+
|
|
415
|
+
## Contributing
|
|
416
|
+
|
|
417
|
+
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
418
|
+
|
|
419
|
+
- Report bugs via [GitHub Issues](https://github.com/ClewCode/ClewCode/issues)
|
|
420
|
+
- Discuss ideas in [GitHub Discussions](https://github.com/ClewCode/ClewCode/discussions)
|
|
421
|
+
- Read [AGENTS.md](AGENTS.md) for full architecture and code conventions
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
## Star History
|
|
426
|
+
|
|
427
|
+
[](https://star-history.com/#ClewCode/ClewCode&Date)
|
|
428
|
+
|
|
429
|
+
---
|
|
430
|
+
|
|
431
|
+
## License
|
|
432
|
+
|
|
433
|
+
GPL-3.0. See [LICENSE.md](LICENSE.md).
|
|
434
|
+
|
|
435
|
+
Release history in [CHANGELOG.md](CHANGELOG.md).
|