Quick Links

• Install & Run · Authenticate · What is CLI-JAW?
• Features · Skills · Telegram · Voice & STT
• PABCD Orchestration · MCP · CLI Commands
• Multi-Instance · Models · Docker
• Development · Tests · Docs · Troubleshooting · Contributing

Step 1: Install WSL (PowerShell as Admin — one time only)

wsl --install

Restart your computer when prompted. After reboot, open Ubuntu from the Start Menu.

Step 2: Install CLI-JAW (in the Ubuntu/WSL terminal)

curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install-wsl.sh | bash

The script automatically installs prerequisites (curl, unzip, git), Node.js 22+, and CLI-JAW.

Step 3: Reload your shell (important — picks up PATH changes)

source ~/.bashrc

Step 4: Authenticate an AI Engine (pick one)

copilot login    # GitHub Copilot (Free)
opencode         # OpenCode (Free models available)
claude auth      # Anthropic Claude
codex login      # OpenAI Codex
gemini           # Google Gemini

Step 5: Start Chatting

jaw serve
# → http://localhost:3457

💡 The script uses fnm for Node.js management. If you already have nvm, it will use that instead.

Step 1: Open Terminal

Open Finder → Applications → Utilities → Terminal.app
(or press ⌘ Space and type Terminal)

Step 2: Paste this and hit Enter

curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install.sh | bash

This installs Node.js + CLI-JAW automatically. Just wait until you see 🎉.

Step 3: Login & Launch

copilot login    # or: claude auth / codex login / gemini login
jaw serve

Open http://localhost:3457 in your browser. That's it! 🦈

🚀 Install & Run (30 seconds)

npm install -g cli-jaw
jaw serve

That's it. Open http://localhost:3457 and start chatting. 🦈

🕐 Want it running 24/7? jaw service install — auto-detects systemd, launchd, or Docker.

Requires Node.js ≥ 22 (download) and at least 1 AI CLI authenticated below.

🔒 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.

🔑 Authenticate Your AI Engines

You only need one — pick whichever you have:

# ── Free options ──
copilot login                # GitHub Copilot (free tier)
opencode                     # OpenCode — auto-auth on first run (free models available)

# ── Paid options ──
claude auth                  # Anthropic Claude
codex login                  # OpenAI Codex
gemini                       # Google Gemini — first run triggers auth

Check what's ready: jaw doctor

🦈 CLI-JAW Doctor — 12 checks

 ✅ Node.js        v22.15.0
 ✅ npm             v10.9.4
 ✅ Claude CLI      installed
 ✅ Codex CLI       installed
 ⚠️ Gemini CLI      not found (optional)
 ✅ OpenCode CLI    installed
 ✅ Copilot CLI     installed
 ✅ Database        jaw.db OK
 ✅ Skills          22 active, 94 reference
 ✅ MCP             3 servers configured
 ✅ Memory          MEMORY.md exists
 ✅ Server          port 3457 available

💡 You don't need all 5. Even one CLI is enough. Your assistant auto-detects which engines are available and falls back gracefully.

What is CLI-JAW?

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.

💬 "Summarize today's schedule" → answer on Telegram
💬 "Refactor this module and write tests" → sub-agents handle it while you grab coffee
💬 "Download that PDF and put the key points in Notion" → browser + Notion skill, done

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. 116 built-in skills handle everything from browser automation to document generation.

🆕 What's New (v1.4.0)

What can your assistant do?

graph LR
    YOU["👤 You"] -->|Web / Terminal / Telegram| JAW["🦈 CLI-JAW"]
    JAW -->|spawn| C["Claude"]
    JAW -->|spawn| X["Codex"]
    JAW -->|spawn| G["Gemini"]
    JAW -->|spawn| O["OpenCode"]
    JAW -->|spawn| P["Copilot"]
    JAW -->|inject| SK["📦 Skills"]
    JAW -->|control| BR["🌐 Chrome"]
    JAW -->|send| TG["📱 Telegram"]
  
    style JAW fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033

• 🤖 5 AI engines, 1 assistant — Claude · Codex · Gemini · OpenCode · Copilot. Switch with /cli.
• ⚡ Auto fallback — If one engine is down, the next picks up seamlessly.
• 🎭 Multi-agent orchestration — Complex tasks get split across specialized sub-agents automatically.
• 🎤 Voice input — Mic button on the web + Telegram voice messages. Multi-provider STT (OpenAI, Vertex AI).
• 📝 Prompt templates — Create, manage, and reuse prompt templates with a visual node-map editor.
• 📦 116 skills — Browser control, file editing, image generation, web search, and much more.
• 🧠 Persistent memory — Your assistant remembers past conversations and preferences across sessions.
• 📱 Telegram bot — Chat with your assistant from your phone, send voice/photos/files.
• 🌐 Browser automation — Your assistant can navigate the web, click, type, and screenshot.
• 🔌 MCP ecosystem — Install once, available to all 5 AI engines instantly.
• 🔍 Web search — Real-time information via MCP tools.
• ⏰ Heartbeat jobs — Schedule recurring tasks that run automatically.

