npm - clew-code - Versions diffs - 0.4.7 → 0.4.9 - Mend

clew-code 0.4.7 → 0.4.9

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.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -2,366 +2,338 @@
 <img src="assets/clew-logo-long.png" alt="Clew Code" width="520" />
-# Clew Code
+### *The agent that works where you do.*
-**A powerful, open-source, multi-provider AI coding agent for the terminal.**
+<p align="center">
+  <a href="https://github.com/ClewCode/ClewCode/stargazers"><img src="https://img.shields.io/github/stars/ClewCode/ClewCode?style=for-the-badge&color=blue" alt="GitHub stars"></a>
+  <a href="https://github.com/ClewCode/ClewCode/releases"><img src="https://img.shields.io/github/v/release/ClewCode/ClewCode?style=for-the-badge&color=orange" alt="Release"></a>
+  <a href="https://www.npmjs.com/package/clew-code"><img src="https://img.shields.io/npm/v/clew-code?style=for-the-badge&color=red" alt="npm"></a>
+  <a href="https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ClewCode/ClewCode/ci.yml?branch=main&style=for-the-badge" alt="CI"></a>
+  <a href="LICENSE.md"><img src="https://img.shields.io/badge/License-GPL--3.0-blue.svg?style=for-the-badge" alt="License"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/built%20with-Bun-ff69b4.svg?style=for-the-badge" alt="Bun"></a>
+</p>
-A local-first coding CLI that runs on your own hardware with your own API keys — no vendor lock-in.
+<p align="center">
+  <a href="https://clew-code.org">Website</a> · <a href="https://clew-docs.pages.dev">Docs</a> · <a href="https://github.com/ClewCode/ClewCode/wiki">Wiki</a> · <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
+</p>
-[![GitHub stars](https://img.shields.io/github/stars/ClewCode/ClewCode?style=flat-square&color=blue)](https://github.com/ClewCode/ClewCode/stargazers)
-[![Release](https://img.shields.io/github/v/release/ClewCode/ClewCode?style=flat-square&color=orange)](https://github.com/ClewCode/ClewCode/releases)
-[![npm](https://img.shields.io/npm/v/clew-code?style=flat-square&color=red)](https://www.npmjs.com/package/clew-code)
-[![CI](https://img.shields.io/github/actions/workflow/status/ClewCode/ClewCode/ci.yml?branch=main&style=flat-square)](https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg?style=flat-square)](#license)
-[![Built with Bun](https://img.shields.io/badge/built%20with-Bun-ff69b4.svg?style=flat-square)](https://bun.sh)
+</div>
-[GitHub](https://github.com/ClewCode/ClewCode) · [Website](https://clew-code.org) · [Documentation](https://clew-docs.pages.dev)
+---
-</div>
+<p align="center">
+  <img src="assets/screenshots/clew-code-repl.png" alt="Clew Code REPL" width="680" />
+</p>
 ---
-**Clew Code is a local-first, multi-provider AI coding CLI.** It is built to run on your own machine using your own API keys, with support for 29 LLM providers. Featuring a built-in SQLite memory system, a peer-to-peer LAN swarm capability, Model Context Protocol (MCP) tool integration, and multiple execution layers, it allows you to run agentic workflows locally or scale them across your local network.
+Clew Code is a terminal-native AI coding agent that lives in your repo, works with your API keys, and **doesn't phone home**. It reads your code, writes files, runs commands, and talks to any LLM you bring — all on your machine, no telemetry, no vendor lock-in.
-<table>
-<tr><td><b>A real terminal interface</b></td><td>Ink-based terminal REPL with autocompletion, slash commands, syntax highlighting, and inline tool stream.</td></tr>
-<tr><td><b>Durable memory loop</b></td><td>SQLite-backed memory store that builds a factual profile of your project, manages context compaction, and injects relevant context into prompt cycles.</td></tr>
-<tr><td><b>Peer-to-peer swarm</b></td><td>Zero-config multicast LAN discovery. Synchronize memory, assign tasks, and broadcast shell execution to multiple peer nodes.</td></tr>
-<tr><td><b>Extensible tools & MCP</b></td><td>Integrates with external tools over Model Context Protocol (stdio, SSE, DirectConnect) and supports custom markdown-based skills (SKILL.md).</td></tr>
-<tr><td><b>Multiple execution layers</b></td><td>Run tasks using standard Agents, isolated Subagents, teammate swarms, or delegate to external CLIs via Process Delegates.</td></tr>
-<tr><td><b>Comprehensive guardrails</b></td><td>Secondary LLM guardian validation, manual approve/deny override, and multi-mode permissions (ask, auto, plan, etc.).</td></tr>
-</table>
+If you want a coding assistant that feels local, fast, and doesn't ship your context to a third-party server, this is it.
 ---
 ## Table of Contents
-- [Overview](#overview)
-- [Architecture](#architecture)
-- [Execution Layers and Model Routing](#execution-layers-and-model-routing)
-- [Advanced Architectural Subsystems](#advanced-architectural-subsystems)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Supported Providers](#supported-providers)
-- [CLI Options](#cli-options)
-- [Commands Reference](#commands-reference)
-- [Tools Reference](#tools-reference)
+- [Prerequisites](#prerequisites)
+- [Quick Install](#quick-install)
+- [Getting Started](#getting-started)
+- [Features](#features)
+- [Use Cases](#use-cases)
+- [CLI Quick Reference](#cli-quick-reference)
 - [Configuration](#configuration)
-- [Project Structure](#project-structure)
-- [Development Guide](#development-guide)
+- [Security](#security)
+- [Documentation](#documentation)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Star History](#star-history)
 - [License](#license)
 ---
-## Overview
-Clew Code is an autonomous AI coding agent designed to live in your terminal. It is provider-agnostic, allowing you to bring your own API keys from OpenAI, Google, DeepSeek, Groq, OpenRouter, a local Ollama instance, or any other compatible provider, and switch between them dynamically mid-session.
+## Prerequisites
-Key design philosophies:
-*   **Privacy & Local Control:** Your source code, active memory, and configurations remain 100% local on your machine.
-*   **Context Optimization:** Built-in SQLite memory ranks context by importance and access frequency, dynamically injecting relevant history into prompts.
-*   **Decentralized Scaling:** Clew instances discover each other on the local network (LAN), synchronizing memory and distributing tasks automatically.
+- **Node.js** 18+ or **Bun** 1.x (recommended for development)
+- An **API key** from at least one supported provider (see [Providers docs](https://clew-docs.pages.dev/providers))
+- *Optional:* Git, Playwright (for browser automation), microphone (for voice input)
 ---
-## Architecture
+## Quick Install
-Clew Code is divided into a clean, modular structure. Below is a high-level overview of how the CLI REPL, the Query Engine, the memory systems, and the provider adapters coordinate:
+### macOS / Linux
-```mermaid
-graph TD
-    User([User]) <--> REPL[REPL Interface\nInk & React 19]
-    REPL <--> QE[Query Engine\nTool Loop & Router]
-    QE <--> SQLite[(SQLite\nPersistent Memory)]
-    QE <--> Tools[Built-in Tools\nFile, Bash, Web, MCP]
-    QE <--> Peers[Peer Server\nLAN Swarm Sync]
-    QE <--> Provider[Provider Manager\n29 Model Adapters]
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.sh | bash
 ```
----
-## Execution Layers and Model Routing
-Clew Code separates execution agents (how the work is scheduled and structured) from backend model providers (the engines driving inference).
-### Execution Layers
-Work is distributed across four distinct layers to balance isolation, capability, and performance:
+### Windows (PowerShell)
-*   **Agent (Root Agent):** The main interactive session. It coordinates the overall workspace, maintains the system prompt, handles session-scoped permissions, and holds the active SQLite memory context. Custom agents can be configured dynamically or defined locally under `.clew/agents/*.md`.
-*   **Subagent (Child Agent):** Short-lived, task-focused processes spawned in the background via the `AgentTool`. Subagents run concurrently in their own isolated memory contexts (often with read-only tools) to perform targeted tasks such as triaging failed unit tests, auditing changed files, or researching a subdirectory.
-*   **Peer (LAN Peer Swarm):** Decentralized peer-to-peer nodes discovered automatically across the local network via UDP multicast. Peers communicate using correlation-ID brokered messages, allowing you to delegate tasks, synchronize memory databases, and broadcast shell execution to other local machines.
-*   **Process Delegate (Codex / Shell Delegation):** A local subprocess wrapper that delegates tasks to external CLI tools or models using `exec`/`pty`. For example, in personal command-center mode, the main agent delegates editor file changes to a Codex worker, monitors execution, and evaluates the results before merging.
-### Model Routing and Providers
+```powershell
+irm https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.ps1 | iex
+```
-Provider adapters map query payloads to their corresponding external APIs. The main intelligence engines include:
+### npm (cross-platform)
-*   **Claude:** Native support for Anthropic models. In personal configurations, these models act as the master planner, supervisor, and guardian, coordinating workflows and reviewing changes made by workers.
-*   **Codex:** Targeted code-generation models that run in the background (via Process Delegates) to perform precise edits, script generation, and code rewrites.
-*   **OpenCode / OpenCode-Go:** Specialized open-source model configurations and endpoints optimized for code comprehension and fast inference.
+```bash
+npm install -g clew-code
+```
 ---
-## Advanced Architectural Subsystems
+## Getting Started
-Clew Code uses several advanced subsystems to enable autonomous, safe, and context-optimized agent operations:
+```bash
+cd your-project
+clew                      # Launch the REPL
+clew -p "fix the tests"   # One-shot mode
+clew --resume last         # Pick up where you left off
+```
-*   **Durable SQLite-backed Memory:** Memory is stored in a local SQLite database with tables for `memories` (tracking importance, confidence, access counts, and type rankings) and `memory_timeline` (event tracking). Context is injected dynamically into system prompts using an `importance * recency * confidence` score. Durable facts are automatically extracted during context compaction and synced across peers. Global project guidance is maintained under `.clew/memory/` in `MEMORY.md` (project overview), `DECISIONS.md` (architectural decisions), and `TASTE.md` (style/formatting preferences).
-*   **Context Compaction and Checkpoints:** When the prompt token window fills up, Clew Code runs a multi-pass context compaction loop that recursively compresses history into factual summaries. To prevent loss of active work during compaction, the supervisor captures progress snapshots as checkpoints at 20%, 45%, and 70% milestones, along with a `notes.md` scratchpad for recovery.
-*   **Autonomous Task Queue and Daemon Mode:** Features a persistent task queue that operates with lease-based concurrency limits (allowing a maximum of 3 concurrent active tasks), exponential backoff retries, and a dead-letter queue (DLQ). The CLI can run in a background Daemon Mode to consume the task queue, run scheduled natural-language cron jobs, and perform memory distillation while the terminal is closed.
-*   **Model Context Protocol (MCP):** A unified client interface supporting stdio, Server-Sent Events (SSE), and direct in-process WebSocket connection adapters. It dynamically fetches tool declarations and resources, extending the agent's capabilities with external server tools.
-*   **Permissions and Guardian Guardrails:** Configurable permission systems restrict tool execution using policies like `ask` (confirm each edit/run), `auto` (bypass prompts), and `guardian`. Under Guardian Mode, a secondary LLM audits execution safety, blocking dangerous terminal shell operations or sensitive edits unless overridden via `/approve`.
-*   **Goal Verification:** Objectives defined via `/goal` are tracked using heuristic pre-checks and verified independently by a separate LLM verification loop. The agent will not exit until the verifier confirms that all objectives in the plan are completed.
+First launch walks you through provider setup. After that, use `/model` to switch providers mid-session.
 ---
-## Installation
+## Features
-### Prerequisites
-*   [Bun](https://bun.sh) v1.3 or higher
-*   Git installed on your system
-### Via npm
-```bash
-npm install -g clew-code
-```
+<table>
+  <tr>
+    <td><strong>29+ Providers</strong></td>
+    <td>OpenAI, Anthropic, DeepSeek, Groq, Google, Ollama (local), and 22+ more. Switch mid-session with <code>/model</code>. No lock-in.</td>
+  </tr>
+  <tr>
+    <td><strong>Persistent Memory</strong></td>
+    <td>SQLite-backed, MiMo-inspired store with importance ranking, confidence scoring, and cross-session persistence. Auto-consolidation via Dream + Distill.</td>
+  </tr>
+  <tr>
+    <td><strong>76+ Tools</strong></td>
+    <td>Read, Write, Edit, Grep, Bash, Browser, MCP, LSP, git, web search, task management, peer coordination, media generation, voice input.</td>
+  </tr>
+  <tr>
+    <td><strong>LAN Peer Swarm</strong></td>
+    <td>Zero-config peer discovery over UDP multicast. Sync memory across machines, delegate tasks, broadcast shell commands with worktree isolation and dependency ordering.</td>
+  </tr>
+  <tr>
+    <td><strong>MCP + Plugins + Skills</strong></td>
+    <td>Model Context Protocol over stdio/SSE/WebSocket. Extend with plugins, <code>SKILL.md</code> workflows, or lifecycle hooks.</td>
+  </tr>
+  <tr>
+    <td><strong>Enterprise Audit Logging</strong></td>
+    <td>SIEM-compatible NDJSON audit trail with rotation, filtering, and level-based capture. Records tool calls, file access, and command execution.</td>
+  </tr>
+  <tr>
+    <td><strong>Project Rules</strong></td>
+    <td>Auto-observed behavioral rules scoped to your repo via <code>/rule</code>. Configured in <code>.clew/rules.json</code> — Clew reads and follows them without being reminded.</td>
+  </tr>
+  <tr>
+    <td><strong>Ultracode Reasoning</strong></td>
+    <td>Max-effort reasoning mode (<code>/ultracode</code> or <code>--effort max</code>) for complex debugging, architecture design, and multi-step refactoring.</td>
+  </tr>
+  <tr>
+    <td><strong>Rewind / Undo</strong></td>
+    <td><code>/rewind</code> restores code and/or conversation to any previous checkpoint. Integrated with structured 20%/45%/70% progress snapshots.</td>
+  </tr>
+  <tr>
+    <td><strong>Cross-Repo Workspace</strong></td>
+    <td><code>/workspace link ../other-repo</code> — edit across linked projects with full context loaded from both. Bidirectional and persistent.</td>
+  </tr>
+  <tr>
+    <td><strong>Background Daemon</strong></td>
+    <td>Task queue with lease-based concurrency, cron scheduling, dead-letter retries, memory consolidation, and cross-session task persistence.</td>
+  </tr>
+  <tr>
+    <td><strong>Multi-Agent Architecture</strong></td>
+    <td>Agents, Subagents, LAN Peers, Process Peers. Personal profile turns Clew into a command center that delegates to Codex workers.</td>
+  </tr>
+</table>
-### From Source
-```bash
-# Clone the repository
-git clone https://github.com/ClewCode/ClewCode.git
-cd ClewCode
+---
-# Install dependencies and build
-bun install
-bun run build
+## Use Cases
-# Start the CLI
-bun run start
-```
+| Scenario | How Clew Code Helps |
+|---|---|
+| **Fix failing tests** | `clew -p "Fix the failing tests and explain what was wrong"` — reads test output, diagnoses root cause, applies fixes. |
+| **Refactor a module** | Point it at a file, describe the target structure. Uses multi-file edit tools, git status awareness, and checkpoint rollback on mistakes. |
+| **Research a codebase** | `/research "How does auth work?"` — searches code, docs, and web, then compiles a dossier with source references. |
+| **Background automation** | Run `/bg` to delegate long-running tasks (migration, lint fixes) to a background agent while you keep working in the REPL. |
+| **Cross-repo changes** | `/workspace link ../other-repo` — edit across linked projects with full context from both. |
 ---
-## Quick Start
+## CLI Quick Reference
-### 1. Launch the REPL
-Navigate to any repository and run `clew`. It will guide you through setting up your first model provider:
-```bash
-cd my-cool-project
-clew
 ```
-### 2. Run One-Shot Commands
-You can ask questions or execute tasks directly without entering the interactive shell:
-```bash
-clew -p "Check if all unit tests are passing and fix them if they fail"
+-p, --prompt <text>       One-shot prompt, then exit
+-c, --continue            Continue last conversation
+-r, --resume [id]         Resume a session (opens picker if no id)
+--model <model>           Override model (sonnet, opus, gemini-2.5-flash, etc.)
+--effort <level>          Reasoning effort (low|medium|high|max)
+--agent <agent>           Custom agent profile
+--permission-mode <mode>  default|ask|plan|auto
+--peer-share              Start as a LAN worker peer
+--computer                Enable OS-level computer use (Windows only)
+--debug                   Developer debug output
 ```
-### 3. Resume Previous Sessions
-Resume exactly where you left off in your last coding session:
-```bash
-clew --resume last
-```
+Notable slash commands: `/model`, `/effort`, `/ultracode`, `/memory`, `/rule`, `/task`, `/goal`, `/compact`, `/rewind`, `/workspace`, `/peer`, `/mcp`, `/agent`, `/plan`, `/voice`, `/research`, `/workflow`, `/skills`, `/code-review`, `/guardian`, `/bg`, `/daemon`, `/buddy`, `/doctor`, `/stats`, `/cost`, `/session`, `/diff`, `/fork`, `/theme`, and [many more](https://clew-docs.pages.dev/cli).
 ---
-## Supported Providers
-Clew Code interfaces with the following model provider registries natively:
-*   **openai** - OpenAI models via native SDK
-*   **anthropic** - Anthropic Claude models via native SDK
-*   **google** - Google Gemini models via native SDK
-*   **google-assist** - Google Cloud AI and Code Assist integrations
-*   **openrouter** - OpenRouter unified endpoint router
-*   **deepseek** - DeepSeek API models (e.g. DeepSeek-V3, DeepSeek-R1)
-*   **groq** - Groq Cloud API for ultra-fast Llama/Mixtral inference
-*   **xai** - xAI Grok models
-*   **mistral** - Mistral AI platform
-*   **kilocode** / **opencode** / **opencode-go** - Specialized coding endpoints
-*   **ollama** - Local Ollama models running on localhost
-*   **together** / **fireworks** / **deepinfra** - Serverless model routers
-*   **nvidia** - NVIDIA NIM API
-*   **cohere** - Cohere Command models
-*   **perplexity** - Perplexity Sonar search models
-*   **cerebras** / **siliconflow** / **moonshot** / **zhipu** - Additional API integrations
-*   **huggingface** / **poe** / **digitalocean** / **cline** - Workspace / community adapters
-*   **clew-gateway** - Standard gateway auth authentication endpoint
-*   **custom** - Any custom OpenAI-compatible endpoint
+## Configuration
----
+### Environment Variables
-## CLI Options
-Pass these arguments to the `clew` binary to customize your session:
-| Flag / Option | Description |
-| :--- | :--- |
-| `-p, --prompt <text>` | Execute a one-shot prompt in the repository and exit immediately. |
-| `-c, --continue` | Continue the most recent conversation in the current directory. |
-| `-r, --resume [id]` | Resume a conversation by session ID, or open the interactive picker. |
-| `--fork-session` | When resuming a session, clone it under a new ID instead of overwriting history. |
-| `--from-pr [id]` | Resume a session linked to a specific GitHub PR number or URL. |
-| `--model <model>` | Specify model override (e.g. `sonnet`, `opus`, `gemini-2.5-flash`). |
-| `--effort <level>` | Set reasoning effort level (`low`, `medium`, `high`, or `max`). |
-| `--agent <agent>` | Specify custom agent profile for the session. |
-| `--permission-mode <mode>` | Specify default permission mode (`default`, `ask`, `plan`, `auto`, etc.). |
-| `--add-dir <dirs...>` | Grant tool access to additional directories outside the workspace. |
-| `--ide` | Automatically connect to the local IDE on startup if available. |
-| `--session-id <uuid>` | Force a specific session ID for the active workspace. |
-| `-n, --name <name>` | Set display name for this session (shown in /resume and terminal title). |
-| `--peer-name <name>` | Set display name for local LAN peer discovery. |
-| `--peer-share` | Automatically launch this instance as a sharing worker peer on startup. |
-| `--computer` | Enable OS computer-use tool (Windows only). |
-| `-d, --debug` | Enable developer debugging output. |
-| `--verbose` | Override verbose logging setting from config. |
+| Variable | Required | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | No | Anthropic Claude models |
+| `OPENAI_API_KEY` | No | OpenAI GPT models |
+| `DEEPSEEK_API_KEY` | No | DeepSeek models |
+| `GOOGLE_API_KEY` | No | Google Gemini models |
+| `GROQ_API_KEY` | No | Groq-hosted models |
+| `TAVILY_API_KEY` | No | Enhanced web search provider |
+| `CLEW_DISABLE_TELEMETRY` | No | Disable anonymous usage stats (`1`) |
----
+All provider keys can also be set via the `/model` provider setup flow or in `.clew/settings.json` under `env`.
-## Commands Reference
-Type these slash commands directly inside the interactive REPL:
-### Core Commands
-*   `/model <name>` - Switch the provider or LLM model mid-session.
-*   `/status` - Check active provider, remaining context, and session metrics.
-*   `/doctor` - Run environment diagnostics and connectivity checks.
-*   `/context` - Inspect active context tokens and compaction boundaries.
-*   `/plan` - Enter/exit plan mode to map out large-scale refactors.
-*   `/rewind` - Undo the last user prompt and assistant response.
-*   `/effort` - Adjust reasoning effort parameter.
-*   `/stats` - View session statistics and token usage.
-*   `/theme` - Switch between dark, light, and custom terminal UI themes.
-*   `/vim` - Toggle Vim keybindings in the REPL editor.
-### Memory & Learning
-*   `/memory init` - Initialize a clean SQLite memory database for the project.
-*   `/memory scan` - Scan the active codebase to build code hierarchy memory.
-*   `/memory dashboard` - View memory statistics, confidence scores, and facts.
-*   `/rule` - Show project-specific behavioral rules auto-observed by the model. `/rule off` to disable, `/rule on` to re-enable.
-*   `/skills` - List and manage active custom skills defined in `.clew/skills/`.
-### Swarm & LAN Peers
-*   `/peer discover` - Search the LAN for active Clew nodes.
-*   `/peer swarm <cmd>` - Broadcast a shell command to all discovered peers.
-*   `/peer dashboard` - Open the visual coordination panel for peer status.
+### Project Rules
----
+Create `.clew/rules.json` in your repo to define auto-observed behavioral rules — Clew reads them at session start and follows them without being reminded. Manage them interactively with `/rule`. Disable temporarily with `/rule off`.
-## Tools Reference
+```json
+{
+  "rules": [
+    "Always use the project's existing test framework for new tests",
+    "Prefer named exports over default exports"
+  ]
+}
+```
-The agent has access to the following built-in tools based on active permission modes:
+### Enterprise Audit Logging
-### File and Terminal I/O
-*   `FileReadTool` / `FileWriteTool` / `FileEditTool` - Read, write, and modify files.
-*   `GlobTool` / `GrepTool` - Search files and directory structures.
-*   `BashTool` - Execute command-line commands in the local shell.
-*   `PowerShellTool` - Execute PowerShell scripts natively (Windows only).
+Audit logging is opt-in and writes newline-delimited JSON events for SIEM ingestion. When enabled, Clew records tool calls, tool results/failures, file read/write access, and Bash/PowerShell command execution/results.
-### Web Access and Scraping
-*   `WebSearchTool` - Query web search engines.
-*   `WebFetchTool` - Retrieve raw markdown/HTML from public URLs.
-*   `BrowserTool` - Automate headless Chrome using Playwright.
+| Variable | Required | Description |
+|---|---|---|
+| `CLEW_AUDIT_LOG` | No | Enable audit logging when set to `1` |
+| `CLEW_AUDIT_LOG_PATH` | No | Audit log directory, relative to the project root by default (`.clew/audit`) |
+| `CLEW_AUDIT_LOG_MAX_BYTES` | No | Rotate `audit.ndjson` after this size in bytes (default: 100 MB) |
+| `CLEW_AUDIT_LOG_MAX_FILES` | No | Number of audit log files to retain, including the active file (default: 10) |
+| `CLEW_AUDIT_LOG_INCLUDE` | No | Comma-separated event allowlist, such as `tool.call,tool.result` |
+| `CLEW_AUDIT_LOG_EXCLUDE` | No | Comma-separated event blocklist |
+| `CLEW_AUDIT_LOG_MIN_LEVEL` | No | Minimum level to write: `info`, `warn`, `error`, or `audit` |
+| `CLEW_AUDIT_LOG_CONSOLE` | No | Also mirror audit summaries to stderr when set to `1` |
+| `CLEW_AUDIT_USER` | No | User identifier to include in each audit event |
-### Task Management
-*   `TaskCreateTool` / `TaskGetTool` / `TaskUpdateTool` / `TaskListTool` - Track workflow task checklists.
-*   `TaskStopTool` / `TaskOutputTool` - Manage long-running tasks.
-*   `GoalTool` - Verify steps against overall task targets.
+Example:
-### Advanced Capabilities
-*   `AgentTool` - Spawns a subagent to research, write tests, or triage issues.
-*   `LSPTool` - Query local Language Server Protocol diagnostics.
-*   `ProcessDelegateTool` - Delegate prompts to external CLI models or Codex.
-*   `MemoryFeedbackTool` - Update project memories, decisions, and preferences.
-*   `ProjectRuleTool` - Save, list, or remove project-specific behavioral rules auto-observed from user patterns (stored in `.clew/rules.json`).
+```bash
+CLEW_AUDIT_LOG=1 CLEW_AUDIT_LOG_PATH=.clew/audit bun run dev
+```
 ---
-## Configuration
+## Security
-Clew Code configuration files reside in `~/.clew/` on your system:
+Clew Code runs entirely on your machine. No code or context leaves your network unless you explicitly configure a remote provider or send a web fetch.
-*   `~/.clew/settings.json` - Shared global settings (models, defaults, formatting).
-*   `~/.clew/settings.local.json` - Environment-specific private overrides.
-*   `~/.clew/memory/` - Text files containing `MEMORY.md`, `DECISIONS.md`, and `TASTE.md`.
+- Prompts for permission before read, write, or terminal execution
+- Fine-tune auto-approve rules per workspace
+- Permission scopes: default, ask, plan, auto
+- Guardian system for auto-review using secondary LLM
-Set these environment variables to authenticate with providers:
+---
-| Variable | Description |
-| :--- | :--- |
-| `OPENAI_API_KEY` | Authentication key for OpenAI models |
-| `GOOGLE_API_KEY` | Authentication key for Google Gemini / Code Assist |
-| `DEEPSEEK_API_KEY` | Authentication key for DeepSeek models |
-| `GROQ_API_KEY` | Authentication key for Groq Cloud API |
-| `OPENROUTER_API_KEY` | Authentication key for OpenRouter API |
-| `OLLAMA_HOST` | Custom address for local Ollama server (e.g., `http://localhost:11434`) |
+## Documentation
+| Guide | Description |
+|---|---|
+| [Quick Start](https://clew-docs.pages.dev/quick-start) | Launch the CLI and start coding |
+| [Installation](https://clew-docs.pages.dev/installation) | One-liner, npm, or build from source |
+| [CLI Reference](https://clew-docs.pages.dev/cli) | Full CLI options, providers, commands |
+| [Configuration](https://clew-docs.pages.dev/configuration) | Settings files, hooks, permission modes |
+| [MCP Guide](https://clew-docs.pages.dev/mcp) | Connect external tools and APIs |
+| [Plugins](https://clew-docs.pages.dev/plugins) | Lifecycle hooks and customization |
+| [Security & Permissions](https://clew-docs.pages.dev/security-permissions) | Permission scopes, guardian system |
+| [Skills System](https://clew-docs.pages.dev/skills) | Automate repeatable workflows |
+| [Memory System](https://clew-docs.pages.dev/memory-system) | SQLite-backed long-term memory |
+| [Peer-to-Peer LAN](https://clew-docs.pages.dev/peer-to-peer) | Discover, delegate, swarm commands |
+| [Architecture](https://clew-docs.pages.dev/concepts-agents-subagents-peers) | Agents, Subagents, Peers |
+| [Troubleshooting](https://clew-docs.pages.dev/troubleshooting) | Common issues and fixes |
+Also available on the [GitHub Wiki](https://github.com/ClewCode/ClewCode/wiki).
 ---
-## Project Structure
-```text
-src/
-├── main.tsx              # CLI entry point & flag parser
-├── replLauncher.tsx      # Boots the Ink/React 19 REPL
-├── QueryEngine.ts        # Streaming message/tool loop
-├── query.ts              # Non-streaming variant
-├── commands/             # Slash commands (prompt, local, local-jsx types)
-├── tools/                # 70+ tools (File I/O, Bash, Browser, Peer, MCP, etc.)
-├── peer/                 # LAN P2P: UDP multicast discovery, HTTP heartbeat
-├── memory/               # SQLite-backed memory with importance/recency ranking
-├── services/             # 36+ services (AI, MCP, autonomous, compact, etc.)
-├── skills/               # SKILL.md loader (Claude Code compatible)
-├── plugins/              # Plugin loader, registry, marketplace
-├── agentRuntime/         # Background agent orchestration
-└── remote/               # WebSocket server, auth tokens, NAT relay (Bridge v2)
-```
+## Architecture
-Full architecture reference in **[AGENTS.md](AGENTS.md)**.
+```
+┌─ REPL ─────────────────────────────┐
+│  Ink + React 19          ┌───────┐ │
+│  Slash commands / skills │ Tools │ │
+│  Streaming / history     └───┬───┘ │
+└────────┬─────────────────────┘     │
+         ▼                           │
+┌─ QueryEngine ──────────────────────┘
+│  Tool loop · Provider routing · Streaming
+│  Context compaction · Checkpoints
+└──┬────┬────┬────┬────┐
+   ▼    ▼    ▼    ▼    ▼
+┌────┐┌────┐┌────┐┌────┐┌──────────┐
+│ MCP││LSP ││Git ││Web ││ Provider │
+│    ││    ││    ││    ││ Manager  │
+└────┘└────┘└────┘└────┘└──────────┘
+   │         LAN            │
+   ▼         ▼              ▼
+┌──────┐┌──────────┐┌──────────────┐
+│ SQLite││ Peer     ││ AgentRuntime │
+│Memory ││ Server   ││ Task Queue   │
+└──────┘└──────────┘└──────────────┘
+```
 ---
-## Development Guide
-Run development commands from the repository root using **Bun**:
+## Development
 ```bash
-bun run dev              # Live-reload REPL (Voice, Transcript, Chicago flags on)
-bun run dev:channels     # Launch dev server with development channels
-bun test                 # Run the test suite via Vitest
-bun test --bail          # Run tests and stop on the first failure
-bun run lint             # Run Biome linter with auto-fix
-bun run format           # Run Biome formatter with auto-fix
-bun x tsc --noEmit       # Compile-free TypeScript validation
+bun run dev               # Live-reload REPL
+bun run build             # Production build to dist/
+bun test                  # Vitest suite
+bun run check:ci          # Biome lint + format check
+bun x tsc --noEmit        # TypeScript check
 ```
-### Pre-commit check
+### Full Pre-Commit
 ```bash
 bun run check:ci && bun x tsc --noEmit && bun test --bail
 ```
-### Knowledge graph
+### Shadow `.js` Files
-This project has a pre-built knowledge graph for codebase exploration:
+`src/` has ~410 `.js` files alongside `.ts` twins (leftover from JS → TS migration). Bun resolves `.js` import specifiers to the real `.js` file on disk — it does **not** prefer the `.ts` source. If you're making a runtime fix, check for a `.js` sibling and edit **both** files.
-```bash
-graphify query "<question>"   # Ask questions about the codebase
-graphify path "<A>" "<B>"     # Trace relationships between symbols
-graphify explain "<concept>"  # Focused explanation of a concept
-graphify update .             # Refresh after code changes (AST-only, no API cost)
-```
+---
-### Important: `.js` shadows `.ts`
+## Contributing
-`src/` has ~188 committed `.js` files next to `.ts`/`.tsx` twins (JS-to-TS migration in progress). Bun resolves `.js` import specifiers to the real `.js` file — if you edit only the `.ts` file, your change won't run at runtime. Check for a `.js` sibling and edit both.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-Full developer reference in **[AGENTS.md](AGENTS.md)**.
+- Report bugs via [GitHub Issues](https://github.com/ClewCode/ClewCode/issues)
+- Discuss ideas in [GitHub Discussions](https://github.com/ClewCode/ClewCode/discussions)
+- Read [AGENTS.md](AGENTS.md) for architecture and code conventions
+---
+## Star History
+[![Star History Chart](https://api.star-history.com/svg?repos=ClewCode/ClewCode&type=Date)](https://star-history.com/#ClewCode/ClewCode&Date)
 ---
 ## License
-Clew Code is licensed under the **GPL-3.0 License**. See [LICENSE.md](LICENSE.md) for details.
-Full release history is available in [CHANGELOG.md](CHANGELOG.md).
+GPL-3.0. See [LICENSE.md](LICENSE.md).
+Release history in [CHANGELOG.md](CHANGELOG.md).