clew-code 0.2.27 → 0.2.29

package/README.md

@@ -12,8 +12,8 @@ A multi-provider AI coding CLI that codes, learns your preferences, coordinates
 [![Contributors](https://img.shields.io/github/contributors/ClewCode/ClewCode.svg)](https://github.com/ClewCode/ClewCode/graphs/contributors)
 [![Release](https://img.shields.io/github/v/release/ClewCode/ClewCode)](https://github.com/ClewCode/ClewCode/releases)
 [![npm](https://img.shields.io/npm/v/clew-code)](https://www.npmjs.com/package/clew-code)
-[![CI](https://img.shields.io/github/actions/workflow/status/ClewCode/ClewCode/release.yml?branch=main)](https://github.com/ClewCode/ClewCode/actions)
-[![License: MIT](https://img.shields.io/badge/license-GPL3-blue.svg)](#license)
+[![CI](https://img.shields.io/github/actions/workflow/status/ClewCode/ClewCode/ci.yml?branch=main)](https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](#license)
 [![Platform](https://img.shields.io/badge/platform-macOS%20·%20Windows%20·%20Linux-lightgrey.svg)](#installation)
 [![Built with Bun](https://img.shields.io/badge/built%20with-Bun-ff69b4.svg)](https://bun.sh)
 
@@ -25,35 +25,40 @@ A multi-provider AI coding CLI that codes, learns your preferences, coordinates
 
 ## Hacking in public
 
-Clew Code is a fork of [Claude Code](https://github.com/anthropics/claude-code) (Anthropic), rebuilt from the ground up to be **multi-provider** — you're not locked into one API. As of this writing the project ships agent-to-agent LAN mesh coordination, a preference-learning engine, autonomous background loops, multi-pass context compaction, MCP integration, plan mode with full bypass permissions, and 27 provider adapters.
+Clew Code is a reverse-engineered reimplementation of [Claude Code](https://github.com/anthropics/claude-code) (Anthropic), rebuilt from the ground up to be **multi-provider** — you're not locked into one API. As of this writing the project ships agent-to-agent LAN peer coordination, a preference-learning engine, autonomous background loops, multi-pass context compaction, MCP integration, plan mode with full bypass permissions, goal verification, Max Mode parallel candidates, structured checkpoints, automated memory consolidation, and 27+ provider adapters.
 
-> Forked from Claude Code. Rebuilt for every provider.
+> Reverse-engineered from Claude Code. Rebuilt for every provider.
 
 ---
 
 ## Features
 
-- **27 providers** — Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, xAI (Grok), Mistral, Cohere, Perplexity, Cerebras, Moonshot (Kimi), Zhipu (GLM), NVIDIA NIM, OpenRouter, GitHub Copilot, OpenCode, KiloCode, Ollama (local), Together AI, Fireworks AI, Deep Infra, SiliconFlow, Hugging Face, Poe, DigitalOcean, Cline, OpenCode Go. Switch mid-session.
-- **Agent-to-agent mesh** — find other Clew instances on the same machine (file registry) or across machines (UDP multicast). Assign tasks, set roles, execute remote commands — 15 mesh AI tools (discover, run, spawn, share, join, ping, broadcast, send_message, list_roles, list_messages, set_name, set_role, disconnect, info, help) let your agent coordinate autonomously via `/mesh` commands.
+- **27+ providers** — Anthropic, OpenAI, Google Gemini & Code Assist, DeepSeek, Groq, xAI (Grok), Mistral, Cohere, Perplexity, Cerebras, Moonshot (Kimi), Zhipu (GLM), NVIDIA NIM, OpenRouter, OpenCode, KiloCode, Ollama (local), Together AI, Fireworks AI, Deep Infra, SiliconFlow, Hugging Face, Poe, DigitalOcean, Cline, OpenCode Go. Switch mid-session.
+- **Peer-to-peer LAN** — find other Clew instances on the same machine (file registry) or across machines (UDP multicast). Assign tasks, set roles, execute remote commands — 15 peer AI tools let your agent coordinate autonomously via `/peer` commands.
 
 - **Autonomous agent loop** — file-backed persistent task queue, lease-based concurrency, exponential backoff retry, dead-letter management. Cron scheduler for recurring jobs. Max 3 concurrent workers.
-- **50+ built-in tools** — Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch, Browser (Playwright), PR (create/list/view/review/merge/status), NotebookEdit, JsonPath, mesh tools (15 LAN coordination tools), MCP tools, ProcessMesh (exec/pty), plan mode with full bypass permissions, multi-pass context compaction.
+- **50+ built-in tools** — Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch, Browser (Playwright), PR (create/list/view/review/merge/status), NotebookEdit, JsonPath, ReadArtifact, peer tools (15 LAN coordination tools), MCP tools, ProcessPeer (exec/pty), plan mode with full bypass permissions, multi-pass context compaction.
+- **Goal system** — `/goal` tracks task completion with heuristic pre-checks (exit codes, test output, lint results). Goal chains with `then` syntax. Auto-integrates with AFK mode and the autonomous loop.
+- **Goal Verifier** — When the agent attempts to terminate, an independent LLM verifier reviews the conversation against the goal text. If unsatisfied, the gap is reported as metadata for automatic re-prompting.
+- **Max Mode** — parallel candidate generation (default 3 per turn) using forked agents. Selects the best response via LLM judge (model-as-judge) with heuristic fallback. Toggle with `/maxmode`.
+- **Structured checkpoints** — automatic progress snapshots at 20%/45%/70% milestones with notes scratchpad (`notes.md`) for main-agent findings. Multi-cycle rebuild from checkpoints during compaction preserves layered context (decisions → notes → blockers → next steps).
+- **Project memory promotion** — at the 70% checkpoint, stable information (active files, persistent decisions, notes) is promoted to `MEMORY.md` for cross-session persistence.
+- **Automated memory consolidation** — Dream process (7-day cycle) merges duplicate insights and creates weekly digests. Distill process (30-day cycle) extracts reusable patterns and generates skill suggestions.
 - **MCP — Model Context Protocol** — connect external tools via stdio (local subprocesses), SSE (remote servers with OAuth), or DirectConnect (in-process plugin servers).
 - **Skills, plugins, hooks** — extend without touching source. Skills via `SKILL.md`, plugins with manifest, hooks at every lifecycle stage (PreToolUse, PostToolUse, PreBash, PostPrompt, PreAcceptEdit).
-- **7 permission modes** — default, ask, plan, auto, acceptEdits, bypassPermissions, dontAsk. Granular allow/deny rules with pattern matching.
+- **8 permission modes** — default, ask, plan, auto, acceptEdits, bypassPermissions, dontAsk, guardian. Granular allow/deny rules with pattern matching.
 
 ---
 
-## Concepts: Agents, Subagents, Mesh, and ACP
+## Concepts: Agents, Subagents, and Peers
 
 Clew Code has several execution layers. They are related, but they do different jobs:
 
-- **Agent:** An AI worker with a prompt, model, tools, and permissions. The main chat session is an agent. Custom agents live in `.claude/agents/*.md`, and built-ins include `Explore`, `Plan`, and `general-purpose`.
+- **Agent:** An AI worker with a prompt, model, tools, and permissions. The main chat session is an agent. Custom agents live in `.clew/agents/*.md`, and built-ins include `Explore`, `Plan`, and `general-purpose`.
 - **Subagent:** A short-lived child agent launched by another agent through the `Agent` tool. Use subagents for independent work such as codebase exploration, test triage, or review. The built-in `Explore` agent is read-only and is the right choice for parallel "go inspect this area" tasks.
 - **Teammate / Swarm:** A longer-lived agent team member with an identity, mailbox, task coordination, and optional pane/tmux or in-process execution. Use this when agents need to keep working together across multiple turns, not for isolated one-shot exploration.
-- **LAN Mesh:** A network of Clew instances on the same machine or LAN. `/mesh` discovers peers, sends messages, assigns tasks, and runs commands on other Clew nodes.
-- **Process Mesh:** A local process-backed worker layer. It delegates a prompt to an external CLI/provider such as Codex using `exec` or `pty`, then returns stdout, stderr, exit code, timeout state, and progress.
-- **ACP:** An external protocol boundary. Editors, IDEs, REST clients, or other agents can send work into Clew through ACP. ACP should normalize the external request and route execution through Clew's internal layers instead of hardcoding a provider in every ACP entry point.
+- **LAN Peer:** A network of Clew instances on the same machine or LAN. `/peer` discovers peers, sends messages, assigns tasks, and runs commands on other Clew nodes.
+- **Process Peer:** A local process-backed worker layer. It delegates a prompt to an external CLI/provider such as Codex using `exec` or `pty`, then returns stdout, stderr, exit code, timeout state, and progress.
 
 Typical flows:
 
@@ -64,17 +69,9 @@ User
           -> short-lived subagent, e.g. Explore
 ```
 
-```text
-External editor / external agent
-  -> ACP
-      -> shared ACP-to-mesh boundary
-          -> Process Mesh provider, e.g. codex
-              -> external CLI process
-```
-
 ```text
 Clew instance A
-  -> LAN Mesh
+  -> LAN Peer
       -> Clew instance B
           -> local agent, daemon task, or process worker
 ```
@@ -83,13 +80,36 @@ Use the layers by intent:
 
 - Need a quick independent read-only investigation? Use an `Explore` subagent.
 - Need long-running coordination between named workers? Use teammates/swarm.
-- Need another Clew instance on the LAN? Use `/mesh`.
-- Need an external editor or agent to call into Clew? Use ACP.
-- Need Clew to run a local external worker such as Codex? Use Process Mesh.
+- Need another Clew instance on the LAN? Use `/peer`.
+- Need Clew to run a local external worker such as Codex? Use Process Peer.
 
 Other runtime concepts:
 - **Plan mode:** Full-access planning mode with bypass permissions — explore, read, write, and edit files freely. Plan files persist to `.clew/plans/long-term-plan.md` with task progress snapshot.
 - **Multi-pass compaction:** Automatic chunk-based context compression with recursive re-compaction when context exceeds the model window.
+- **Goal verification:** When the agent declares a task done, an independent LLM call reviews the conversation against the goal text and reports specific gaps if unsatisfied (attached as `goalGap` in result metadata).
+- **Max Mode:** Generates N parallel candidate responses per turn via forked agents, then selects the best one via LLM judge with heuristic fallback. Toggle with `/maxmode`.
+- **Checkpoints:** Structured snapshots at 20%/45%/70% progress milestones. Includes a `notes.md` scratchpad for the main agent's findings. Used for layered multi-cycle rebuild during compaction.
+
+---
+
+## Profiles: Coding vs Personal
+
+Clew Code has two profiles you switch between with `/profile`:
+
+- **Coding profile** (`/profile coding`) — default. Directly implement software changes: inspect repo, edit files, run validation.
+- **Personal profile** (`/profile personal`) — command center mode. Plan, split tasks, **delegate** code work to a Codex worker via `process_peer`, then review and summarize results.
+
+### How personal delegation works
+
+```
+You → personal profile → understand requirement → plan approach
+     → /delegate skill → ProcessPeer → Codex worker
+     → worker implements → report back → you review
+```
+
+In personal profile, you never edit files directly — the `delegate` skill spawns a Codex worker with a structured task prompt (goal, scope, constraints, validation criteria) and reports what was done, what passed/failed, and what's blocked. Use personal profile when you want to orchestrate rather than implement.
+
+Profile and last-used permission mode are saved between sessions.
 
 ---
 
@@ -144,9 +164,11 @@ clew
 # In-session commands
 ❯ /help           # list everything
 ❯ /status         # current provider, model, context info
-❯ /mesh discover # find other Clew instances on LAN
+❯ /goal "tests pass"  # track task completion
+❯ /maxmode on     # parallel candidate generation
+❯ /peer discover  # find other Clew instances on LAN
 ❯ /mcp list       # connected MCP servers
-❯ /loop start     # background autonomous loop
+❯ /daemon        # background autonomous loop
 
 # One-shot mode (pipe-friendly)
 clew -p "summarize CHANGELOG.md"
@@ -167,7 +189,7 @@ export DEEPSEEK_API_KEY=...
 export GROQ_API_KEY=...
 export OPENROUTER_API_KEY=...
 export OLLAMA_HOST=http://localhost:11434
-export COPILOT_GITHUB_TOKEN=gho_...
+export GEMINI_API_KEY=...
 ```
 
 ---
@@ -175,14 +197,17 @@ export COPILOT_GITHUB_TOKEN=gho_...
 ## Commands
 
 <details>
-<summary><strong>17 slash commands</strong></summary>
+<summary><strong>21 slash commands</strong></summary>
 
 ```
 /model        Switch provider or model
 /status       Provider, session, context info
 /doctor       Diagnostics
+/profile      Switch between coding and personal profiles
 /context      Active context usage
 /compact      Compress conversation history
+/goal         Track and verify task completion
+/maxmode      Toggle parallel candidate generation
 /mcp          MCP server management
 /code-review  Review changed files for bugs
 /simplify     Cleanup-focused review
@@ -190,11 +215,12 @@ export COPILOT_GITHUB_TOKEN=gho_...
 /bridge       Bridge mode config
 /agent        Background agent dispatch & subcommands
 /agents       TUI Agent dashboard (operational view)
-/mesh        Collaborate with Clew instances on LAN (formerly /peer)
+/peer         Collaborate with Clew instances on LAN
 /remote       WebSocket remote control
-/loop         24/7 autonomous agent loop
 /daemon       Autonomous daemon dashboard
 /task         Scheduled tasks
+/memory       Long-term memory search and management
+/tasks        Curated task list management
 ```
 
 </details>
@@ -214,13 +240,18 @@ src/
 ├── commands/                # Slash command implementations
 ├── tools/                   # 50+ built-in tools
 ├── services/
-│   ├── ai/                  # Provider manager + 27 providers
+│   ├── ai/                  # Provider manager + 27+ providers
 │   ├── mcp/                 # MCP client + auth + transports
 │   ├── plugins/             # Plugin hooks + marketplace
 │   ├── autonomous/          # Agent loop + task queue + cron
+│   ├── checkpoint/          # Structured progress checkpoints
+│   ├── goal/                # Goal evaluation and verification
+│   ├── longTermMemory/      # Dream (7d) + Distill (30d) consolidation
+│   ├── maxMode/             # Candidate runner + evaluator
 │   ├── lsp/                 # LSP integration
 │   └── Supervisor/          # Agent supervisor IPC
-├── mesh/                    # MeshServer + MeshDiscovery (agent-to-agent)
+├── peer/                    # PeerServer + PeerDiscovery (agent-to-agent)
+├── memory/                  # Long-term memory (SQLite, FTS5)
 ├── bridge/                  # WebSocket bridge + relay
 ├── components/              # Ink terminal UI components
 ├── state/                   # AppState management
@@ -278,15 +309,19 @@ We welcome contributions. Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_COND
 ## Changelog
 
 <details>
-<summary><strong>v0.2.7 — 2026-06-11</strong></summary>
-
-- **process_peer PTY terminal box** — terminal-style progress box with ANSI-preserving output tail
-- **`/mesh run codex <task>`** — run one-shot Codex process peer from chat
-- **Auto-update dialog** — npm update notification before app starts
-- **Rich model fetching** — API models now carry context window, vision, tools, reasoning, free tags
-- **`/model list` capability tags** — `[200K ctx, vision, tools, reason, free]` per model
-- **GlimmerMessage gradient** — per-character color interpolation with fade effect
-- **Cost in status line** — shows session cost when >$0
+<summary><strong>v0.2.22 — 2026-06-15</strong></summary>
+
+- **Max Mode** — parallel candidate generation (default 3 per turn), `/maxmode` command
+- **Goal system** — `/goal` with heuristic pre-checks, goal chains (`then`), AFK integration
+- **Structured checkpoints** — progress snapshots at 20%/45%/70%, session rebuild from checkpoints
+- **Dream process** — 7-day automated memory consolidation cycle
+- **Distill process** — 30-day pattern extraction and reusable skill generation
+- **Video input** — paste mp4/mov/webm to video-capable models (Gemini, GPT-5.x)
+- **Image & Video generation** — `GenerateImage` (DALL-E 3, Imagen 3) and `GenerateVideo` (Runway Gen-4)
+- **Profile system** — `/profile` switches between `coding` and `personal` profiles
+- **Execution modes** — `/mode` with `safe`, `yolo`, `afk`, `review-only`, `browser-safe`
+- **ReadArtifact tool** — read truncated large outputs in chunks
+- **Bounded tool output** — 200-line cap with disk persistence for large results
 
 </details>