📦 Skill System

116 skills out of the box — browser, github, notion, telegram, memory, pdf, image generation, and much more.

Active Skills (always on)

Reference Skills (on-demand)

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.

jaw skill install <name>    # Activate a reference skill permanently

📱 Telegram — Your Assistant in Your Pocket

Your assistant isn't tied to your desk. Chat from anywhere via Telegram:

📱 Telegram ←→ 🦈 CLI-JAW ←→ 🤖 AI Engines

1. Create a bot — Message @BotFather → /newbot → copy the token
2. Configure — Run jaw init --telegram-token YOUR_TOKEN or edit settings in the Web UI
3. Start chatting — Send any message to your bot. Your chat ID is auto-saved on first message.

What you can do from Telegram:

• 💬 Chat with your assistant (any of 5 AI engines)
• 🎤 Send voice messages (auto-transcribed via multi-provider STT)
• 📎 Send files and photos for processing
• 🎙️ Combine voice + text + attachments in a single message
• ⚡ Run commands (/cli, /model, /status)
• 🔄 Switch AI engines on the fly

What your assistant sends back:

• AI responses with markdown formatting
• Generated images, PDFs, documents
• Scheduled task results (heartbeat jobs)
• Browser screenshots

🎤 Voice & STT — Speech-to-Text

CLI-JAW supports voice input across all interfaces with multi-provider STT:

Where you can use voice:

• 🌐 Web UI — Click the mic button to record and transcribe in real-time
• 📱 Telegram — Send voice messages; auto-transcribed before reaching the AI
• 🎙️ Multimodal — Combine voice + text + file attachments in a single message

All STT settings (provider, API keys, language) are managed in the Settings UI — no config files to edit.

🎭 Multi-Agent Orchestration — PABCD

For complex tasks, CLI-JAW uses PABCD — a finite state machine that enforces a strict 5-phase pipeline:

 ┌─────────────────────────────────────────────────────────┐
 │  P          A            B           C          D       │
 │  Plan  →  Audit  →    Build   →  Check  →    Done      │
 │  📝        🔍          🔨          ✅          🏁       │
 │            ↑            ↑                               │
 │            └── reject ──┘── reject (self-heal loop)     │
 └─────────────────────────────────────────────────────────┘

Key design decisions:

• DB-persisted FSM — state survives server restarts, CLI and Web UI share the same state
• Hard STOP at every phase — the AI cannot self-advance; you approve each transition
• Workers are READ-ONLY — audit and verify phases can never accidentally modify files
• Parallel-safe — independent subtasks run concurrently via Promise.all with file-overlap detection

graph TD
    USER["👤 Your Request"] --> TRIAGE["🔍 Triage — Simple or Complex?"]
  
    TRIAGE -->|Simple| DIRECT["⚡ Direct Response"]
    TRIAGE -->|Complex| P["📝 P: Plan"]
  
    P -->|approved| A["🔍 A: Audit"]
    A -->|pass| B["🔨 B: Build"]
    A -->|fail| P
    B -->|verified| C["✅ C: Check"]
    B -->|needs fix| B
    C --> D["🏁 D: Done"]
    D --> IDLE["💤 IDLE"]

    style USER fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
    style P fill:#fdf2e9,stroke:#d4a574,color:#5c4033
    style A fill:#fdf2e9,stroke:#d4a574,color:#5c4033
    style B fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
    style C fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033
    style D fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033

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.

🔌 MCP — One Config, Six AI Engines

jaw mcp install @anthropic/context7    # Install once
# → Automatically syncs to Claude, Codex, Gemini, OpenCode, Copilot, Antigravity

graph LR
    MJ["📄 mcp.json"] -->|auto-sync| CL["Claude"]
    MJ -->|auto-sync| CX["Codex"]
    MJ -->|auto-sync| GM["Gemini"]
    MJ -->|auto-sync| OC["OpenCode"]
    MJ -->|auto-sync| CP["Copilot"]
    MJ -->|auto-sync| AG["Antigravity"]
  
    style MJ fill:#f5e6d3,stroke:#d4a574,stroke-width:2px,color:#5c4033

No more editing 5 different config files. Install once → all AI engines get it.

⌨️ CLI Commands

jaw serve                         # Start server
jaw service install               # Auto-start on boot (systemd/launchd/docker auto-detected)
jaw service status                # Check daemon status
jaw service unset                 # Remove auto-start
jaw service logs                  # View service logs
jaw chat                          # Terminal TUI
jaw doctor                        # Diagnostics (12 checks)
jaw skill install <name>          # Install a skill
jaw mcp install <package>         # Install MCP → syncs to all 6 CLIs
jaw memory search <query>         # Search memory
jaw browser start                 # Launch Chrome (CDP)
jaw browser vision-click "Login"  # AI-powered click
jaw clone ~/my-project            # Clone instance for a separate project
jaw --home ~/my-project serve --port 3458  # Run a second instance
jaw reset                         # Full reset

