compact-agent 1.1.0 → 1.2.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 +344 -394
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -1
- package/dist/query.js +46 -9
- package/dist/query.js.map +1 -1
- package/dist/stitch.d.ts +46 -0
- package/dist/stitch.js +278 -0
- package/dist/stitch.js.map +1 -0
- package/dist/theme.d.ts +2 -1
- package/dist/theme.js +67 -18
- package/dist/theme.js.map +1 -1
- package/dist/tools/index.js +8 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/stitch.d.ts +14 -0
- package/dist/tools/stitch.js +84 -0
- package/dist/tools/stitch.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,394 +1,344 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
/ecc-skills — list ECC skills
|
|
346
|
-
/ecc-agents — list ECC agents
|
|
347
|
-
/ecc-commands — list ECC-only commands
|
|
348
|
-
/ecc-feature-development — feature implementation workflow
|
|
349
|
-
/ecc-add-language-rules — add language-specific rule files
|
|
350
|
-
/ecc-database-migration — database migration workflow
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
Any `/ecc-<command-name>` dynamic dispatch is also supported for commands in `~/.crowcoder/ecc-commands/`.
|
|
354
|
-
|
|
355
|
-
### Skill auto-injection
|
|
356
|
-
|
|
357
|
-
When you send a prompt that matches an ECC skill's triggers
|
|
358
|
-
(e.g. asking about *TDD*, *bun*, *e2e testing*, *MCP servers*, *frontend slides*),
|
|
359
|
-
the highest-scoring skill's body is auto-injected into the system prompt for
|
|
360
|
-
that turn. Skills also appear in `/skills` so you can invoke them by trigger
|
|
361
|
-
matching from any prompt.
|
|
362
|
-
|
|
363
|
-
### ECC hooks (security)
|
|
364
|
-
|
|
365
|
-
Five native hooks are installed (auto-disabled if you remove them from
|
|
366
|
-
`~/.crowcoder/hooks.json`):
|
|
367
|
-
|
|
368
|
-
| Event | Match | Behavior |
|
|
369
|
-
|-------------|-------------|--------------------------------------------------|
|
|
370
|
-
| PreToolUse | `bash` | Block `git ... --no-verify` and `--no-gpg-sign` |
|
|
371
|
-
| PreToolUse | `bash` | Remind to run dev servers under tmux (non-blocking) |
|
|
372
|
-
| PreToolUse | `read_file` | Warn when reading `.env / .key / .pem / credentials*` |
|
|
373
|
-
| PostToolUse | `edit_file` | Warn when an edit leaves `console.*` statements |
|
|
374
|
-
| PostToolUse | `write_file`| Same console-statement warning on new files |
|
|
375
|
-
|
|
376
|
-
All hook entries are tagged `__ecc__` so `/ecc-install` can refresh them
|
|
377
|
-
without touching hooks you've defined yourself.
|
|
378
|
-
|
|
379
|
-
### Rebuilding bundled ECC resources
|
|
380
|
-
|
|
381
|
-
The bundled `resources/ecc/` is a frozen snapshot of the upstream repo. To
|
|
382
|
-
refresh from upstream:
|
|
383
|
-
|
|
384
|
-
```bash
|
|
385
|
-
git -C /e/ecc-mirror/everything-claude-code pull
|
|
386
|
-
# then re-copy: skills, agents, commands, rules, prompts
|
|
387
|
-
# (run /ecc-install afterwards to re-import)
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
---
|
|
391
|
-
|
|
392
|
-
## License
|
|
393
|
-
|
|
394
|
-
MIT
|
|
1
|
+
|
|
2
|
+
# Compact Agent
|
|
3
|
+
|
|
4
|
+
**A dense, feature-rich AI coding agent for the terminal.**
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/compact-agent)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://nodejs.org/)
|
|
9
|
+
[](https://www.typescriptlang.org/)
|
|
10
|
+
[](https://github.com/nousresearch/hermes-agent)
|
|
11
|
+
[](https://github.com/Crownelius/everything-claude-code)
|
|
12
|
+
|
|
13
|
+
Compact Agent is a single-command terminal AI coding CLI. It speaks any OpenAI-compatible API (OpenRouter, OpenAI, Anthropic via compatible endpoints, Ollama, LM Studio, DeepSeek, GLM). It ships with **80+ slash commands**, **8 operation modes** including the self-improving **Hermes** mode, the bundled **everything-claude-code** skill library, multi-agent orchestration, a cross-session learning system, and zero telemetry.
|
|
14
|
+
|
|
15
|
+
[Features](#-features) • [Modes](#-operation-modes) • [Skills](#-skills-system) • [Tools](#-tool-arsenal) • [Providers](#-supported-providers) • [Installation](#-installation) • [Commands](#-slash-commands) • [Privacy](#-privacy) • [Architecture](#-architecture)
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## ✨ Features
|
|
20
|
+
|
|
21
|
+
- **Single-command install** — `npm install -g compact-agent && compact-agent`. No clone, no build step, no Docker, no IDE extension.
|
|
22
|
+
- **Universal LLM transport** — works with any OpenAI-compatible API. Switch providers and models from inside the REPL with `/model`, `/provider`, `/route`.
|
|
23
|
+
- **8 operation modes** — `dev`, `review`, `tdd`, `research`, `plan`, `debug`, `architect`, and `hermes` (self-improving learning loop). Each rewrites the system prompt to bias the agent toward its specific workflow.
|
|
24
|
+
- **Hermes self-improving mode** — recalls prior sessions, models the user across conversations, parallelizes independent subtasks, distills new skills from experience, and proposes what's worth banking before finishing. Inspired by [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent).
|
|
25
|
+
- **Bundled everything-claude-code library** — 33 high-quality skills, 16 agents, 9 workflow commands, 7 language rule bundles, and 5 default security hooks. Auto-installed on first launch via [Crownelius/everything-claude-code](https://github.com/Crownelius/everything-claude-code).
|
|
26
|
+
- **Unified slash-command surface** — `/tdd`, `/review`, `/security-review`, `/plan`, `/refactor`, `/build-fix` automatically use the ECC prompts when ECC is installed. **No `/ecc-tdd` vs `/tdd` duplication.**
|
|
27
|
+
- **Multi-agent orchestration** — `/orchestrate`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/pr-loop` spawn parallel sub-tasks against the same project.
|
|
28
|
+
- **10 language-specific reviewers** — `/auto-review` (auto-detects the language) plus dedicated reviewers for TS, Python, Go, Rust, Java, C++, Kotlin, PHP, and SQL.
|
|
29
|
+
- **6 language-specific build fixers** — `/ts-build-fix`, `/go-build-fix`, `/rust-build-fix`, `/java-build-fix`, `/cpp-build-fix`, `/pytorch-fix`.
|
|
30
|
+
- **Learning system** — `/learn` extracts patterns from the current session into confidence-scored instincts. `/evolve` promotes high-confidence instincts into reusable skills. Confidence decays automatically; `/prune` removes stale patterns.
|
|
31
|
+
- **Cross-session memory** — `~/.crowcoder/memory/` retains project context across sessions. Hermes mode searches it before answering.
|
|
32
|
+
- **Sessions & checkpoints** — `/sessions`, `/save`, `/resume`, `/delete` for full session snapshots; `/checkpoint` for git-state snapshots inside a session.
|
|
33
|
+
- **Agent-led walkthrough** — type `/walkthrough` (or `/tour`, `/guide`) and the agent walks new users through every feature interactively.
|
|
34
|
+
- **Native security hooks** — by default, block `git --no-verify`, warn on reading `.env`/`.key`/`.pem`, warn when an edit leaves `console.*` statements, suggest tmux for long-running dev servers. Fully configurable in `~/.crowcoder/hooks.json`.
|
|
35
|
+
- **Permission modes** — `/perm ask` prompts before every tool use, `/perm auto` allows non-destructive ops, `/perm yolo` approves everything. Per-tool dry-run via `/dry-run`.
|
|
36
|
+
- **Cost & budget tracking** — `/usage`, `/budget` keep token counts and cost estimates entirely local in `~/.crowcoder/usage.json`. Cost-aware routing via `/route`.
|
|
37
|
+
- **Real web search** — `web_search` tool backed by DuckDuckGo Lite (no API key). The LLM gets unknown-tool errors with the valid tool list so free models that hallucinate `web_search_exa` can self-correct.
|
|
38
|
+
- **Google Stitch integration** — `/stitch <query>` interface to [Stitch](https://stitch.withgoogle.com/), Google's AI UI/UX design tool. List projects, generate UI from text, enhance design prompts. Ports the [gemini-cli-extensions/stitch](https://github.com/gemini-cli-extensions/stitch) extension; API-key auth.
|
|
39
|
+
- **Zero telemetry** — no analytics SDKs, no phone-home, no crash reporting. The only network calls are to your chosen LLM provider when you send a message.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 🧠 Operation Modes
|
|
44
|
+
|
|
45
|
+
Switchable any time with `/mode <name>`. Each mode injects a specialized system-prompt addition.
|
|
46
|
+
|
|
47
|
+
### ⚡ dev — *default*
|
|
48
|
+
|
|
49
|
+
General coding. Write features, fix bugs, refactor. Reads files before editing, prefers minimal changes.
|
|
50
|
+
|
|
51
|
+
### 🔍 review
|
|
52
|
+
|
|
53
|
+
Code review with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW). Confidence-filtered: only reports issues the model is >80% sure about.
|
|
54
|
+
|
|
55
|
+
### 🧪 tdd
|
|
56
|
+
|
|
57
|
+
Strict RED → GREEN → REFACTOR cycle. Will **not** write implementation before a failing test. Lower temperature for tighter cycles.
|
|
58
|
+
|
|
59
|
+
### 🔭 research
|
|
60
|
+
|
|
61
|
+
Read-only exploration. The agent reads code, traces execution paths, maps architecture, and reports — without modifying files.
|
|
62
|
+
|
|
63
|
+
### 📋 plan
|
|
64
|
+
|
|
65
|
+
Design before building. Produces numbered step-by-step plans with file paths, trade-offs, and risk assessment. Does **not** write code in this mode.
|
|
66
|
+
|
|
67
|
+
### 🐛 debug
|
|
68
|
+
|
|
69
|
+
Systematic root-cause hunting. Reproduce → hypothesize → narrow → fix → verify. Never guesses — always confirms with evidence.
|
|
70
|
+
|
|
71
|
+
### 🏛 architect
|
|
72
|
+
|
|
73
|
+
System-level design. Component boundaries, data flow, technology choices, scalability, API design, database schemas, deployment.
|
|
74
|
+
|
|
75
|
+
### 🜲 hermes
|
|
76
|
+
|
|
77
|
+
**The agent that grows with you.** Recalls prior sessions and instincts before answering, builds a model of the user across conversations, parallelizes independent subtasks, distills skills from experience, nudges to persist knowledge at end of work, and proactively suggests scheduled follow-ups.
|
|
78
|
+
|
|
79
|
+
Activate with `/hermes` or `/mode hermes`.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 🛠 Skills System
|
|
84
|
+
|
|
85
|
+
Skills are reusable prompt templates stored in `~/.crowcoder/skills/`. Three sources:
|
|
86
|
+
|
|
87
|
+
| Source | Stored as | Origin |
|
|
88
|
+
| :--- | :--- | :--- |
|
|
89
|
+
| **ECC bundled** | `ecc-<name>.json` | The 33 skills from [everything-claude-code](https://github.com/Crownelius/everything-claude-code), auto-installed on first launch |
|
|
90
|
+
| **ECC agents** | `ecc-agent-<name>.json` | 16 specialized agent prompts (code-reviewer, planner, doc-updater, etc.) |
|
|
91
|
+
| **Your own** | `<id>.json` | Created via `/skill-create` (distilled from git patterns) or `/evolve` (promoted from high-confidence instincts) |
|
|
92
|
+
|
|
93
|
+
When you send a message, Compact Agent auto-matches the highest-scoring skill against your query and injects its body into the system prompt for that turn. Browse with `/skills`, filter to ECC with `/ecc-skills`.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 🔧 Tool Arsenal
|
|
98
|
+
|
|
99
|
+
The LLM has access to these tools. Each call is gated by your permission mode (`ask`/`auto`/`yolo`).
|
|
100
|
+
|
|
101
|
+
| Tool | Description | R/W |
|
|
102
|
+
| :--- | :--- | :---: |
|
|
103
|
+
| `bash` | Run a shell command. Spawns via Git Bash on Windows, `/bin/bash` elsewhere. | RW |
|
|
104
|
+
| `read_file` | Read a file with paging + size limits. | R |
|
|
105
|
+
| `write_file` | Create or overwrite a file. Auto-creates parent dirs. | W |
|
|
106
|
+
| `edit_file` | Find-and-replace within a file with optional `replace_all`. | W |
|
|
107
|
+
| `grep` | Search file contents. Uses ripgrep when available, falls back to grep. | R |
|
|
108
|
+
| `glob` | Find files by glob pattern (e.g. `src/**/*.ts`). | R |
|
|
109
|
+
| `list_dir` | List directory entries (type, size, name). | R |
|
|
110
|
+
| `web_fetch` | Fetch a URL and convert HTML → readable text. | R |
|
|
111
|
+
| `web_search` | Keyword search via DuckDuckGo Lite. Returns title/URL/snippet. No API key required. | R |
|
|
112
|
+
| `stitch` | Google Stitch MCP server — 12 tools across Project Management, Screen Management, AI Generation (gemini-3-flash / -pro, slow), and Design Systems. Auto-registered when `/stitch-config` has saved an API key. | RW |
|
|
113
|
+
|
|
114
|
+
Unknown-tool calls are intercepted: when a free model hallucinates `web_search_exa`, `TodoWrite`, or similar, the error response lists the valid tool names so the model self-corrects on the next iteration.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## 🌐 Supported Providers
|
|
119
|
+
|
|
120
|
+
| Provider | Base URL | Notes |
|
|
121
|
+
| :--- | :--- | :--- |
|
|
122
|
+
| **OpenRouter** | `https://openrouter.ai/api/v1` | One key, hundreds of models, free tier available. Recommended for new users. |
|
|
123
|
+
| **OpenAI** | `https://api.openai.com/v1` | GPT-4o / o-series. |
|
|
124
|
+
| **Anthropic** (via OpenRouter) | `https://openrouter.ai/api/v1` | Use `anthropic/claude-sonnet-4` etc. (native Anthropic API is not OpenAI-compatible). |
|
|
125
|
+
| **DeepSeek** | `https://api.deepseek.com/v1` | Cheap, strong on code. |
|
|
126
|
+
| **GLM (ZhipuAI)** | `https://open.bigmodel.cn/api/paas/v4` | GLM family. |
|
|
127
|
+
| **Ollama** | `http://localhost:11434/v1` | Local models — no API key needed. |
|
|
128
|
+
| **LM Studio** | `http://localhost:1234/v1` | Local models — no API key needed. |
|
|
129
|
+
| **Custom** | you provide | Anything that speaks OpenAI Chat Completions. |
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 📦 Installation
|
|
134
|
+
|
|
135
|
+
### Prerequisites
|
|
136
|
+
|
|
137
|
+
- [Node.js](https://nodejs.org/) **18 or newer** (tested on 18, 20, 22, 24)
|
|
138
|
+
- An API key from any supported provider (or use a local Ollama / LM Studio)
|
|
139
|
+
- A POSIX-like shell. Compact Agent spawns Git Bash for shell tools on Windows.
|
|
140
|
+
|
|
141
|
+
### Single-command install
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
npm install -g compact-agent
|
|
145
|
+
compact-agent
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
First run launches the setup wizard (provider, key, model, permission mode). After that, `compact-agent` from any directory drops you into the REPL.
|
|
149
|
+
|
|
150
|
+
### From source (development)
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
git clone https://github.com/Crownelius/Crowcoder.git
|
|
154
|
+
cd Crowcoder
|
|
155
|
+
npm install
|
|
156
|
+
npm link
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Rebuild after edits: `npx tsc` (or `npm run build`). The `prepare` script also runs `tsc` automatically on `npm install`, so a clean clone produces a working `dist/` without an extra step.
|
|
160
|
+
|
|
161
|
+
### Updating
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
npm install -g compact-agent@latest
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Uninstalling
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
npm uninstall -g compact-agent
|
|
171
|
+
rm -rf ~/.crowcoder # remove all local state (config, sessions, skills, ...)
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
See [INSTALL.md](INSTALL.md) for the full setup walkthrough including provider-specific tips and troubleshooting.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## ⌨ Slash commands
|
|
179
|
+
|
|
180
|
+
The most-used commands at a glance. See **[COMMANDS.md](COMMANDS.md)** for the complete reference (~80 commands).
|
|
181
|
+
|
|
182
|
+
| Command | Description |
|
|
183
|
+
| :--- | :--- |
|
|
184
|
+
| `/walkthrough` | Agent-led tour of every feature *(aliases: `/tour`, `/guide`)* |
|
|
185
|
+
| `/help` | Print the full command list |
|
|
186
|
+
| `/mode <name>` | Switch operation mode (dev/review/tdd/research/plan/debug/architect/hermes) |
|
|
187
|
+
| `/model [name]` | Switch model, or show the current one |
|
|
188
|
+
| `/perm <mode>` | Change permission mode (ask/auto/yolo) |
|
|
189
|
+
| `/tdd <feature>` | Test-driven workflow — tests first, then implementation |
|
|
190
|
+
| `/review [target]` | AI code review with severity ratings |
|
|
191
|
+
| `/orchestrate <task>` | Decompose a task and run sub-agents in parallel |
|
|
192
|
+
| `/skills` | List all skills (built-in, ECC bundled, learned) |
|
|
193
|
+
| `/learn` | Extract patterns from the current session into instincts |
|
|
194
|
+
| `/usage` | Show token + cost summary |
|
|
195
|
+
| `/audit` | Local-only project health check (no data leaves your machine) |
|
|
196
|
+
| `/export [md\|json\|txt]` | Save the current conversation to a file |
|
|
197
|
+
| `!<cmd>` | Run a shell command directly without involving the AI |
|
|
198
|
+
| `/exit` | Quit the REPL |
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## 🔒 Privacy
|
|
203
|
+
|
|
204
|
+
**Zero telemetry, zero analytics, zero phone-home.**
|
|
205
|
+
|
|
206
|
+
| Data | Where it goes |
|
|
207
|
+
| :--- | :--- |
|
|
208
|
+
| Conversation messages | Your chosen LLM provider only (required for the model to respond) |
|
|
209
|
+
| Token counts, costs | `~/.crowcoder/usage.json` — local file only, never transmitted |
|
|
210
|
+
| Sessions | `~/.crowcoder/sessions/*.json` — local files |
|
|
211
|
+
| Learned instincts & skills | `~/.crowcoder/instincts/`, `~/.crowcoder/skills/` — local files |
|
|
212
|
+
| Memory | `~/.crowcoder/memory/` — local files |
|
|
213
|
+
| API keys | `~/.crowcoder/config.json` — plaintext, local only. **Protect this file.** |
|
|
214
|
+
| Hook execution | All hooks run locally in your shell. No external calls. |
|
|
215
|
+
|
|
216
|
+
The `web_fetch` and `web_search` tools only contact URLs the agent decides to fetch in response to your request. There is no background telemetry, no crash reporting, no auto-update beacon.
|
|
217
|
+
|
|
218
|
+
**To remove everything:** `rm -rf ~/.crowcoder`.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 🪝 Default Hooks
|
|
223
|
+
|
|
224
|
+
Five hooks ship by default via the bundled everything-claude-code library. Configured in `~/.crowcoder/hooks.json` — disable any you don't want.
|
|
225
|
+
|
|
226
|
+
| Event | Match | Behavior |
|
|
227
|
+
| :--- | :--- | :--- |
|
|
228
|
+
| `PreToolUse` | `bash` | **Block** `git ... --no-verify` and `--no-gpg-sign` — they skip pre-commit hooks |
|
|
229
|
+
| `PreToolUse` | `bash` | Warn (non-blocking) when running a dev server outside tmux on POSIX |
|
|
230
|
+
| `PreToolUse` | `read_file` | Warn when reading `.env`, `.key`, `.pem`, or paths containing `credentials`/`secrets`/`id_rsa` |
|
|
231
|
+
| `PostToolUse` | `edit_file` | Warn when an edit leaves `console.log`/`console.warn`/`console.error` statements in `.ts`/`.js` files |
|
|
232
|
+
| `PostToolUse` | `write_file` | Same console-statement warning on new files |
|
|
233
|
+
|
|
234
|
+
Set `CROWCODER_HOOK_PROFILE=minimal` to silence all but the blocking ones. Set `=strict` to enable additional reminders (tmux prompts, git-push warnings). Write your own hooks by adding entries to `hooks.json` with `event`, `match`, `command`, `blocking`, `timeout`, `enabled`.
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 🏛 Architecture
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
src/
|
|
242
|
+
├── index.ts # REPL main loop + ~80 slash-command dispatcher
|
|
243
|
+
├── api.ts # OpenAI-compatible client (streaming, retries, 429-aware)
|
|
244
|
+
├── query.ts # Tool-call loop: stream chat → exec tools → feed back results
|
|
245
|
+
├── system-prompt.ts # System prompt assembly (env + mode + rules + ECC skill)
|
|
246
|
+
├── config.ts # ~/.crowcoder/config.json (CROWCODER_HOME-aware)
|
|
247
|
+
├── modes.ts # 8 operation modes — dev/review/tdd/research/plan/debug/architect/hermes
|
|
248
|
+
├── walkthrough.ts # /walkthrough — agent-led tour prompt
|
|
249
|
+
├── ecc.ts # everything-claude-code installer + skill/agent/command loader
|
|
250
|
+
├── stitch.ts # Google Stitch integration (MCP JSON-RPC client + prompt builder)
|
|
251
|
+
├── tools/ # 9 tools — each implements { name, parameters, call(input, cwd) }
|
|
252
|
+
│ ├── bash.ts # Shell exec with timeout, 10 MB buffer
|
|
253
|
+
│ ├── read.ts # Paged file read with size limit
|
|
254
|
+
│ ├── write.ts # File creation/overwrite, auto mkdir
|
|
255
|
+
│ ├── edit.ts # Find/replace with optional replace_all
|
|
256
|
+
│ ├── grep.ts # ripgrep with grep fallback
|
|
257
|
+
│ ├── glob.ts # File pattern matching
|
|
258
|
+
│ ├── list-dir.ts # Directory listing
|
|
259
|
+
│ ├── web-fetch.ts # URL fetch + HTML→text
|
|
260
|
+
│ ├── web-search.ts # DuckDuckGo Lite — no API key
|
|
261
|
+
│ ├── stitch.ts # Google Stitch MCP wrapper (opt-in via /stitch-config)
|
|
262
|
+
│ └── index.ts # ALL_TOOLS registry (stitch only listed when configured)
|
|
263
|
+
├── hooks.ts # PreToolUse / PostToolUse / SessionStart / SessionStop dispatcher
|
|
264
|
+
├── hook-controls.ts # Hook profile system (minimal/standard/strict)
|
|
265
|
+
├── permissions.ts # ask/auto/yolo gating per tool
|
|
266
|
+
├── security.ts # Dangerous-command + secret-write scanner
|
|
267
|
+
├── sessions.ts # ~/.crowcoder/sessions/*.json — save/load/resume
|
|
268
|
+
├── memory.ts # Cross-session project memory
|
|
269
|
+
├── learning.ts # Instincts: pattern extraction, confidence decay, pruning
|
|
270
|
+
├── skills.ts # Skill JSON store + trigger-based auto-injection
|
|
271
|
+
├── skill-create.ts # Distill new skills from git history patterns
|
|
272
|
+
├── orchestration.ts # /orchestrate + /multi-* parallel sub-agent prompts
|
|
273
|
+
├── autonomous-loops.ts # /pr-loop + multi-plan/multi-execute prompts
|
|
274
|
+
├── search-first.ts # /search-first /docs-lookup research-before-code prompts
|
|
275
|
+
├── modes.ts, codemaps.ts, compaction.ts, strategic-compaction.ts
|
|
276
|
+
├── verification.ts # /verify /test-coverage prompts + checkpoint helpers
|
|
277
|
+
├── refactor.ts # /refactor /refactor-clean prompts
|
|
278
|
+
├── evaluation.ts # /review /tdd /security-review /audit /plan prompts
|
|
279
|
+
├── content-engine.ts # /article /slides /investor-deck /chief-of-staff prompts
|
|
280
|
+
├── git-workflow.ts # /commit /pr /diff /log + branch helpers
|
|
281
|
+
├── agents.ts # 10 language-specific review + build-fix prompt builders
|
|
282
|
+
├── cost-tracker.ts # ~/.crowcoder/usage.json — token counts, cost estimates
|
|
283
|
+
├── model-router.ts # /route — complexity-based model switching
|
|
284
|
+
├── docs-sync.ts # /update-docs + project language detection
|
|
285
|
+
├── package-detect.ts # /detect — package manager / test runner / build tool
|
|
286
|
+
├── rules.ts # Language-specific coding rules (loaded into system prompt)
|
|
287
|
+
├── pm2-manager.ts # /pm2 wrapper
|
|
288
|
+
├── theme.ts # TUI colors + splash + banner + tool-call rendering
|
|
289
|
+
├── retry.ts # API call retry with backoff
|
|
290
|
+
├── export.ts # /export md/json/txt
|
|
291
|
+
├── html-parser.ts # HTML→text for web_fetch
|
|
292
|
+
└── types.ts # CrowcoderConfig, Message, Session, Mode types
|
|
293
|
+
|
|
294
|
+
bin/
|
|
295
|
+
└── crowcoder.js # CLI entry — DEP0040 suppress + dynamic import dist/index.js
|
|
296
|
+
|
|
297
|
+
resources/
|
|
298
|
+
└── ecc/ # Bundled everything-claude-code library
|
|
299
|
+
├── skills/ # 33 SKILL.md files (one per skill)
|
|
300
|
+
├── agents/ # 16 kiro agent JSON+MD pairs
|
|
301
|
+
├── commands/ # 9 workflow command prompts
|
|
302
|
+
├── rules/ # 39 language-specific rule files
|
|
303
|
+
└── prompts/ # 6 GitHub prompt files
|
|
304
|
+
|
|
305
|
+
tests/
|
|
306
|
+
├── smoke-commands.mjs # 88-command dispatch smoke test (no LLM calls)
|
|
307
|
+
├── llm-drive-all.mjs # End-to-end LLM driver against a real API
|
|
308
|
+
├── users.test.ts # Vitest unit tests
|
|
309
|
+
└── e2e/ # Playwright E2E
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## 🤝 Contributing
|
|
315
|
+
|
|
316
|
+
PRs welcome. Please:
|
|
317
|
+
|
|
318
|
+
- Strict TypeScript — avoid `any`
|
|
319
|
+
- Focused PRs — one thing per PR
|
|
320
|
+
- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`)
|
|
321
|
+
- Never commit API keys, tokens, or paths containing your username
|
|
322
|
+
- Run `node tests/smoke-commands.mjs` before submitting — must report `88/88 pass`
|
|
323
|
+
|
|
324
|
+
For larger features (new mode, new tool, new orchestration pattern), open an issue first to discuss the design.
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## 📜 License
|
|
329
|
+
|
|
330
|
+
Distributed under the **[MIT License](LICENSE)**.
|
|
331
|
+
|
|
332
|
+
Crowcoder bundles content from these projects, each under their own license:
|
|
333
|
+
- [everything-claude-code](https://github.com/Crownelius/everything-claude-code) — agent harness library
|
|
334
|
+
- [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent) — Hermes mode inspiration
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
<div align="center">
|
|
339
|
+
|
|
340
|
+
**Compact Agent** — Built to fit a lot of intelligence in a small command.
|
|
341
|
+
|
|
342
|
+
[Bug reports](https://github.com/Crownelius/Crowcoder/issues) • [Install guide](INSTALL.md) • [Command reference](COMMANDS.md) • [npm](https://www.npmjs.com/package/compact-agent)
|
|
343
|
+
|
|
344
|
+
</div>
|