cli-jaw 1.7.19 β 1.7.20
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.ko.md +183 -441
- package/README.md +249 -480
- package/README.zh-CN.md +184 -442
- package/dist/server.js +33 -19
- package/dist/server.js.map +1 -1
- package/dist/src/core/config.js +5 -0
- package/dist/src/core/config.js.map +1 -1
- package/dist/src/core/settings-merge.js +2 -2
- package/dist/src/core/settings-merge.js.map +1 -1
- package/dist/src/security/network-acl.js +133 -0
- package/dist/src/security/network-acl.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,18 +1,14 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
#
|
|
3
|
+
# CLI-JAW
|
|
4
4
|
|
|
5
|
-
###
|
|
5
|
+
### All your AI subscriptions. One assistant.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
[](#-tests)
|
|
7
|
+
[](https://npmjs.com/package/cli-jaw)
|
|
10
8
|
[](https://typescriptlang.org)
|
|
11
9
|
[](https://nodejs.org)
|
|
12
10
|
[](LICENSE)
|
|
13
|
-
[](#-docker--container-isolation)
|
|
15
|
-
[](#)
|
|
11
|
+
[](#-docker)
|
|
16
12
|
|
|
17
13
|
**English** / [νκ΅μ΄](README.ko.md) / [δΈζ](README.zh-CN.md)
|
|
18
14
|
|
|
@@ -20,144 +16,120 @@
|
|
|
20
16
|
|
|
21
17
|
</div>
|
|
22
18
|
|
|
23
|
-
|
|
19
|
+
<table>
|
|
20
|
+
<tr><td><b>Your existing subscriptions, unified</b></td><td>Claude Max, ChatGPT Pro, Copilot, Gemini Advanced β route through OAuth. Add any model via OpenCode. No per-token billing.</td></tr>
|
|
21
|
+
<tr><td><b>Lives where you do</b></td><td>Web PWA with virtual scroll and WS streaming, Mac WebView app, terminal TUI, Telegram with voice, Discord β five surfaces, one conversation.</td></tr>
|
|
22
|
+
<tr><td><b>3-layer memory</b></td><td>History Block (recent sessions) + Memory Flush (episodes, daily logs) + Soul and Task Snapshot (identity, semantic recall). SQLite FTS5 full-text search.</td></tr>
|
|
23
|
+
<tr><td><b>Multi-agent orchestration</b></td><td>PABCD β a DB-persisted 5-phase FSM. Employee system with worker registry. Parallel subtasks with file-overlap detection. You approve every phase.</td></tr>
|
|
24
|
+
<tr><td><b>Browser and desktop automation</b></td><td>Chrome CDP, vision-click, DOM reference for ChatGPT/Grok/Gemini, Computer Use integration via Codex App, diagram skill for SVG and interactive visualizations.</td></tr>
|
|
25
|
+
<tr><td><b>MCP install once, 5 engines</b></td><td><code>jaw mcp install</code> syncs to Claude, Codex, Gemini, OpenCode, and Copilot simultaneously. One config file.</td></tr>
|
|
26
|
+
<tr><td><b>Speaks your language</b></td><td>English, Korean, Chinese README. i18n web UI. HWP/HWPX Korean office document support via OfficeCLI.</td></tr>
|
|
27
|
+
</table>
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Quick links
|
|
24
32
|
|
|
25
|
-
- [Install
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [Development](#οΈ-development) Β· [Tests](#-tests) Β· [Docs](#-documentation) Β· [Troubleshooting](#-troubleshooting) Β· [Contributing](#-contributing)
|
|
33
|
+
- [Install](#-install--run) Β· [Authenticate](#-authenticate) Β· [Surfaces](#-where-it-lives)
|
|
34
|
+
- [Engine routing](#-engine-routing) Β· [Memory](#-memory) Β· [PABCD](#-orchestration--pabcd) Β· [Skills](#-skills)
|
|
35
|
+
- [Browser automation](#-browser--desktop-automation) Β· [MCP](#-mcp) Β· [Messaging](#-messaging)
|
|
36
|
+
- [CLI commands](#%EF%B8%8F-cli-commands) Β· [Docker](#-docker) Β· [Docs](#-documentation) Β· [How it compares](#-how-it-compares)
|
|
30
37
|
|
|
31
38
|
<details>
|
|
32
|
-
<summary
|
|
39
|
+
<summary>Are you on Windows? β WSL one-click setup</summary>
|
|
33
40
|
|
|
34
|
-
**Step 1: Install WSL** (PowerShell as Admin
|
|
41
|
+
**Step 1: Install WSL** (PowerShell as Admin)
|
|
35
42
|
|
|
36
43
|
```powershell
|
|
37
44
|
wsl --install
|
|
38
45
|
```
|
|
39
46
|
|
|
40
|
-
Restart
|
|
47
|
+
Restart, then open **Ubuntu** from the Start Menu.
|
|
41
48
|
|
|
42
|
-
**Step 2: Install CLI-JAW**
|
|
49
|
+
**Step 2: Install CLI-JAW**
|
|
43
50
|
|
|
44
51
|
```bash
|
|
45
52
|
curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install-wsl.sh | bash
|
|
46
53
|
```
|
|
47
54
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
**Step 3: Reload your shell** (important β picks up PATH changes)
|
|
55
|
+
**Step 3: Reload shell and start**
|
|
51
56
|
|
|
52
57
|
```bash
|
|
53
58
|
source ~/.bashrc
|
|
59
|
+
copilot login # or: claude auth / codex login / gemini
|
|
60
|
+
jaw serve # β http://localhost:3457
|
|
54
61
|
```
|
|
55
62
|
|
|
56
|
-
**Step 4: Authenticate an AI Engine** (pick one)
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
copilot login # GitHub Copilot (Free)
|
|
60
|
-
opencode # OpenCode (Free models available)
|
|
61
|
-
claude auth # Anthropic Claude
|
|
62
|
-
codex login # OpenAI Codex
|
|
63
|
-
gemini # Google Gemini
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
**Step 5: Start Chatting**
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
jaw serve
|
|
70
|
-
# β http://localhost:3457
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
> π‘ The script uses [fnm](https://github.com/Schniz/fnm) for Node.js management. If you already have `nvm`, it will use that instead.
|
|
74
|
-
|
|
75
63
|
<details>
|
|
76
|
-
<summary
|
|
64
|
+
<summary>Troubleshooting WSL</summary>
|
|
77
65
|
|
|
78
|
-
| Problem
|
|
79
|
-
|
|
80
|
-
| `unzip: command not found`
|
|
81
|
-
| `jaw: command not found`
|
|
82
|
-
|
|
|
83
|
-
| Permission errors with `npm install -g` | Run `sudo chown -R $USER $(npm config get prefix)` |
|
|
84
|
-
| `sudo` keeps blocking later tasks | Rerun the WSL installer so it can install system deps once, then check `jaw doctor --json` for `wsl.sudoNonInteractive` and `wsl.npmPrefix` |
|
|
66
|
+
| Problem | Fix |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `unzip: command not found` | Rerun the installer |
|
|
69
|
+
| `jaw: command not found` | `source ~/.bashrc` |
|
|
70
|
+
| Permission errors | `sudo chown -R $USER $(npm config get prefix)` |
|
|
85
71
|
|
|
86
72
|
</details>
|
|
87
|
-
|
|
88
73
|
</details>
|
|
89
74
|
|
|
90
75
|
<details>
|
|
91
|
-
<summary
|
|
92
|
-
|
|
93
|
-
**Step 1: Open Terminal**
|
|
94
|
-
|
|
95
|
-
Open **Finder** β **Applications** β **Utilities** β **Terminal.app**
|
|
96
|
-
(or press `β Space` and type `Terminal`)
|
|
76
|
+
<summary>New to the terminal? β One-click install (macOS)</summary>
|
|
97
77
|
|
|
98
|
-
**
|
|
78
|
+
1. Open **Terminal** (`Cmd + Space` β type `Terminal`)
|
|
79
|
+
2. Paste and hit Enter:
|
|
99
80
|
|
|
100
81
|
```bash
|
|
101
82
|
curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install.sh | bash
|
|
102
83
|
```
|
|
103
84
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
**Step 3: Login & Launch**
|
|
85
|
+
3. Authenticate and launch:
|
|
107
86
|
|
|
108
87
|
```bash
|
|
109
|
-
copilot login
|
|
110
|
-
jaw serve
|
|
88
|
+
copilot login
|
|
89
|
+
jaw serve # β http://localhost:3457
|
|
111
90
|
```
|
|
112
91
|
|
|
113
|
-
Open **http://localhost:3457** in your browser. That's it! π¦
|
|
114
|
-
|
|
115
92
|
</details>
|
|
116
93
|
|
|
117
94
|
---
|
|
118
95
|
|
|
119
|
-
## π Install &
|
|
96
|
+
## π Install & run
|
|
120
97
|
|
|
121
98
|
```bash
|
|
122
99
|
npm install -g cli-jaw
|
|
123
100
|
jaw serve
|
|
124
101
|
```
|
|
125
102
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
> π **Want it running 24/7?** `jaw service install` β auto-detects systemd, launchd, or Docker.
|
|
103
|
+
Open **http://localhost:3457**. Requires Node.js 22+ and at least one AI CLI authenticated below.
|
|
129
104
|
|
|
130
|
-
>
|
|
131
|
-
|
|
132
|
-
> π **Shared path policy:** cli-jaw uses `~/.cli-jaw/*` by default. It does **not** modify shared harness paths (`~/.agents/*`, `~/.agent/*`, `~/.claude/*`) unless you explicitly opt in. See `jaw doctor --repair-shared-paths` to detect or fix contamination from older versions.
|
|
105
|
+
> `jaw service install` β auto-start on boot (systemd, launchd, or Docker, auto-detected).
|
|
133
106
|
|
|
134
107
|
---
|
|
135
108
|
|
|
136
|
-
## π Authenticate
|
|
109
|
+
## π Authenticate
|
|
137
110
|
|
|
138
|
-
You only need
|
|
111
|
+
You only need one. Pick whichever subscription you already have:
|
|
139
112
|
|
|
140
113
|
```bash
|
|
141
|
-
#
|
|
142
|
-
copilot login
|
|
143
|
-
opencode
|
|
144
|
-
|
|
145
|
-
#
|
|
146
|
-
claude auth
|
|
147
|
-
codex login
|
|
148
|
-
gemini
|
|
114
|
+
# Free
|
|
115
|
+
copilot login # GitHub Copilot
|
|
116
|
+
opencode # OpenCode β free models available
|
|
117
|
+
|
|
118
|
+
# Paid (monthly subscription)
|
|
119
|
+
claude auth # Anthropic Claude Max
|
|
120
|
+
codex login # OpenAI ChatGPT Pro
|
|
121
|
+
gemini # Google Gemini Advanced
|
|
149
122
|
```
|
|
150
123
|
|
|
151
|
-
Check
|
|
124
|
+
Check status: `jaw doctor`
|
|
152
125
|
|
|
153
126
|
<details>
|
|
154
|
-
<summary
|
|
127
|
+
<summary>Example jaw doctor output</summary>
|
|
155
128
|
|
|
156
129
|
```
|
|
157
130
|
π¦ CLI-JAW Doctor β 12 checks
|
|
158
131
|
|
|
159
132
|
β
Node.js v22.15.0
|
|
160
|
-
β
npm v10.9.4
|
|
161
133
|
β
Claude CLI installed
|
|
162
134
|
β
Codex CLI installed
|
|
163
135
|
β οΈ Gemini CLI not found (optional)
|
|
@@ -172,453 +144,301 @@ Check what's ready: `jaw doctor`
|
|
|
172
144
|
|
|
173
145
|
</details>
|
|
174
146
|
|
|
175
|
-
> π‘ **You don't need all 5.** Even one CLI is enough. Your assistant auto-detects which engines are available and falls back gracefully.
|
|
176
|
-
|
|
177
147
|
---
|
|
178
148
|
|
|
179
|
-
##
|
|
180
|
-
|
|
181
|
-
CLI-JAW is a **personal AI assistant** that lives on your machine and works from the interfaces you already use β **Web, Terminal, Telegram, and Discord**. Ask it anything, delegate tasks, automate your workflows.
|
|
182
|
-

|
|
183
|
-
|
|
184
|
-
> π¬ *"Summarize today's schedule"* β answer on Telegram
|
|
185
|
-
> π¬ *"Refactor this module and write tests"* β sub-agents handle it while you grab coffee
|
|
186
|
-
> π¬ *"Download that PDF and put the key points in Notion"* β browser + Notion skill, done
|
|
149
|
+
## π₯οΈ Where it lives
|
|
187
150
|
|
|
188
|
-
|
|
151
|
+
CLI-JAW works from five surfaces. Same assistant, same memory, same skills across all of them.
|
|
189
152
|
|
|
190
|
-
|
|
|
191
|
-
|
|
192
|
-
|
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
|
|
|
196
|
-
|
|
|
197
|
-
| π₯οΈ**Cross-Platform** | macOS, Linux, Windows β ENOENT-safe CLI spawn, auto-detection,`.cmd` shim support, and native install all work across platforms. |
|
|
198
|
-
|
|
199
|
-

|
|
153
|
+
| Surface | What you get |
|
|
154
|
+
|---|---|
|
|
155
|
+
| **Web PWA** | Full UI with markdown/KaTeX/Mermaid rendering, virtual scroll, WS streaming, drag-and-drop file upload, voice recording, PABCD roadmap bar, i18n (English, Korean), dark/light theme, offline message cache via IndexedDB |
|
|
156
|
+
| **Mac WebView app** | `jaw serve` wrapped in a native macOS app shell. Access from Dock without opening a browser |
|
|
157
|
+
| **Terminal TUI** | Multiline editing, slash-command autocomplete, overlay selectors, session persistence, resume classification |
|
|
158
|
+
| **Telegram** | Voice messages (multi-provider STT), photos, files. Scheduled task results delivered automatically. Slash commands for model/CLI switching |
|
|
159
|
+
| **Discord** | Text and file messaging, command sync, channel/thread routing, forwarder for agent results |
|
|
200
160
|
|
|
201
161
|
---
|
|
202
162
|
|
|
203
|
-
##
|
|
204
|
-
|
|
205
|
-
`v1.6.0` is the documentation catch-up release that finally summarizes the major product expansion that happened after `v1.2.0`.
|
|
163
|
+
## π Engine routing
|
|
206
164
|
|
|
207
|
-
|
|
208
|
-
- Range covered: `v1.2.0` β `v1.5.1`
|
|
209
|
-
- Scope: `59` commits, `307` files changed, `32,760` insertions, `4,263` deletions
|
|
210
|
-
- Theme: CLI-JAW grew from a capable personal assistant into a broader operating environment with richer orchestration, memory, channels, UI, and release tooling
|
|
165
|
+
Five CLI backends, routed through OAuth subscriptions you already pay for. No per-token API billing.
|
|
211
166
|
|
|
212
|
-
|
|
|
213
|
-
|
|
214
|
-
|
|
|
215
|
-
|
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
|
|
|
219
|
-
| β¨οΈ **CLI/TUI Usability Pass** | Terminal workflows now include `/compact`, better overlays and selectors, session persistence, resume classification, readiness checks, and more stable command handling. |
|
|
220
|
-
| π§ͺ **Ops, CI, and Installability** | `jaw doctor`, browser launch policy, skill reset/fallback behavior, submodule-safe CI, preview releases, Vite-based frontend delivery, service worker assets, and stronger install troubleshooting all improved. |
|
|
221
|
-
| π **Office Automation Maturity** | OfficeCLI integration, smoke tests, local binaries, and Office/PDF workflows are much more production-ready than they were at `v1.2.0`. |
|
|
167
|
+
| CLI | Default model | Auth | Cost model |
|
|
168
|
+
|---|---|---|---|
|
|
169
|
+
| **Claude** | `opus-4-6` | `claude auth` | Claude Max subscription |
|
|
170
|
+
| **Codex** | `gpt-5.5` | `codex login` | ChatGPT Pro subscription |
|
|
171
|
+
| **Gemini** | `gemini-3.1-pro-preview` | `gemini` | Gemini Advanced subscription |
|
|
172
|
+
| **OpenCode** | `minimax-m2.7` | `opencode` | Free models available |
|
|
173
|
+
| **Copilot** | `gpt-5-mini` | `copilot login` | Free tier available |
|
|
222
174
|
|
|
223
|
-
|
|
175
|
+
**Fallback chain**: if one engine is rate-limited or down, the next picks up automatically. Configure with `/fallback [cli1 cli2...]`.
|
|
224
176
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
```mermaid
|
|
228
|
-
graph LR
|
|
229
|
-
YOU["π€ You"] -->|Web / Terminal / Telegram| JAW["π¦ CLI-JAW"]
|
|
230
|
-
JAW -->|spawn| C["Claude"]
|
|
231
|
-
JAW -->|spawn| X["Codex"]
|
|
232
|
-
JAW -->|spawn| G["Gemini"]
|
|
233
|
-
JAW -->|spawn| O["OpenCode"]
|
|
234
|
-
JAW -->|spawn| P["Copilot"]
|
|
235
|
-
JAW -->|inject| SK["π¦ Skills"]
|
|
236
|
-
JAW -->|control| BR["π Chrome"]
|
|
237
|
-
JAW -->|send| TG["π± Telegram"]
|
|
238
|
-
|
|
239
|
-
style JAW fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
240
|
-
```
|
|
177
|
+
**OpenCode wildcard**: connect any model endpoint β OpenRouter, local LLMs, or any OpenAI-compatible API.
|
|
241
178
|
|
|
242
|
-
|
|
243
|
-
- β‘ **Auto fallback** β If one engine is down, the next picks up seamlessly.
|
|
244
|
-
- π **Multi-agent orchestration** β Complex tasks get split across specialized sub-agents automatically.
|
|
245
|
-
- π€ **Voice input** β Mic button on the web + Telegram voice messages. Multi-provider STT (OpenAI, Vertex AI).
|
|
246
|
-
- π **Prompt templates** β Create, manage, and reuse prompt templates with a visual node-map editor.
|
|
247
|
-
- π¦ **100+ skills** β Browser control, file editing, image generation, web search, and [much more](#-skill-system).
|
|
248
|
-
- π§ **Persistent memory** β Your assistant remembers past conversations and preferences across sessions.
|
|
249
|
-
- π± **Telegram bot** β Chat with your assistant from your phone, send voice/photos/files.
|
|
250
|
-
- π **Browser automation** β Your assistant can navigate the web, click, type, and screenshot.
|
|
251
|
-
- π **MCP ecosystem** β Install once, available to all 5 AI engines instantly.
|
|
252
|
-
- π **Web search** β Real-time information via MCP tools.
|
|
253
|
-
- β° **Heartbeat jobs** β Schedule recurring tasks that run automatically.
|
|
179
|
+
> Switch engines: `/cli codex`. Switch models: `/model gpt-5.5`. All from Web, Terminal, Telegram, or Discord.
|
|
254
180
|
|
|
255
181
|
---
|
|
256
182
|
|
|
257
|
-
##
|
|
183
|
+
## π§ Memory
|
|
258
184
|
|
|
259
|
-
|
|
185
|
+
Three layers, each serving a different recall horizon.
|
|
260
186
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
|
265
|
-
|
|
|
266
|
-
| **Active Skills** | 22 | Auto-injected into every AI prompt. Always available. |
|
|
267
|
-
| **Reference Skills** | 94 | AI reads them on-demand when you ask for a relevant task. |
|
|
268
|
-
|
|
269
|
-
#### Active Skills (always on)
|
|
270
|
-
|
|
271
|
-
| Skill | What it does |
|
|
272
|
-
| ------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
273
|
-
| `browser` | Chrome automation β snapshot, click, navigate, screenshot |
|
|
274
|
-
| `github` | Issues, PRs, CI, code review via `gh` CLI |
|
|
275
|
-
| `notion` | Create/manage Notion pages and databases |
|
|
276
|
-
| `memory` | Persistent long-term memory across sessions |
|
|
277
|
-
| `telegram-send` | Send photos, documents, voice messages to Telegram |
|
|
278
|
-
| `vision-click` | Screenshot β AI finds coordinates β clicks (one command) |
|
|
279
|
-
| `pdf` / `pdf-expert` / `docx` / `xlsx` / `pptx` / `hwp` | Read, create, edit office & PDF documents (incl. Korean HWP) |
|
|
280
|
-
| `screen-capture` | macOS screenshot and camera capture |
|
|
281
|
-
| `video` | Remotion-based programmatic video rendering from JSON |
|
|
282
|
-
| `dev` / `dev-frontend` / `dev-backend` / `dev-data` / `dev-testing` | Development guidelines for sub-agents |
|
|
283
|
-
| `dev-pabcd` / `dev-scaffolding` / `dev-code-reviewer` | Orchestration, scaffolding, and code review guides |
|
|
187
|
+
| Layer | What it stores | How it works |
|
|
188
|
+
|---|---|---|
|
|
189
|
+
| **History Block** | Recent session context | `buildHistoryBlock()` β last 10 sessions, max 8000 chars, scoped to working directory. Injected at prompt start |
|
|
190
|
+
| **Memory Flush** | Structured knowledge extracted from conversations | Triggered after threshold (default 10 turns). Extractor prompt summarizes into episodes, daily logs (`YYYY-MM-DD.md`), live notes. Stored as markdown files |
|
|
191
|
+
| **Soul + Task Snapshot** | Identity and semantic recall | `soul.md` defines core values, tone, boundaries. Task Snapshot searches FTS5 index for up to 4 semantically relevant hits (700 chars each) per prompt |
|
|
284
192
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
94 more skills ready to use β imagegen, openai-docs, spotify, weather, deep-research, tts, video-downloader, apple-reminders, 1password, terraform, postgres, jupyter-notebook, sentry, whatsapp, and more.
|
|
288
|
-
|
|
289
|
-
```bash
|
|
290
|
-
jaw skill install <name> # Activate a reference skill permanently
|
|
291
|
-
```
|
|
193
|
+
All three layers feed into the system prompt automatically. Memory is searchable: `jaw memory search <query>` or `/memory <query>` from any interface.
|
|
292
194
|
|
|
293
|
-
|
|
195
|
+
Advanced memory includes profile summary, bootstrap/migration, and reindex flows accessible from the Web UI settings.
|
|
294
196
|
|
|
295
197
|
---
|
|
296
198
|
|
|
297
|
-
##
|
|
199
|
+
## π Orchestration β PABCD
|
|
298
200
|
|
|
299
|
-
|
|
201
|
+
For complex tasks, CLI-JAW uses a 5-phase state machine. You approve every transition.
|
|
300
202
|
|
|
301
203
|
```
|
|
302
|
-
|
|
204
|
+
P (Plan) β A (Audit) β B (Build) β C (Check) β D (Done) β IDLE
|
|
205
|
+
β β β auto auto
|
|
303
206
|
```
|
|
304
207
|
|
|
305
|
-
|
|
306
|
-
|
|
208
|
+
| Phase | What happens |
|
|
209
|
+
|---|---|
|
|
210
|
+
| **P** | Boss AI writes a diff-level plan. Stops for your review |
|
|
211
|
+
| **A** | Read-only worker verifies the plan is feasible |
|
|
212
|
+
| **B** | Boss implements. Read-only worker verifies the result |
|
|
213
|
+
| **C** | Type-check, docs update, consistency check |
|
|
214
|
+
| **D** | Summary of all changes. Returns to idle |
|
|
307
215
|
|
|
308
|
-
|
|
309
|
-
2. **Configure** β Run `jaw init --telegram-token YOUR_TOKEN` or edit settings in the Web UI
|
|
310
|
-
3. **Start chatting** β Send any message to your bot. Your chat ID is auto-saved on first message.
|
|
216
|
+
State is DB-persisted and survives server restarts. Workers cannot modify files. Activate with `jaw orchestrate` or `/pabcd`.
|
|
311
217
|
|
|
312
|
-
|
|
218
|
+
---
|
|
313
219
|
|
|
314
|
-
|
|
220
|
+
## π¦ Skills
|
|
315
221
|
|
|
316
|
-
|
|
317
|
-
- π€ Send voice messages (auto-transcribed via multi-provider STT)
|
|
318
|
-
- π Send files and photos for processing
|
|
319
|
-
- ποΈ Combine voice + text + attachments in a single message
|
|
320
|
-
- β‘ Run commands (`/cli`, `/model`, `/status`)
|
|
321
|
-
- π Switch AI engines on the fly
|
|
222
|
+
100+ skills, organized by what they do.
|
|
322
223
|
|
|
323
|
-
|
|
224
|
+
| Category | Skills | What they cover |
|
|
225
|
+
|---|---|---|
|
|
226
|
+
| **Office** | `pdf`, `docx`, `xlsx`, `pptx`, `hwp` | Read, create, edit documents. Korean HWP/HWPX via OfficeCLI |
|
|
227
|
+
| **Automation** | `browser`, `vision-click`, `screen-capture`, `desktop-control` | Chrome CDP, AI-powered coordinate click, macOS screenshot/camera, Computer Use |
|
|
228
|
+
| **Media** | `video`, `imagegen`, `lecture-stt`, `tts` | Remotion video rendering, OpenAI image generation, lecture transcription, text-to-speech |
|
|
229
|
+
| **Integration** | `github`, `notion`, `telegram-send`, `memory` | Issues/PRs/CI, Notion pages, Telegram media delivery, persistent memory |
|
|
230
|
+
| **Visualization** | `diagram` | SVG diagrams, charts, interactive visualizations rendered in chat |
|
|
231
|
+
| **Dev guides** | `dev`, `dev-frontend`, `dev-backend`, `dev-data`, `dev-testing`, `dev-pabcd`, `dev-code-reviewer` | Engineering guidelines injected into sub-agent prompts |
|
|
324
232
|
|
|
325
|
-
|
|
326
|
-
- Generated images, PDFs, documents
|
|
327
|
-
- Scheduled task results (heartbeat jobs)
|
|
328
|
-
- Browser screenshots
|
|
233
|
+
22 active skills (always injected). 94+ reference skills (loaded on demand).
|
|
329
234
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
235
|
+
```bash
|
|
236
|
+
jaw skill install <name> # activate a reference skill
|
|
237
|
+
```
|
|
333
238
|
|
|
334
239
|
---
|
|
335
240
|
|
|
336
|
-
##
|
|
241
|
+
## π Browser & desktop automation
|
|
337
242
|
|
|
338
|
-
|
|
243
|
+
| Capability | How it works |
|
|
244
|
+
|---|---|
|
|
245
|
+
| **Chrome CDP** | Navigate, click, type, screenshot, evaluate JS, scroll, focus, press keys β 10 actions via DevTools Protocol |
|
|
246
|
+
| **Vision-click** | Screenshot the screen, AI extracts target coordinates, clicks. One command: `jaw browser vision-click "Login button"` |
|
|
247
|
+
| **DOM reference** | Documented selector maps for ChatGPT, Grok, and Gemini web UIs β model selection, stop buttons, tool drawers |
|
|
248
|
+
| **Computer Use** | Desktop app automation via Codex App Computer Use MCP. Routes DOM targets to CDP, desktop apps to Computer Use |
|
|
249
|
+
| **Diagram skill** | Generate SVG diagrams and interactive HTML visualizations, rendered in sandboxed iframes with copy/save controls |
|
|
339
250
|
|
|
340
|
-
|
|
341
|
-
| --------------------- | --------------------------------------------- |
|
|
342
|
-
| **OpenAI-compatible** | Settings UI β STT β OpenAI endpoint + API key |
|
|
343
|
-
| **Google Vertex AI** | Settings UI β STT β Vertex AI credentials |
|
|
344
|
-
| **Custom endpoint** | Any OpenAI-compatible STT API URL |
|
|
251
|
+
---
|
|
345
252
|
|
|
346
|
-
|
|
253
|
+
## π MCP
|
|
347
254
|
|
|
348
|
-
|
|
349
|
-
- π± **Telegram** β Send voice messages; auto-transcribed before reaching the AI
|
|
350
|
-
- ποΈ **Multimodal** β Combine voice + text + file attachments in a single message
|
|
255
|
+
[Model Context Protocol](https://modelcontextprotocol.io) lets AI agents use external tools. CLI-JAW manages MCP config for all five engines from one file.
|
|
351
256
|
|
|
352
|
-
|
|
257
|
+
```bash
|
|
258
|
+
jaw mcp install @anthropic/context7
|
|
259
|
+
# β syncs to Claude, Codex, Gemini, OpenCode, Copilot config files
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
No more editing five different JSON files. Install once, all engines get it.
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
jaw mcp sync # re-sync after manual edits
|
|
266
|
+
```
|
|
353
267
|
|
|
354
268
|
---
|
|
355
269
|
|
|
356
|
-
##
|
|
270
|
+
## π¬ Messaging
|
|
357
271
|
|
|
358
|
-
|
|
272
|
+
### Telegram
|
|
359
273
|
|
|
360
274
|
```
|
|
361
|
-
|
|
362
|
-
β P A B C D β
|
|
363
|
-
β Plan β Audit β Build β Check β Done β
|
|
364
|
-
β π π π¨ β
π β
|
|
365
|
-
β β β β
|
|
366
|
-
β βββ reject βββββ reject (self-heal loop) β
|
|
367
|
-
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
275
|
+
π± Telegram ββ π¦ CLI-JAW ββ π€ AI Engines
|
|
368
276
|
```
|
|
369
277
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
| **P** | Plan | Boss AI writes a diff-level implementation plan. Stops and waits for your approval. |
|
|
373
|
-
| **A** | Audit | A read-only worker verifies the plan is feasible β imports resolve, signatures match, no integration risks. |
|
|
374
|
-
| **B** | Build | Boss implements the code directly. A read-only worker verifies the result. Self-heals on failure. |
|
|
375
|
-
| **C** | Check | Final verification β `tsc --noEmit`, docs update, consistency check. |
|
|
376
|
-
| **D** | Done | Summary of all changes. State returns to IDLE. |
|
|
377
|
-
|
|
378
|
-
**Key design decisions:**
|
|
379
|
-
- **DB-persisted FSM** β state survives server restarts, CLI and Web UI share the same state
|
|
380
|
-
- **Hard STOP at every phase** β the AI cannot self-advance; you approve each transition
|
|
381
|
-
- **Workers are READ-ONLY** β audit and verify phases can never accidentally modify files
|
|
382
|
-
- **Parallel-safe** β independent subtasks run concurrently via `Promise.all` with file-overlap detection
|
|
383
|
-
|
|
384
|
-
```mermaid
|
|
385
|
-
graph TD
|
|
386
|
-
USER["π€ Your Request"] --> TRIAGE["π Triage β Simple or Complex?"]
|
|
387
|
-
|
|
388
|
-
TRIAGE -->|Simple| DIRECT["β‘ Direct Response"]
|
|
389
|
-
TRIAGE -->|Complex| P["π P: Plan"]
|
|
390
|
-
|
|
391
|
-
P -->|approved| A["π A: Audit"]
|
|
392
|
-
A -->|pass| B["π¨ B: Build"]
|
|
393
|
-
A -->|fail| P
|
|
394
|
-
B -->|verified| C["β
C: Check"]
|
|
395
|
-
B -->|needs fix| B
|
|
396
|
-
C --> D["π D: Done"]
|
|
397
|
-
D --> IDLE["π€ IDLE"]
|
|
398
|
-
|
|
399
|
-
style USER fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
400
|
-
style P fill:#fdf2e9,stroke:#d4a574,color:#5c4033
|
|
401
|
-
style A fill:#fdf2e9,stroke:#d4a574,color:#5c4033
|
|
402
|
-
style B fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
403
|
-
style C fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
404
|
-
style D fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
405
|
-
```
|
|
278
|
+
<details>
|
|
279
|
+
<summary>Setup (3 steps)</summary>
|
|
406
280
|
|
|
407
|
-
|
|
281
|
+
1. Create a bot β message [@BotFather](https://t.me/BotFather) β `/newbot` β copy the token
|
|
282
|
+
2. Configure β `jaw init --telegram-token YOUR_TOKEN` or use the Web UI settings
|
|
283
|
+
3. Send any message to your bot. Chat ID is auto-saved on first message
|
|
408
284
|
|
|
409
|
-
|
|
285
|
+
</details>
|
|
410
286
|
|
|
411
|
-
|
|
287
|
+
What works from Telegram: text chat, voice messages (auto-transcribed via multi-provider STT), file/photo upload, slash commands (`/cli`, `/model`, `/status`), scheduled task result delivery.
|
|
412
288
|
|
|
413
|
-
|
|
289
|
+
### Discord
|
|
414
290
|
|
|
415
|
-
|
|
416
|
-
jaw mcp install @anthropic/context7 # Install once
|
|
417
|
-
# β Automatically syncs to Claude, Codex, Gemini, OpenCode, Copilot, Antigravity
|
|
418
|
-
```
|
|
291
|
+
Same capabilities as Telegram β text, files, commands. Channel and thread routing with forwarder for agent result broadcast. Setup via Web UI settings.
|
|
419
292
|
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
MJ -->|auto-sync| CX["Codex"]
|
|
424
|
-
MJ -->|auto-sync| GM["Gemini"]
|
|
425
|
-
MJ -->|auto-sync| OC["OpenCode"]
|
|
426
|
-
MJ -->|auto-sync| CP["Copilot"]
|
|
427
|
-
MJ -->|auto-sync| AG["Antigravity"]
|
|
428
|
-
|
|
429
|
-
style MJ fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
|
|
430
|
-
```
|
|
293
|
+
### Voice & STT
|
|
294
|
+
|
|
295
|
+
Voice input works on Web (mic button), Telegram (voice messages), and Discord. Providers: OpenAI-compatible, Google Vertex AI, or any custom endpoint. Configured in the Web UI settings.
|
|
431
296
|
|
|
432
|
-
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## β° Scheduling & heartbeat
|
|
300
|
+
|
|
301
|
+
| Feature | What it does |
|
|
302
|
+
|---|---|
|
|
303
|
+
| **Heartbeat jobs** | Cron-scheduled tasks that run unattended. Results delivered to Telegram/Discord |
|
|
304
|
+
| **Service auto-start** | `jaw service install` β auto-detects systemd (Linux), launchd (macOS), or Docker |
|
|
305
|
+
| **Memory auto-reflect** | Optional post-flush reflection for structured knowledge extraction |
|
|
433
306
|
|
|
434
307
|
---
|
|
435
308
|
|
|
436
|
-
## β¨οΈ CLI
|
|
309
|
+
## β¨οΈ CLI commands
|
|
437
310
|
|
|
438
311
|
```bash
|
|
439
|
-
jaw serve #
|
|
440
|
-
jaw
|
|
441
|
-
jaw
|
|
442
|
-
jaw service
|
|
443
|
-
jaw
|
|
444
|
-
jaw
|
|
445
|
-
jaw
|
|
446
|
-
jaw
|
|
447
|
-
jaw mcp install <package> # Install MCP β syncs to all 6 CLIs
|
|
448
|
-
jaw memory search <query> # Search memory
|
|
449
|
-
jaw browser start # Launch Chrome (CDP)
|
|
312
|
+
jaw serve # start server β http://localhost:3457
|
|
313
|
+
jaw chat # terminal TUI
|
|
314
|
+
jaw doctor # 12-point diagnostics
|
|
315
|
+
jaw service install # auto-start on boot
|
|
316
|
+
jaw skill install <name> # activate a skill
|
|
317
|
+
jaw mcp install <package> # install MCP β syncs to 5 engines
|
|
318
|
+
jaw memory search <query> # search memory
|
|
319
|
+
jaw browser start # launch Chrome (CDP)
|
|
450
320
|
jaw browser vision-click "Login" # AI-powered click
|
|
451
|
-
jaw clone ~/
|
|
452
|
-
jaw --home ~/
|
|
453
|
-
jaw
|
|
321
|
+
jaw clone ~/project # clone instance
|
|
322
|
+
jaw --home ~/project serve --port 3458 # run second instance
|
|
323
|
+
jaw orchestrate # enter PABCD
|
|
324
|
+
jaw dispatch --agent Research --task "..." # dispatch employee
|
|
325
|
+
jaw reset # full reset
|
|
454
326
|
```
|
|
455
327
|
|
|
456
328
|
---
|
|
457
329
|
|
|
458
|
-
## ποΈ Multi-
|
|
330
|
+
## ποΈ Multi-instance
|
|
459
331
|
|
|
460
|
-
Run
|
|
332
|
+
Run isolated instances with separate settings, memory, and database.
|
|
461
333
|
|
|
462
334
|
```bash
|
|
463
|
-
# Clone your default instance to a new project
|
|
464
335
|
jaw clone ~/my-project
|
|
465
|
-
|
|
466
|
-
# Run it on a different port
|
|
467
336
|
jaw --home ~/my-project serve --port 3458
|
|
468
|
-
|
|
469
|
-
# Or auto-start both on boot
|
|
470
|
-
jaw service # default β port 3457 (auto-detect backend)
|
|
471
|
-
jaw --home ~/my-project service --port 3458 # project β port 3458
|
|
472
337
|
```
|
|
473
338
|
|
|
474
|
-
Each instance is fully independent β different working directory, different memory, different MCP config.
|
|
475
|
-
|
|
476
|
-
| Flag / Env | What it does |
|
|
477
|
-
| --------------------- | ----------------------------------------- |
|
|
478
|
-
| `--home <path>` | Use a custom home directory for this run |
|
|
479
|
-
| `--home=<path>` | Same, with `=` syntax |
|
|
480
|
-
| `CLI_JAW_HOME=<path>` | Set via environment variable |
|
|
481
|
-
| `jaw clone <target>` | Clone current instance to a new directory |
|
|
482
|
-
| `--port <port>` | Custom port for `serve` / `service` |
|
|
483
|
-
|
|
484
|
-
---
|
|
485
|
-
|
|
486
|
-
## π€ Models
|
|
487
|
-
|
|
488
|
-
Each CLI comes with preconfigured presets, but you can type **any model ID** directly.
|
|
489
|
-
|
|
490
|
-
<details>
|
|
491
|
-
<summary>View all presets</summary>
|
|
492
|
-
|
|
493
|
-
| CLI | Default | Notable Models |
|
|
494
|
-
| ------------ | -------------------------- | ----------------------------------------------- |
|
|
495
|
-
| **Claude** | `claude-sonnet-4-6` | opus-4-6, haiku-4-5, extended thinking variants |
|
|
496
|
-
| **Codex** | `gpt-5.3-codex` | spark, 5.2, 5.1-max, 5.1-mini |
|
|
497
|
-
| **Gemini** | `gemini-2.5-pro` | 3.0-pro-preview, 3-flash-preview, 2.5-flash |
|
|
498
|
-
| **OpenCode** | `claude-opus-4-6-thinking` | π big-pickle, GLM-5, MiniMax, Kimi, GPT-5-Nano |
|
|
499
|
-
| **Copilot** | `gpt-4.1` π | π gpt-5-mini, claude-sonnet-4.6, opus-4.6 |
|
|
500
|
-
|
|
501
|
-
</details>
|
|
502
|
-
|
|
503
|
-
> π§ To add models: edit `src/cli/registry.ts` β one file, auto-propagates everywhere.
|
|
339
|
+
Each instance is fully independent β different working directory, different memory, different MCP config.
|
|
504
340
|
|
|
505
341
|
---
|
|
506
342
|
|
|
507
|
-
## π³ Docker
|
|
508
|
-
|
|
509
|
-
Run CLI-JAW in a Docker container for **security isolation** β AI agents cannot access host files.
|
|
343
|
+
## π³ Docker
|
|
510
344
|
|
|
511
345
|
```bash
|
|
512
|
-
|
|
513
|
-
docker compose up -d
|
|
514
|
-
# β http://localhost:3457
|
|
515
|
-
|
|
516
|
-
# Or build manually
|
|
517
|
-
docker build -t cli-jaw .
|
|
518
|
-
docker run -d -p 3457:3457 --env-file .env --name jaw cli-jaw
|
|
346
|
+
docker compose up -d # β http://localhost:3457
|
|
519
347
|
```
|
|
520
348
|
|
|
521
|
-
|
|
522
|
-
<summary>π Docker details</summary>
|
|
523
|
-
|
|
524
|
-
**Two Dockerfiles:**
|
|
349
|
+
Non-root `jaw` user, Chromium sandbox enabled. Two Dockerfiles: `Dockerfile` (npm install) and `Dockerfile.dev` (local source). Data persists in `jaw-data` named volume.
|
|
525
350
|
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
| `Dockerfile` | Installs from npm registry | Production / deployment |
|
|
529
|
-
| `Dockerfile.dev` | Builds from local source | Development / testing |
|
|
351
|
+
<details>
|
|
352
|
+
<summary>Docker details</summary>
|
|
530
353
|
|
|
531
354
|
```bash
|
|
532
|
-
# Dev build
|
|
355
|
+
# Dev build
|
|
533
356
|
docker build -f Dockerfile.dev -t cli-jaw:dev .
|
|
534
357
|
docker run -d -p 3457:3457 --env-file .env cli-jaw:dev
|
|
535
358
|
|
|
536
|
-
# Pin version
|
|
359
|
+
# Pin version
|
|
537
360
|
docker build --build-arg CLI_JAW_VERSION=1.0.1 -t cli-jaw:1.0.1 .
|
|
538
361
|
|
|
539
|
-
# If Chromium sandbox fails
|
|
362
|
+
# If Chromium sandbox fails
|
|
540
363
|
docker run -e CHROME_NO_SANDBOX=1 -p 3457:3457 cli-jaw
|
|
541
364
|
```
|
|
542
365
|
|
|
543
|
-
|
|
366
|
+
</details>
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## π Documentation
|
|
544
371
|
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
372
|
+
| Document | What it covers |
|
|
373
|
+
|---|---|
|
|
374
|
+
| [CHANGELOG.md](CHANGELOG.md) | Release log, including the v1.6.0 catch-up covering v1.2.0 through v1.5.1 |
|
|
375
|
+
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, module graph, 95 API handlers across 94 endpoints |
|
|
376
|
+
| [TESTS.md](TESTS.md) | Test coverage, counts, and test plan |
|
|
377
|
+
| [memory-architecture.md](docs/memory-architecture.md) | 3-layer memory model, indexing, and runtime behavior |
|
|
378
|
+
| [env-vars.md](docs/env-vars.md) | Environment variable reference |
|
|
379
|
+
| [skill-router-plan.md](docs/skill-router-plan.md) | Skill routing architecture |
|
|
380
|
+
| [officecli-integration.md](docs/officecli-integration.md) | OfficeCLI setup for HWP/HWPX and Office documents |
|
|
381
|
+
| [devlog/structure/](devlog/structure/) | Internal architecture reference β prompt pipeline, agent spawn, frontend, server API, commands, Telegram, memory |
|
|
549
382
|
|
|
550
|
-
|
|
551
|
-
To use existing host config: `-v ~/.cli-jaw:/home/jaw/.cli-jaw`
|
|
383
|
+
---
|
|
552
384
|
|
|
553
|
-
|
|
385
|
+
## βοΈ How it compares
|
|
386
|
+
|
|
387
|
+
| | CLI-JAW | Hermes Agent | Claude Code |
|
|
388
|
+
|---|---|---|---|
|
|
389
|
+
| **Model access** | OAuth subscriptions (Claude Max, ChatGPT Pro, Copilot, Gemini) + OpenCode wildcard | API keys (OpenRouter 200+, Nous Portal) | Anthropic only |
|
|
390
|
+
| **Cost model** | Monthly subscriptions you already pay for | Per-token API billing | Anthropic subscription |
|
|
391
|
+
| **Primary UI** | Web PWA + Mac app + TUI | TUI only | CLI + IDE plugins |
|
|
392
|
+
| **Messaging** | Telegram (voice) + Discord | Telegram/Discord/Slack/WhatsApp/Signal | None |
|
|
393
|
+
| **Memory** | 3-layer (History/Flush/Soul) + FTS5 | Self-improving learning loop + Honcho | File-based auto-memory |
|
|
394
|
+
| **Browser automation** | Chrome CDP + vision-click + DOM ref | Limited | Via MCP |
|
|
395
|
+
| **Orchestration** | PABCD 5-phase FSM | Subagent spawn | Task tool |
|
|
396
|
+
| **Execution** | Local + Docker | Local/Docker/SSH/Daytona/Modal/Singularity | Local |
|
|
397
|
+
| **Skills** | 100+ bundled | Self-creating + agentskills.io | User-configured |
|
|
398
|
+
| **i18n** | English, Korean, Chinese | English | English |
|
|
399
|
+
|
|
400
|
+
CLI-JAW descends from the OpenClaw harness architecture (hybrid search manager, fallback patterns, session indexing). If migrating from OpenClaw, the slash-command surface and memory model will be familiar.
|
|
554
401
|
|
|
555
402
|
---
|
|
556
403
|
|
|
557
404
|
## π οΈ Development
|
|
558
405
|
|
|
559
406
|
<details>
|
|
560
|
-
<summary>Build
|
|
407
|
+
<summary>Build and project structure</summary>
|
|
561
408
|
|
|
562
409
|
```bash
|
|
563
|
-
# Build (TypeScript β JavaScript)
|
|
564
410
|
npm run build # tsc β dist/
|
|
565
|
-
|
|
566
|
-
# Run from source (development)
|
|
567
|
-
npm run dev # tsx server.ts (hot-reload friendly)
|
|
568
|
-
npx tsx bin/cli-jaw.ts serve # Run CLI directly from .ts
|
|
569
|
-
|
|
570
|
-
# Run from build (production)
|
|
571
|
-
node dist/bin/cli-jaw.js serve
|
|
411
|
+
npm run dev # tsx server.ts (hot-reload)
|
|
572
412
|
```
|
|
573
413
|
|
|
574
|
-
**Project structure:**
|
|
575
|
-
|
|
576
414
|
```
|
|
577
415
|
src/
|
|
578
|
-
βββ agent/ # AI agent lifecycle
|
|
579
|
-
βββ browser/ # Chrome CDP
|
|
580
|
-
βββ cli/ # CLI registry
|
|
581
|
-
βββ core/ # DB, config, logging
|
|
582
|
-
βββ
|
|
583
|
-
βββ
|
|
584
|
-
βββ
|
|
585
|
-
βββ
|
|
586
|
-
βββ
|
|
587
|
-
βββ
|
|
588
|
-
|
|
416
|
+
βββ agent/ # AI agent lifecycle, spawn, history block
|
|
417
|
+
βββ browser/ # Chrome CDP, vision-click, launch policy
|
|
418
|
+
βββ cli/ # CLI registry, slash commands, model presets
|
|
419
|
+
βββ core/ # DB, config, employees, logging
|
|
420
|
+
βββ discord/ # Discord bot, commands, file send
|
|
421
|
+
βββ http/ # Express server, middleware
|
|
422
|
+
βββ memory/ # 3-layer memory, FTS5 indexing, flush, soul
|
|
423
|
+
βββ messaging/ # Channel routing, session keys
|
|
424
|
+
βββ orchestrator/ # PABCD state machine, worker registry, dispatch
|
|
425
|
+
βββ prompt/ # Prompt assembly pipeline, templates
|
|
426
|
+
βββ routes/ # REST API (95 handlers, 94 endpoints)
|
|
427
|
+
βββ security/ # Input sanitization, path guards
|
|
428
|
+
βββ telegram/ # Telegram bot, voice STT, forwarder
|
|
589
429
|
```
|
|
590
430
|
|
|
591
|
-
> TypeScript with `strict: true`, `NodeNext` module resolution, targeting ES2022.
|
|
592
|
-
|
|
593
431
|
</details>
|
|
594
432
|
|
|
595
433
|
---
|
|
596
434
|
|
|
597
435
|
## π§ͺ Tests
|
|
598
436
|
|
|
599
|
-
<details>
|
|
600
|
-
<summary>See TESTS.md for current pass counts and inventory</summary>
|
|
601
|
-
|
|
602
437
|
```bash
|
|
603
|
-
npm test
|
|
438
|
+
npm test # tsx --test (native Node.js test runner)
|
|
604
439
|
```
|
|
605
440
|
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
</details>
|
|
609
|
-
|
|
610
|
-
---
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
## π Documentation
|
|
615
|
-
|
|
616
|
-
| Document | What's inside |
|
|
617
|
-
| -------- | ------------- |
|
|
618
|
-
| [CHANGELOG.md](CHANGELOG.md) | Long-form release log, including the `v1.6.0` catch-up notes covering `v1.2.0` β `v1.5.1` |
|
|
619
|
-
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, module graph, REST API (40+ endpoints) |
|
|
620
|
-
| [TESTS.md](TESTS.md) | Test coverage, current counts, and test plan |
|
|
621
|
-
| [memory-architecture.md](docs/memory-architecture.md) | Structured memory model, indexing, and runtime behavior |
|
|
441
|
+
See [TESTS.md](TESTS.md) for current inventory and pass counts.
|
|
622
442
|
|
|
623
443
|
---
|
|
624
444
|
|
|
@@ -627,83 +447,38 @@ All tests run via `tsx --test` (native Node.js test runner + TypeScript).
|
|
|
627
447
|
<details>
|
|
628
448
|
<summary>Common issues</summary>
|
|
629
449
|
|
|
630
|
-
| Problem
|
|
631
|
-
|
|
632
|
-
| `cli-jaw: command not found` |
|
|
633
|
-
| `Error: node version`
|
|
634
|
-
| `NODE_MODULE_VERSION` mismatch |
|
|
635
|
-
| Agent timeout
|
|
636
|
-
| `EADDRINUSE: port 3457`
|
|
637
|
-
| Telegram
|
|
638
|
-
|
|
|
639
|
-
|
|
|
640
|
-
| Browser commands fail | Install Chrome/Chromium. Run `jaw browser start` first. |
|
|
450
|
+
| Problem | Solution |
|
|
451
|
+
|---|---|
|
|
452
|
+
| `cli-jaw: command not found` | `npm install -g cli-jaw` again. Check `npm bin -g` is in `$PATH` |
|
|
453
|
+
| `Error: node version` | Upgrade to Node.js 22+: `nvm install 22` |
|
|
454
|
+
| `NODE_MODULE_VERSION` mismatch | `npm run ensure:native` (auto-rebuild) |
|
|
455
|
+
| Agent timeout | `jaw doctor` to check CLI auth |
|
|
456
|
+
| `EADDRINUSE: port 3457` | Another instance running. Use `--port 3458` |
|
|
457
|
+
| Telegram not responding | Check token with `jaw doctor`. Ensure `jaw serve` is running |
|
|
458
|
+
| Skills not loading | `jaw skill reset` then `jaw mcp sync` |
|
|
459
|
+
| Browser commands fail | Install Chrome. Run `jaw browser start` first |
|
|
641
460
|
|
|
642
461
|
</details>
|
|
643
462
|
|
|
644
463
|
<details>
|
|
645
|
-
<summary
|
|
646
|
-
|
|
647
|
-
If you previously used **cli-claw** or an older version of cli-jaw and want a completely clean slate:
|
|
464
|
+
<summary>Fresh start β clean reinstall</summary>
|
|
648
465
|
|
|
649
466
|
```bash
|
|
650
|
-
# ββ 1. Uninstall ββ
|
|
651
467
|
npm uninstall -g cli-jaw
|
|
652
|
-
|
|
653
|
-
# Verify removal
|
|
654
|
-
which jaw && echo "β οΈ jaw still found" || echo "β
jaw removed"
|
|
655
|
-
|
|
656
|
-
# ββ 2. Back up & remove data ββ
|
|
657
|
-
# Back up current data (just in case)
|
|
658
468
|
[ -d ~/.cli-jaw ] && mv ~/.cli-jaw ~/.cli-jaw.bak.$(date +%s)
|
|
659
|
-
|
|
660
|
-
# Remove work instances
|
|
661
|
-
[ -d ~/.jaw-work ] && rm -rf ~/.jaw-work
|
|
662
|
-
|
|
663
|
-
# ββ 3. Remove launchd daemons (macOS) ββ
|
|
664
|
-
launchctl list | grep com.cli-jaw | awk '{print $3}' | \
|
|
665
|
-
xargs -I{} launchctl bootout gui/$(id -u) system/{} 2>/dev/null
|
|
666
|
-
rm -f ~/Library/LaunchAgents/com.cli-jaw.*
|
|
667
|
-
|
|
668
|
-
# ββ 4. Remove legacy artifacts ββ
|
|
669
|
-
rm -f ~/AGENTS.md ~/CLAUDE.md # postinstall symlinks
|
|
670
|
-
# Do not remove shared harness paths (~/.agents, ~/.agent) unless you explicitly
|
|
671
|
-
# created them for cli-jaw. Use: jaw doctor --repair-shared-paths
|
|
672
|
-
rm -rf ~/.cli-claw # old cli-claw data
|
|
673
|
-
rm -f ~/.copilot/mcp-config.json # MCP config synced by jaw
|
|
674
|
-
|
|
675
|
-
# ββ 5. Verify clean state ββ
|
|
676
|
-
echo "=== Clean State Check ==="
|
|
677
|
-
which jaw; which cli-jaw # should be "not found"
|
|
678
|
-
ls ~/.cli-jaw ~/.cli-claw 2>&1 # should be "No such file"
|
|
679
|
-
|
|
680
|
-
# ββ 6. Reinstall ββ
|
|
681
469
|
npm install -g cli-jaw
|
|
682
470
|
jaw init
|
|
683
471
|
jaw doctor
|
|
684
472
|
```
|
|
685
473
|
|
|
686
|
-
> π‘ Your backup is at `~/.cli-jaw.bak.<timestamp>` β copy back `settings.json` or `jaw.db` if you want to restore previous config or conversation history.
|
|
687
|
-
|
|
688
474
|
</details>
|
|
689
475
|
|
|
690
476
|
<details>
|
|
691
|
-
<summary
|
|
692
|
-
|
|
693
|
-
If you upgraded Node.js and see a `NODE_MODULE_VERSION` error, re-check and auto-rebuild native modules for the current runtime:
|
|
477
|
+
<summary>Native module mismatch (better-sqlite3)</summary>
|
|
694
478
|
|
|
695
479
|
```bash
|
|
696
480
|
npm run ensure:native
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
`npm test`, `npm run test:all`, `npm run test:integration`, `npm run test:smoke`, and `npm run build`
|
|
700
|
-
now run this guard automatically before they start.
|
|
701
|
-
|
|
702
|
-
If that still fails, reinstall dependencies under the active Node version:
|
|
703
|
-
|
|
704
|
-
```bash
|
|
705
|
-
rm -rf node_modules package-lock.json
|
|
706
|
-
npm install
|
|
481
|
+
# or: rm -rf node_modules package-lock.json && npm install
|
|
707
482
|
```
|
|
708
483
|
|
|
709
484
|
</details>
|
|
@@ -712,22 +487,16 @@ npm install
|
|
|
712
487
|
|
|
713
488
|
## π€ Contributing
|
|
714
489
|
|
|
715
|
-
|
|
490
|
+
1. Fork and branch from `master`
|
|
491
|
+
2. `npm run build && npm test`
|
|
492
|
+
3. Submit a PR
|
|
716
493
|
|
|
717
|
-
|
|
718
|
-
2. Run `npm run build && npm test` to make sure everything works
|
|
719
|
-
3. Submit a PR β we'll review it promptly
|
|
720
|
-
|
|
721
|
-
> π Found a bug or have a feature idea? [Open an issue](https://github.com/lidge-jun/cli-jaw/issues)
|
|
494
|
+
Found a bug or have an idea? [Open an issue](https://github.com/lidge-jun/cli-jaw/issues)
|
|
722
495
|
|
|
723
496
|
---
|
|
724
497
|
|
|
725
498
|
<div align="center">
|
|
726
499
|
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
Made with β€οΈ by the CLI-JAW community
|
|
730
|
-
|
|
731
|
-
[MIT License](LICENSE)
|
|
500
|
+
**[MIT License](LICENSE)**
|
|
732
501
|
|
|
733
502
|
</div>
|