🏗️ Multi-Instance — Separate Projects, Separate Contexts

Run multiple isolated instances of CLI-JAW — each with its own settings, memory, skills, and database.

# Clone your default instance to a new project
jaw clone ~/my-project

# Run it on a different port
jaw --home ~/my-project serve --port 3458

# Or auto-start both on boot
jaw service                                    # default → port 3457 (auto-detect backend)
jaw --home ~/my-project service --port 3458    # project → port 3458

Each instance is fully independent — different working directory, different memory, different MCP config. Perfect for separating work/personal contexts or per-project AI setups.

🤖 Models

Each CLI comes with preconfigured presets, but you can type any model ID directly.

🔧 To add models: edit src/cli/registry.ts — one file, auto-propagates everywhere.

🐳 Docker — Container Isolation

Run CLI-JAW in a Docker container for security isolation — AI agents cannot access host files.

# Quick start (after npm publish)
docker compose up -d
# → http://localhost:3457

# Or build manually
docker build -t cli-jaw .
docker run -d -p 3457:3457 --env-file .env --name jaw cli-jaw

Two Dockerfiles:

# Dev build (local source)
docker build -f Dockerfile.dev -t cli-jaw:dev .
docker run -d -p 3457:3457 --env-file .env cli-jaw:dev

# Pin version for CI
docker build --build-arg CLI_JAW_VERSION=1.0.1 -t cli-jaw:1.0.1 .

# If Chromium sandbox fails in your environment
docker run -e CHROME_NO_SANDBOX=1 -p 3457:3457 cli-jaw

Security:

• Non-root jaw user — Chromium sandbox enabled by default
• No ipc: host or seccomp=unconfined — full container isolation
• --no-sandbox only via explicit CHROME_NO_SANDBOX=1 opt-in
• Build-time feature guard prevents outdated image deployment

Volumes: Data persists in jaw-data named volume (/home/jaw/.cli-jaw).
To use existing host config: -v ~/.cli-jaw:/home/jaw/.cli-jaw

🛠️ Development

# Build (TypeScript → JavaScript)
npm run build          # tsc → dist/

# Run from source (development)
npm run dev            # tsx server.ts (hot-reload friendly)
npx tsx bin/cli-jaw.ts serve   # Run CLI directly from .ts

# Run from build (production)
node dist/bin/cli-jaw.js serve

Project structure:

src/
├── agent/          # AI agent lifecycle & spawning
├── browser/        # Chrome CDP automation
├── cli/            # CLI registry & model presets
├── core/           # DB, config, logging
├── http/           # Express server & middleware
├── memory/         # Persistent memory system
├── orchestrator/   # Multi-agent orchestration pipeline
├── prompt/         # Prompt injection & AGENTS.md generation
├── routes/         # REST API endpoints (40+)
├── security/       # Input sanitization & guardrails
└── telegram/       # Telegram bot integration

TypeScript with strict: true, NodeNext module resolution, targeting ES2022.

🧪 Tests

npm test

All tests run via tsx --test (native Node.js test runner + TypeScript).

📖 Documentation

❓ Troubleshooting

If you previously used cli-claw or an older version of cli-jaw and want a completely clean slate:

# ── 1. Uninstall ──
npm uninstall -g cli-jaw

# Verify removal
which jaw && echo "⚠️  jaw still found" || echo "✅ jaw removed"

# ── 2. Back up & remove data ──
# Back up current data (just in case)
[ -d ~/.cli-jaw ] && mv ~/.cli-jaw ~/.cli-jaw.bak.$(date +%s)

# Remove work instances
[ -d ~/.jaw-work ] && rm -rf ~/.jaw-work

# ── 3. Remove launchd daemons (macOS) ──
launchctl list | grep com.cli-jaw | awk '{print $3}' | \
  xargs -I{} launchctl bootout gui/$(id -u) system/{}  2>/dev/null
rm -f ~/Library/LaunchAgents/com.cli-jaw.*

# ── 4. Remove legacy artifacts ──
rm -f ~/AGENTS.md ~/CLAUDE.md          # postinstall symlinks
# Do not remove shared harness paths (~/.agents, ~/.agent) unless you explicitly
# created them for cli-jaw. Use: jaw doctor --repair-shared-paths
rm -rf ~/.cli-claw                     # old cli-claw data
rm -f ~/.copilot/mcp-config.json       # MCP config synced by jaw

# ── 5. Verify clean state ──
echo "=== Clean State Check ==="
which jaw; which cli-jaw               # should be "not found"
ls ~/.cli-jaw ~/.cli-claw 2>&1         # should be "No such file"

# ── 6. Reinstall ──
npm install -g cli-jaw
jaw init
jaw doctor

💡 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.

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repo and create your branch from master
2. Run npm run build && npm test to make sure everything works
3. Submit a PR — we'll review it promptly

📋 Found a bug or have a feature idea? Open an issue