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.md CHANGED
@@ -1,18 +1,14 @@
1
1
  <div align="center">
2
2
 
3
- # 🦈 CLI-JAW
3
+ # CLI-JAW
4
4
 
5
- ### Your Personal AI Assistant β€” Powered by 5 AI Engines
5
+ ### All your AI subscriptions. One assistant.
6
6
 
7
- *One assistant. Five brains. Always on.*
8
-
9
- [![Tests](https://img.shields.io/badge/tests-rolling%20inventory-blue)](#-tests)
7
+ [![npm](https://img.shields.io/npm/v/cli-jaw)](https://npmjs.com/package/cli-jaw)
10
8
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://typescriptlang.org)
11
9
  [![Node](https://img.shields.io/badge/node-%3E%3D22-blue)](https://nodejs.org)
12
10
  [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
13
- [![npm](https://img.shields.io/npm/v/cli-jaw)](https://npmjs.com/package/cli-jaw)
14
- [![Docker](https://img.shields.io/badge/Docker-supported-2496ED?logo=docker&logoColor=white)](#-docker--container-isolation)
15
- [![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20WSL%20%7C%20Docker-lightgrey)](#)
11
+ [![Docker](https://img.shields.io/badge/Docker-supported-2496ED?logo=docker&logoColor=white)](#-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
- ## Quick Links
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 & Run](#-install--run-30-seconds) Β· [Authenticate](#-authenticate-your-ai-engines) Β· [What is CLI-JAW?](#what-is-cli-jaw)
26
- - [Features](#what-can-your-assistant-do) Β· [Skills](#-skill-system) Β· [Telegram](#-telegram--your-assistant-in-your-pocket) Β· [Voice & STT](#-voice--stt--speech-to-text)
27
- - [PABCD Orchestration](#-multi-agent-orchestration--pabcd) · [MCP](#-mcp--one-config-six-ai-engines) · [CLI Commands](#️-cli-commands)
28
- - [Multi-Instance](#️-multi-instance--separate-projects-separate-contexts) · [Models](#-models) · [Docker](#-docker--container-isolation)
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>πŸͺŸ <b>Are you on Windows?</b> β€” WSL One-Click Setup</summary>
39
+ <summary>Are you on Windows? β€” WSL one-click setup</summary>
33
40
 
34
- **Step 1: Install WSL** (PowerShell as Admin β€” one time only)
41
+ **Step 1: Install WSL** (PowerShell as Admin)
35
42
 
36
43
  ```powershell
37
44
  wsl --install
38
45
  ```
39
46
 
40
- Restart your computer when prompted. After reboot, open **Ubuntu** from the Start Menu.
47
+ Restart, then open **Ubuntu** from the Start Menu.
41
48
 
42
- **Step 2: Install CLI-JAW** (in the Ubuntu/WSL terminal)
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
- The script automatically installs WSL prerequisites, Node.js 22+, user-local npm globals, browser deps, OfficeCLI, and CLI-JAW.
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>πŸ”§ <b>Troubleshooting WSL</b></summary>
64
+ <summary>Troubleshooting WSL</summary>
77
65
 
78
- | Problem | Fix |
79
- | --------------------------------------- | ------------------------------------------------------ |
80
- | `unzip: command not found` | Rerun the installer β€” it now auto-installs `unzip` |
81
- | `jaw: command not found` after install | Run `source ~/.bashrc` to reload PATH |
82
- | Still can't find `jaw` | Run `export PATH="$(npm config get prefix)/bin:$PATH"` |
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>🍎 <b>New to the terminal?</b> β€” One-click Node.js + CLI-JAW install</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
- **Step 2: Paste this and hit Enter**
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
- This installs Node.js + CLI-JAW automatically. Just wait until you see πŸŽ‰.
105
-
106
- **Step 3: Login & Launch**
85
+ 3. Authenticate and launch:
107
86
 
108
87
  ```bash
109
- copilot login # or: claude auth / codex login / gemini 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 & Run (30 seconds)
96
+ ## πŸš€ Install & run
120
97
 
121
98
  ```bash
122
99
  npm install -g cli-jaw
123
100
  jaw serve
124
101
  ```
125
102
 
126
- **That's it.** Open **http://localhost:3457** and start chatting. 🦈
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
- > Requires **Node.js β‰₯ 22** ([download](https://nodejs.org)) and **at least 1 AI CLI** authenticated below.
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 Your AI Engines
109
+ ## πŸ”‘ Authenticate
137
110
 
138
- You only need **one** β€” pick whichever you have:
111
+ You only need one. Pick whichever subscription you already have:
139
112
 
140
113
  ```bash
141
- # ── Free options ──
142
- copilot login # GitHub Copilot (free tier)
143
- opencode # OpenCode β€” auto-auth on first run (free models available)
144
-
145
- # ── Paid options ──
146
- claude auth # Anthropic Claude
147
- codex login # OpenAI Codex
148
- gemini # Google Gemini β€” first run triggers auth
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 what's ready: `jaw doctor`
124
+ Check status: `jaw doctor`
152
125
 
153
126
  <details>
154
- <summary>πŸ“‹ Example <code>jaw doctor</code> output</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
- ## What is CLI-JAW?
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
- ![1772128366759](image/README/1772128366759.png)
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
- Unlike single-model assistants, CLI-JAW orchestrates **5 AI engines** (Claude, Codex, Gemini, OpenCode, Copilot) through their official CLIs β€” giving you the best of every provider in one unified experience. If one engine is busy, it automatically falls back to the next. **100+ built-in skills** handle everything from browser automation to document generation.
151
+ CLI-JAW works from five surfaces. Same assistant, same memory, same skills across all of them.
189
152
 
190
- | | Why CLI-JAW? |
191
- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
192
- | πŸ›‘οΈ**TOS-Safe** | Uses official CLIs only β€” no API key scraping, no reverse engineering, no ban risk. |
193
- | πŸ€–**Verified Agent Tools** | 5 battle-tested coding agents (Claude, Codex, Gemini, OpenCode, Copilot) under one roof. |
194
- | ⚑**Multi-Agent Fallback** | One engine down? The next picks up automatically. Zero downtime. |
195
- | 🎭**PABCD Orchestration** | DB-persisted FSM pipeline β€” Plan β†’ Audit β†’ Build β†’ Check β†’ Done. Workers are read-only. You approve every phase. |
196
- | πŸ“¦**100+ Built-in Skills** | Browser automation, document generation, Telegram/Discord, memory β€” ready out of the box. |
197
- | πŸ–₯️**Cross-Platform** | macOS, Linux, Windows β€” ENOENT-safe CLI spawn, auto-detection,`.cmd` shim support, and native install all work across platforms. |
198
-
199
- ![CLI-JAW Terminal](docs/screenshots/terminal-cli.png)
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
- ## πŸ†• What's New (v1.6.0)
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
- - Full update log: [CHANGELOG.md](CHANGELOG.md#160---2026-04-13)
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
- | Feature | Description |
213
- | ------- | ----------- |
214
- | 🎭 **PABCD Orchestration** | Orchestration is now a first-class surface: `jaw dispatch`, `jaw orchestrate`, persisted PABCD state, worker registry, research dispatch, and live orchestration status in the product. |
215
- | 🧠 **Structured Memory Runtime** | Memory moved beyond plain persistence into a layered indexed subsystem: structured storage, bootstrap/migration, SQLite FTS5 indexing, query expansion, task snapshots, and UI controls for audit/reindex flows. |
216
- | πŸ’¬ **Discord + Voice Channels** | CLI-JAW now works across Web, Terminal, Telegram, and Discord. Voice/STT also became a first-class workflow with web recording, Telegram voice handling, and provider-configurable transcription. |
217
- | πŸ–₯️ **Major Web UI Expansion** | The web app gained richer settings panes, memory and heartbeat controls, tool UI, provider icons, gesture handling, drag/drop protections, stronger streaming render behavior, and virtual scrolling. |
218
- | πŸ“Š **Diagram & Widget Rendering** | Inline diagrams and sandboxed widget rendering became visible product features, backed by dedicated iframe rendering, validation, and CSS/runtime updates. |
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
- ## What can your assistant do?
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
- - πŸ€– **5 AI engines, 1 assistant** β€” Claude Β· Codex Β· Gemini Β· OpenCode Β· Copilot. Switch with `/cli`.
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
- ## πŸ“¦ Skill System
183
+ ## 🧠 Memory
258
184
 
259
- **100+ skills** out of the box β€” browser, github, notion, telegram, memory, pdf, image generation, and [much more](#).
185
+ Three layers, each serving a different recall horizon.
260
186
 
261
- <details>
262
- <summary>View all skills</summary>
263
-
264
- | Tier | Count | How it works |
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
- #### Reference Skills (on-demand)
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
- </details>
195
+ Advanced memory includes profile summary, bootstrap/migration, and reindex flows accessible from the Web UI settings.
294
196
 
295
197
  ---
296
198
 
297
- ## πŸ“± Telegram β€” Your Assistant in Your Pocket
199
+ ## 🎭 Orchestration β€” PABCD
298
200
 
299
- Your assistant isn't tied to your desk. Chat from anywhere via Telegram:
201
+ For complex tasks, CLI-JAW uses a 5-phase state machine. You approve every transition.
300
202
 
301
203
  ```
302
- πŸ“± Telegram ←→ 🦈 CLI-JAW ←→ πŸ€– AI Engines
204
+ P (Plan) β†’ A (Audit) β†’ B (Build) β†’ C (Check) β†’ D (Done) β†’ IDLE
205
+ β›” β›” β›” auto auto
303
206
  ```
304
207
 
305
- <details>
306
- <summary>πŸ“‹ Telegram setup (3 steps)</summary>
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
- 1. **Create a bot** β€” Message [@BotFather](https://t.me/BotFather) β†’ `/newbot` β†’ copy the token
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
- </details>
218
+ ---
313
219
 
314
- **What you can do from Telegram:**
220
+ ## πŸ“¦ Skills
315
221
 
316
- - πŸ’¬ Chat with your assistant (any of 5 AI engines)
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
- **What your assistant sends back:**
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
- - AI responses with markdown formatting
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
- <p align="center">
331
- <img src="docs/screenshots/telegram-bot.png" width="300" alt="Telegram Bot" />
332
- </p>
235
+ ```bash
236
+ jaw skill install <name> # activate a reference skill
237
+ ```
333
238
 
334
239
  ---
335
240
 
336
- ## 🎀 Voice & STT β€” Speech-to-Text
241
+ ## 🌐 Browser & desktop automation
337
242
 
338
- CLI-JAW supports voice input across all interfaces with multi-provider STT:
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
- | Provider | How to enable |
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
- **Where you can use voice:**
253
+ ## πŸ”Œ MCP
347
254
 
348
- - 🌐 **Web UI** β€” Click the mic button to record and transcribe in real-time
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
- All STT settings (provider, API keys, language) are managed in the **Settings UI** β€” no config files to edit.
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
- ## 🎭 Multi-Agent Orchestration β€” PABCD
270
+ ## πŸ’¬ Messaging
357
271
 
358
- For complex tasks, CLI-JAW uses **PABCD** β€” a finite state machine that enforces a strict 5-phase pipeline:
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
- | Phase | Name | What happens |
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
- Activate manually with `jaw orchestrate` or let the assistant decide automatically. The Web UI shows a live roadmap bar with phase indicators and a 🦈 runner animation.
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
- ![Orchestration Log](docs/screenshots/orchestration-log.png)
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
- ## πŸ”Œ MCP β€” One Config, Six AI Engines
289
+ ### Discord
414
290
 
415
- ```bash
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
- ```mermaid
421
- graph LR
422
- MJ["πŸ“„ mcp.json"] -->|auto-sync| CL["Claude"]
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
- No more editing 5 different config files. Install once β†’ all AI engines get it.
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 Commands
309
+ ## ⌨️ CLI commands
437
310
 
438
311
  ```bash
439
- jaw serve # Start server
440
- jaw service install # Auto-start on boot (systemd/launchd/docker auto-detected)
441
- jaw service status # Check daemon status
442
- jaw service unset # Remove auto-start
443
- jaw service logs # View service logs
444
- jaw chat # Terminal TUI
445
- jaw doctor # Diagnostics (12 checks)
446
- jaw skill install <name> # Install a skill
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 ~/my-project # Clone instance for a separate project
452
- jaw --home ~/my-project serve --port 3458 # Run a second instance
453
- jaw reset # Full reset
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-Instance β€” Separate Projects, Separate Contexts
330
+ ## πŸ—οΈ Multi-instance
459
331
 
460
- Run multiple isolated instances of CLI-JAW β€” each with its own settings, memory, skills, and database.
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. Perfect for separating work/personal contexts or per-project AI setups.
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 β€” Container Isolation
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
- # Quick start (after npm publish)
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
- <details>
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
- | File | Purpose | Use Case |
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 (local source)
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 for CI
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 in your environment
362
+ # If Chromium sandbox fails
540
363
  docker run -e CHROME_NO_SANDBOX=1 -p 3457:3457 cli-jaw
541
364
  ```
542
365
 
543
- **Security:**
366
+ </details>
367
+
368
+ ---
369
+
370
+ ## πŸ“– Documentation
544
371
 
545
- - Non-root `jaw` user β€” Chromium sandbox enabled by default
546
- - No `ipc: host` or `seccomp=unconfined` β€” full container isolation
547
- - `--no-sandbox` only via explicit `CHROME_NO_SANDBOX=1` opt-in
548
- - Build-time feature guard prevents outdated image deployment
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
- **Volumes:** Data persists in `jaw-data` named volume (`/home/jaw/.cli-jaw`).
551
- To use existing host config: `-v ~/.cli-jaw:/home/jaw/.cli-jaw`
383
+ ---
552
384
 
553
- </details>
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, run, and project structure</summary>
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 & spawning
579
- β”œβ”€β”€ browser/ # Chrome CDP automation
580
- β”œβ”€β”€ cli/ # CLI registry & model presets
581
- β”œβ”€β”€ core/ # DB, config, logging
582
- β”œβ”€β”€ http/ # Express server & middleware
583
- β”œβ”€β”€ memory/ # Persistent memory system
584
- β”œβ”€β”€ orchestrator/ # Multi-agent orchestration pipeline
585
- β”œβ”€β”€ prompt/ # Prompt injection & AGENTS.md generation
586
- β”œβ”€β”€ routes/ # REST API endpoints (40+)
587
- β”œβ”€β”€ security/ # Input sanitization & guardrails
588
- └── telegram/ # Telegram bot integration
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
- All tests run via `tsx --test` (native Node.js test runner + TypeScript).
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 | Solution |
631
- | ---------------------------- | ------------------------------------------------------------------------------------------ |
632
- | `cli-jaw: command not found` | Run `npm install -g cli-jaw` again. Check `npm bin -g` is in your `$PATH`. |
633
- | `Error: node version` | Upgrade to Node.js β‰₯ 22:`nvm install 22` or download from [nodejs.org](https://nodejs.org) |
634
- | `NODE_MODULE_VERSION` mismatch | Run `npm run ensure:native` (auto-rebuild) or reinstall dependencies for the current Node version |
635
- | Agent timeout / no response | Run `jaw doctor` to check CLI auth. Re-authenticate with `claude auth` / `codex login`. |
636
- | `EADDRINUSE: port 3457` | Another instance is running. Stop it or use `jaw serve --port 3458`. |
637
- | Telegram bot not responding | Check token with `jaw doctor`. Ensure `jaw serve` is running. |
638
- | Telegram βœ“βœ“ delayed | Normal β€” Telegram server-side delivery ack can take a few minutes under load. Not a bug. |
639
- | Skills not loading | Run `jaw skill reset` then `jaw mcp sync`. |
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>πŸ”„ Fresh start β€” clean reinstall for legacy / cli-claw users</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>🧱 Native module mismatch (<code>better-sqlite3</code>)</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
- Contributions are welcome! Here's how to get started:
490
+ 1. Fork and branch from `master`
491
+ 2. `npm run build && npm test`
492
+ 3. Submit a PR
716
493
 
717
- 1. Fork the repo and create your branch from `master`
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
- **⭐ If CLI-JAW helps you, give it a star β€” it means a lot!**
728
-
729
- Made with ❀️ by the CLI-JAW community
730
-
731
- [MIT License](LICENSE)
500
+ **[MIT License](LICENSE)**
732
501
 
733
502
  </div>