clew-code 0.4.3 → 0.4.6
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/LICENSE.md +1 -1
- package/README.md +279 -206
- package/dist/main.js +2221 -2075
- package/docs/architecture/provider-system.md +107 -0
- package/package.json +162 -161
package/LICENSE.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Nature of This Repository
|
|
4
4
|
|
|
5
|
-
This repository contains an unofficial,
|
|
5
|
+
This repository contains an unofficial, independent implementation of an AI coding CLI, named Clew Code (clew-code). The code has been developed and extended for research, local development, and self-hosted use.
|
|
6
6
|
|
|
7
7
|
This repository is not an official Anthropic product. Anthropic has not authorized, endorsed, sponsored, or approved this project.
|
|
8
8
|
|
package/README.md
CHANGED
|
@@ -1,292 +1,365 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="assets/clew-logo-long.png" alt="Clew Code" width="
|
|
3
|
+
<img src="assets/clew-logo-long.png" alt="Clew Code" width="520" />
|
|
4
4
|
|
|
5
5
|
# Clew Code
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**A powerful, open-source, multi-provider AI coding agent for the terminal.**
|
|
8
8
|
|
|
9
|
-
A local-first coding CLI that
|
|
9
|
+
A local-first coding CLI that runs on your own hardware with your own API keys — no vendor lock-in.
|
|
10
10
|
|
|
11
|
-
[](https://github.com/ClewCode/ClewCode/releases)
|
|
13
|
-
[](https://www.npmjs.com/package/clew-code)
|
|
14
|
-
[](https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml)
|
|
15
|
-
[](#license)
|
|
16
|
-
[](https://bun.sh)
|
|
11
|
+
[](https://github.com/ClewCode/ClewCode/stargazers)
|
|
12
|
+
[](https://github.com/ClewCode/ClewCode/releases)
|
|
13
|
+
[](https://www.npmjs.com/package/clew-code)
|
|
14
|
+
[](https://github.com/ClewCode/ClewCode/actions/workflows/ci.yml)
|
|
15
|
+
[](#license)
|
|
16
|
+
[](https://bun.sh)
|
|
18
17
|
|
|
19
|
-
[GitHub](https://github.com/ClewCode/ClewCode) · [Website](https://clew-code.org) · [
|
|
18
|
+
[GitHub](https://github.com/ClewCode/ClewCode) · [Website](https://clew-code.org) · [Documentation](https://clew-docs.pages.dev)
|
|
20
19
|
|
|
21
20
|
</div>
|
|
22
21
|
|
|
23
22
|
---
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
**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.
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
<table>
|
|
27
|
+
<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>
|
|
28
|
+
<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>
|
|
29
|
+
<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>
|
|
30
|
+
<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>
|
|
31
|
+
<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>
|
|
32
|
+
<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>
|
|
33
|
+
</table>
|
|
28
34
|
|
|
29
|
-
|
|
35
|
+
---
|
|
30
36
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-
|
|
37
|
+
## Table of Contents
|
|
38
|
+
|
|
39
|
+
- [Overview](#overview)
|
|
40
|
+
- [Architecture](#architecture)
|
|
41
|
+
- [Execution Layers and Model Routing](#execution-layers-and-model-routing)
|
|
42
|
+
- [Advanced Architectural Subsystems](#advanced-architectural-subsystems)
|
|
43
|
+
- [Installation](#installation)
|
|
44
|
+
- [Quick Start](#quick-start)
|
|
45
|
+
- [Supported Providers](#supported-providers)
|
|
46
|
+
- [CLI Options](#cli-options)
|
|
47
|
+
- [Commands Reference](#commands-reference)
|
|
48
|
+
- [Tools Reference](#tools-reference)
|
|
49
|
+
- [Configuration](#configuration)
|
|
50
|
+
- [Project Structure](#project-structure)
|
|
51
|
+
- [Development Guide](#development-guide)
|
|
52
|
+
- [License](#license)
|
|
34
53
|
|
|
35
54
|
---
|
|
36
55
|
|
|
37
|
-
##
|
|
56
|
+
## Overview
|
|
38
57
|
|
|
39
|
-
|
|
58
|
+
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.
|
|
40
59
|
|
|
41
|
-
|
|
60
|
+
Key design philosophies:
|
|
61
|
+
* **Privacy & Local Control:** Your source code, active memory, and configurations remain 100% local on your machine.
|
|
62
|
+
* **Context Optimization:** Built-in SQLite memory ranks context by importance and access frequency, dynamically injecting relevant history into prompts.
|
|
63
|
+
* **Decentralized Scaling:** Clew instances discover each other on the local network (LAN), synchronizing memory and distributing tasks automatically.
|
|
42
64
|
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
curl -fsSL https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.sh | bash
|
|
46
|
-
```
|
|
65
|
+
---
|
|
47
66
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
67
|
+
## Architecture
|
|
68
|
+
|
|
69
|
+
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:
|
|
70
|
+
|
|
71
|
+
```mermaid
|
|
72
|
+
graph TD
|
|
73
|
+
User([User]) <--> REPL[REPL Interface\nInk & React 19]
|
|
74
|
+
REPL <--> QE[Query Engine\nTool Loop & Router]
|
|
75
|
+
QE <--> SQLite[(SQLite\nPersistent Memory)]
|
|
76
|
+
QE <--> Tools[Built-in Tools\nFile, Bash, Web, MCP]
|
|
77
|
+
QE <--> Peers[Peer Server\nLAN Swarm Sync]
|
|
78
|
+
QE <--> Provider[Provider Manager\n29 Model Adapters]
|
|
51
79
|
```
|
|
52
80
|
|
|
53
|
-
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Execution Layers and Model Routing
|
|
84
|
+
|
|
85
|
+
Clew Code separates execution agents (how the work is scheduled and structured) from backend model providers (the engines driving inference).
|
|
86
|
+
|
|
87
|
+
### Execution Layers
|
|
88
|
+
|
|
89
|
+
Work is distributed across four distinct layers to balance isolation, capability, and performance:
|
|
90
|
+
|
|
91
|
+
* **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`.
|
|
92
|
+
* **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.
|
|
93
|
+
* **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.
|
|
94
|
+
* **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.
|
|
95
|
+
|
|
96
|
+
### Model Routing and Providers
|
|
97
|
+
|
|
98
|
+
Provider adapters map query payloads to their corresponding external APIs. The main intelligence engines include:
|
|
54
99
|
|
|
100
|
+
* **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.
|
|
101
|
+
* **Codex:** Targeted code-generation models that run in the background (via Process Delegates) to perform precise edits, script generation, and code rewrites.
|
|
102
|
+
* **OpenCode / OpenCode-Go:** Specialized open-source model configurations and endpoints optimized for code comprehension and fast inference.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Advanced Architectural Subsystems
|
|
107
|
+
|
|
108
|
+
Clew Code uses several advanced subsystems to enable autonomous, safe, and context-optimized agent operations:
|
|
109
|
+
|
|
110
|
+
* **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).
|
|
111
|
+
* **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.
|
|
112
|
+
* **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.
|
|
113
|
+
* **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.
|
|
114
|
+
* **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`.
|
|
115
|
+
* **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.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Installation
|
|
120
|
+
|
|
121
|
+
### Prerequisites
|
|
122
|
+
* [Bun](https://bun.sh) v1.3 or higher
|
|
123
|
+
* Git installed on your system
|
|
124
|
+
|
|
125
|
+
### Via npm
|
|
55
126
|
```bash
|
|
56
127
|
npm install -g clew-code
|
|
57
128
|
```
|
|
58
129
|
|
|
59
|
-
### From
|
|
60
|
-
|
|
130
|
+
### From Source
|
|
61
131
|
```bash
|
|
132
|
+
# Clone the repository
|
|
62
133
|
git clone https://github.com/ClewCode/ClewCode.git
|
|
63
134
|
cd ClewCode
|
|
64
|
-
bun install && bun run build && bun run start
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
**Requirements:** [Bun](https://bun.sh) 1.3+, Git, and at least one provider API key. Node.js 18+ is supported as a fallback runtime.
|
|
68
135
|
|
|
69
|
-
|
|
70
|
-
|
|
136
|
+
# Install dependencies and build
|
|
137
|
+
bun install
|
|
138
|
+
bun run build
|
|
71
139
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
</details>
|
|
140
|
+
# Start the CLI
|
|
141
|
+
bun run start
|
|
142
|
+
```
|
|
76
143
|
|
|
77
144
|
---
|
|
78
145
|
|
|
79
|
-
## Quick
|
|
146
|
+
## Quick Start
|
|
80
147
|
|
|
148
|
+
### 1. Launch the REPL
|
|
149
|
+
Navigate to any repository and run `clew`. It will guide you through setting up your first model provider:
|
|
81
150
|
```bash
|
|
82
|
-
|
|
83
|
-
cd my-project
|
|
151
|
+
cd my-cool-project
|
|
84
152
|
clew
|
|
85
153
|
```
|
|
86
154
|
|
|
87
|
-
|
|
88
|
-
|
|
155
|
+
### 2. Run One-Shot Commands
|
|
156
|
+
You can ask questions or execute tasks directly without entering the interactive shell:
|
|
89
157
|
```bash
|
|
90
|
-
|
|
91
|
-
export GOOGLE_API_KEY=...
|
|
92
|
-
export DEEPSEEK_API_KEY=...
|
|
93
|
-
export GROQ_API_KEY=...
|
|
94
|
-
export OPENROUTER_API_KEY=...
|
|
95
|
-
export OLLAMA_HOST=http://localhost:11434
|
|
158
|
+
clew -p "Check if all unit tests are passing and fix them if they fail"
|
|
96
159
|
```
|
|
97
160
|
|
|
161
|
+
### 3. Resume Previous Sessions
|
|
162
|
+
Resume exactly where you left off in your last coding session:
|
|
98
163
|
```bash
|
|
99
|
-
# One-shot mode (pipe-friendly)
|
|
100
|
-
clew -p "summarize CHANGELOG.md"
|
|
101
|
-
|
|
102
|
-
# Resume your last session
|
|
103
164
|
clew --resume last
|
|
104
165
|
```
|
|
105
166
|
|
|
106
|
-
|
|
167
|
+
---
|
|
107
168
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
169
|
+
## Supported Providers
|
|
170
|
+
|
|
171
|
+
Clew Code interfaces with the following model provider registries natively:
|
|
172
|
+
|
|
173
|
+
* **openai** - OpenAI models via native SDK
|
|
174
|
+
* **anthropic** - Anthropic Claude models via native SDK
|
|
175
|
+
* **google** - Google Gemini models via native SDK
|
|
176
|
+
* **google-assist** - Google Cloud AI and Code Assist integrations
|
|
177
|
+
* **openrouter** - OpenRouter unified endpoint router
|
|
178
|
+
* **deepseek** - DeepSeek API models (e.g. DeepSeek-V3, DeepSeek-R1)
|
|
179
|
+
* **groq** - Groq Cloud API for ultra-fast Llama/Mixtral inference
|
|
180
|
+
* **xai** - xAI Grok models
|
|
181
|
+
* **mistral** - Mistral AI platform
|
|
182
|
+
* **kilocode** / **opencode** / **opencode-go** - Specialized coding endpoints
|
|
183
|
+
* **ollama** - Local Ollama models running on localhost
|
|
184
|
+
* **together** / **fireworks** / **deepinfra** - Serverless model routers
|
|
185
|
+
* **nvidia** - NVIDIA NIM API
|
|
186
|
+
* **cohere** - Cohere Command models
|
|
187
|
+
* **perplexity** - Perplexity Sonar search models
|
|
188
|
+
* **cerebras** / **siliconflow** / **moonshot** / **zhipu** - Additional API integrations
|
|
189
|
+
* **huggingface** / **poe** / **digitalocean** / **cline** - Workspace / community adapters
|
|
190
|
+
* **clew-gateway** - Standard gateway auth authentication endpoint
|
|
191
|
+
* **custom** - Any custom OpenAI-compatible endpoint
|
|
118
192
|
|
|
119
193
|
---
|
|
120
194
|
|
|
121
|
-
##
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
## SWE-bench Verified
|
|
149
|
-
|
|
150
|
-
Clew Code ships a SWE-bench Verified evaluation harness modeled after the public
|
|
151
|
-
agent-comparison workflow used by projects like ClawCodex: a FastAPI wrapper
|
|
152
|
-
around `clew -p`, a `prepare`/`run` driver, prediction JSONL output, and optional
|
|
153
|
-
Docker harness execution.
|
|
154
|
-
|
|
155
|
-
No official Clew Code SWE-bench score is claimed in this repository yet. See
|
|
156
|
-
[`eval/README.md`](eval/README.md) to run a smoke batch, full Verified split, or
|
|
157
|
-
side-by-side comparison with another agent.
|
|
158
|
-
|
|
159
|
-
---
|
|
160
|
-
|
|
161
|
-
## Execution layers
|
|
162
|
-
|
|
163
|
-
Clew Code runs work at several layers, each for a different job:
|
|
164
|
-
|
|
165
|
-
| Layer | What it is | Use it for |
|
|
166
|
-
|-------|-----------|------------|
|
|
167
|
-
| **Agent** | An AI worker with a prompt, model, tools, and permissions. The main chat is an agent; custom ones live in `.clew/agents/*.md`. | The session itself. |
|
|
168
|
-
| **Subagent** | A short-lived child launched via the `Agent` tool (e.g. read-only `Explore`). | Independent investigation, test triage, review. |
|
|
169
|
-
| **Teammate / Swarm** | A longer-lived agent with identity, mailbox, and task coordination. | Multi-turn collaboration between named workers. |
|
|
170
|
-
| **LAN Peer** | Another Clew instance on the same machine or network, reached via `/peer`. | Distributing work across machines. |
|
|
171
|
-
| **Process Peer** | A local worker that delegates to an external CLI (e.g. Codex) via `exec`/`pty`. | Running another coding tool as a subprocess. |
|
|
172
|
-
|
|
173
|
-
Other runtime concepts: **Plan mode** (full-access planning that persists to `.clew/plans/`), **multi-pass compaction** (recursive context compression when the window fills), and **structured checkpoints** (progress snapshots at 20/45/70% with a `notes.md` scratchpad, used for layered rebuild during compaction).
|
|
195
|
+
## CLI Options
|
|
196
|
+
|
|
197
|
+
Pass these arguments to the `clew` binary to customize your session:
|
|
198
|
+
|
|
199
|
+
| Flag / Option | Description |
|
|
200
|
+
| :--- | :--- |
|
|
201
|
+
| `-p, --prompt <text>` | Execute a one-shot prompt in the repository and exit immediately. |
|
|
202
|
+
| `-c, --continue` | Continue the most recent conversation in the current directory. |
|
|
203
|
+
| `-r, --resume [id]` | Resume a conversation by session ID, or open the interactive picker. |
|
|
204
|
+
| `--fork-session` | When resuming a session, clone it under a new ID instead of overwriting history. |
|
|
205
|
+
| `--from-pr [id]` | Resume a session linked to a specific GitHub PR number or URL. |
|
|
206
|
+
| `--model <model>` | Specify model override (e.g. `sonnet`, `opus`, `gemini-2.5-flash`). |
|
|
207
|
+
| `--effort <level>` | Set reasoning effort level (`low`, `medium`, `high`, or `max`). |
|
|
208
|
+
| `--agent <agent>` | Specify custom agent profile for the session. |
|
|
209
|
+
| `--permission-mode <mode>` | Specify default permission mode (`default`, `ask`, `plan`, `auto`, etc.). |
|
|
210
|
+
| `--add-dir <dirs...>` | Grant tool access to additional directories outside the workspace. |
|
|
211
|
+
| `--ide` | Automatically connect to the local IDE on startup if available. |
|
|
212
|
+
| `--session-id <uuid>` | Force a specific session ID for the active workspace. |
|
|
213
|
+
| `-n, --name <name>` | Set display name for this session (shown in /resume and terminal title). |
|
|
214
|
+
| `--peer-name <name>` | Set display name for local LAN peer discovery. |
|
|
215
|
+
| `--peer-share` | Automatically launch this instance as a sharing worker peer on startup. |
|
|
216
|
+
| `--computer` | Enable OS computer-use tool (Windows only). |
|
|
217
|
+
| `-d, --debug` | Enable developer debugging output. |
|
|
218
|
+
| `--verbose` | Override verbose logging setting from config. |
|
|
174
219
|
|
|
175
220
|
---
|
|
176
221
|
|
|
177
|
-
## Commands
|
|
222
|
+
## Commands Reference
|
|
223
|
+
|
|
224
|
+
Type these slash commands directly inside the interactive REPL:
|
|
225
|
+
|
|
226
|
+
### Core Commands
|
|
227
|
+
* `/model <name>` - Switch the provider or LLM model mid-session.
|
|
228
|
+
* `/status` - Check active provider, remaining context, and session metrics.
|
|
229
|
+
* `/doctor` - Run environment diagnostics and connectivity checks.
|
|
230
|
+
* `/context` - Inspect active context tokens and compaction boundaries.
|
|
231
|
+
* `/plan` - Enter/exit plan mode to map out large-scale refactors.
|
|
232
|
+
* `/rewind` - Undo the last user prompt and assistant response.
|
|
233
|
+
* `/effort` - Adjust reasoning effort parameter.
|
|
234
|
+
* `/stats` - View session statistics and token usage.
|
|
235
|
+
* `/theme` - Switch between dark, light, and custom terminal UI themes.
|
|
236
|
+
* `/vim` - Toggle Vim keybindings in the REPL editor.
|
|
237
|
+
|
|
238
|
+
### Memory & Learning
|
|
239
|
+
* `/memory init` - Initialize a clean SQLite memory database for the project.
|
|
240
|
+
* `/memory scan` - Scan the active codebase to build code hierarchy memory.
|
|
241
|
+
* `/memory dashboard` - View memory statistics, confidence scores, and facts.
|
|
242
|
+
* `/skills` - List and manage active custom skills defined in `.clew/skills/`.
|
|
243
|
+
|
|
244
|
+
### Swarm & LAN Peers
|
|
245
|
+
* `/peer discover` - Search the LAN for active Clew nodes.
|
|
246
|
+
* `/peer swarm <cmd>` - Broadcast a shell command to all discovered peers.
|
|
247
|
+
* `/peer dashboard` - Open the visual coordination panel for peer status.
|
|
178
248
|
|
|
179
|
-
|
|
180
|
-
<summary><strong>100+ slash commands</strong></summary>
|
|
249
|
+
---
|
|
181
250
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
/
|
|
188
|
-
/
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
/
|
|
195
|
-
|
|
196
|
-
/code-review Review changed files for bugs
|
|
197
|
-
/simplify Cleanup-focused review
|
|
198
|
-
/guardian Auto-review mode using a secondary LLM
|
|
199
|
-
/approve Override guardian denials
|
|
200
|
-
/pr GitHub PR lifecycle
|
|
201
|
-
/plan Plan mode
|
|
202
|
-
/fork Fork conversation into a new session
|
|
203
|
-
/rewind Undo last response
|
|
204
|
-
/effort Set reasoning effort
|
|
205
|
-
/stats Session statistics and cost breakdown
|
|
206
|
-
/voice Voice input via browser Web Speech API
|
|
207
|
-
/remote WebSocket remote control
|
|
208
|
-
/bridge Bridge mode config
|
|
209
|
-
/session Session management
|
|
210
|
-
/theme Theme switcher
|
|
211
|
-
/vim Vim keybindings
|
|
212
|
-
/login Sign in via Clew Gateway
|
|
213
|
-
/logout Sign out
|
|
214
|
-
/upgrade Check for updates
|
|
215
|
-
```
|
|
251
|
+
## Tools Reference
|
|
252
|
+
|
|
253
|
+
The agent has access to the following built-in tools based on active permission modes:
|
|
254
|
+
|
|
255
|
+
### File and Terminal I/O
|
|
256
|
+
* `FileReadTool` / `FileWriteTool` / `FileEditTool` - Read, write, and modify files.
|
|
257
|
+
* `GlobTool` / `GrepTool` - Search files and directory structures.
|
|
258
|
+
* `BashTool` - Execute command-line commands in the local shell.
|
|
259
|
+
* `PowerShellTool` - Execute PowerShell scripts natively (Windows only).
|
|
260
|
+
|
|
261
|
+
### Web Access and Scraping
|
|
262
|
+
* `WebSearchTool` - Query web search engines.
|
|
263
|
+
* `WebFetchTool` - Retrieve raw markdown/HTML from public URLs.
|
|
264
|
+
* `BrowserTool` - Automate headless Chrome using Playwright.
|
|
216
265
|
|
|
217
|
-
|
|
266
|
+
### Task Management
|
|
267
|
+
* `TaskCreateTool` / `TaskGetTool` / `TaskUpdateTool` / `TaskListTool` - Track workflow task checklists.
|
|
268
|
+
* `TaskStopTool` / `TaskOutputTool` - Manage long-running tasks.
|
|
269
|
+
* `GoalTool` - Verify steps against overall task targets.
|
|
270
|
+
|
|
271
|
+
### Advanced Capabilities
|
|
272
|
+
* `AgentTool` - Spawns a subagent to research, write tests, or triage issues.
|
|
273
|
+
* `LSPTool` - Query local Language Server Protocol diagnostics.
|
|
274
|
+
* `ProcessDelegateTool` - Delegate prompts to external CLI models or Codex.
|
|
275
|
+
* `MemoryFeedbackTool` - Update project memories, decisions, and preferences.
|
|
218
276
|
|
|
219
277
|
---
|
|
220
278
|
|
|
221
|
-
##
|
|
279
|
+
## Configuration
|
|
222
280
|
|
|
223
|
-
|
|
224
|
-
<summary><strong>src/ — single-entry Bun bundle</strong></summary>
|
|
281
|
+
Clew Code configuration files reside in `~/.clew/` on your system:
|
|
225
282
|
|
|
226
|
-
|
|
283
|
+
* `~/.clew/settings.json` - Shared global settings (models, defaults, formatting).
|
|
284
|
+
* `~/.clew/settings.local.json` - Environment-specific private overrides.
|
|
285
|
+
* `~/.clew/memory/` - Text files containing `MEMORY.md`, `DECISIONS.md`, and `TASTE.md`.
|
|
286
|
+
|
|
287
|
+
Set these environment variables to authenticate with providers:
|
|
288
|
+
|
|
289
|
+
| Variable | Description |
|
|
290
|
+
| :--- | :--- |
|
|
291
|
+
| `OPENAI_API_KEY` | Authentication key for OpenAI models |
|
|
292
|
+
| `GOOGLE_API_KEY` | Authentication key for Google Gemini / Code Assist |
|
|
293
|
+
| `DEEPSEEK_API_KEY` | Authentication key for DeepSeek models |
|
|
294
|
+
| `GROQ_API_KEY` | Authentication key for Groq Cloud API |
|
|
295
|
+
| `OPENROUTER_API_KEY` | Authentication key for OpenRouter API |
|
|
296
|
+
| `OLLAMA_HOST` | Custom address for local Ollama server (e.g., `http://localhost:11434`) |
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## Project Structure
|
|
301
|
+
|
|
302
|
+
```text
|
|
227
303
|
src/
|
|
228
|
-
├── main.tsx #
|
|
229
|
-
├──
|
|
230
|
-
├──
|
|
231
|
-
├──
|
|
232
|
-
├──
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
│ └── compact/ # Context compression
|
|
242
|
-
├── peer/ # PeerServer + PeerDiscovery
|
|
243
|
-
├── memory/ # MemoryDB + scanner + feedback
|
|
244
|
-
├── bridge/ # WebSocket bridge + relay
|
|
245
|
-
├── components/ # Ink terminal UI
|
|
246
|
-
└── hooks/ # React hooks
|
|
304
|
+
├── main.tsx # CLI entry point & flag parser
|
|
305
|
+
├── replLauncher.tsx # Boots the Ink/React 19 REPL
|
|
306
|
+
├── QueryEngine.ts # Streaming message/tool loop
|
|
307
|
+
├── query.ts # Non-streaming variant
|
|
308
|
+
├── commands/ # Slash commands (prompt, local, local-jsx types)
|
|
309
|
+
├── tools/ # 70+ tools (File I/O, Bash, Browser, Peer, MCP, etc.)
|
|
310
|
+
├── peer/ # LAN P2P: UDP multicast discovery, HTTP heartbeat
|
|
311
|
+
├── memory/ # SQLite-backed memory with importance/recency ranking
|
|
312
|
+
├── services/ # 36+ services (AI, MCP, autonomous, compact, etc.)
|
|
313
|
+
├── skills/ # SKILL.md loader (Claude Code compatible)
|
|
314
|
+
├── plugins/ # Plugin loader, registry, marketplace
|
|
315
|
+
├── agentRuntime/ # Background agent orchestration
|
|
316
|
+
└── remote/ # WebSocket server, auth tokens, NAT relay (Bridge v2)
|
|
247
317
|
```
|
|
248
318
|
|
|
249
|
-
|
|
319
|
+
Full architecture reference in **[AGENTS.md](AGENTS.md)**.
|
|
250
320
|
|
|
251
321
|
---
|
|
252
322
|
|
|
253
|
-
## Development
|
|
323
|
+
## Development Guide
|
|
324
|
+
|
|
325
|
+
Run development commands from the repository root using **Bun**:
|
|
254
326
|
|
|
255
327
|
```bash
|
|
256
|
-
bun run dev
|
|
257
|
-
bun run
|
|
258
|
-
bun test
|
|
259
|
-
bun
|
|
260
|
-
bun run
|
|
328
|
+
bun run dev # Live-reload REPL (Voice, Transcript, Chicago flags on)
|
|
329
|
+
bun run dev:channels # Launch dev server with development channels
|
|
330
|
+
bun test # Run the test suite via Vitest
|
|
331
|
+
bun test --bail # Run tests and stop on the first failure
|
|
332
|
+
bun run lint # Run Biome linter with auto-fix
|
|
333
|
+
bun run format # Run Biome formatter with auto-fix
|
|
334
|
+
bun x tsc --noEmit # Compile-free TypeScript validation
|
|
261
335
|
```
|
|
262
336
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
bun
|
|
337
|
+
### Pre-commit check
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
bun run check:ci && bun x tsc --noEmit && bun test --bail
|
|
267
341
|
```
|
|
268
342
|
|
|
269
|
-
|
|
343
|
+
### Knowledge graph
|
|
270
344
|
|
|
271
|
-
|
|
345
|
+
This project has a pre-built knowledge graph for codebase exploration:
|
|
272
346
|
|
|
273
|
-
|
|
347
|
+
```bash
|
|
348
|
+
graphify query "<question>" # Ask questions about the codebase
|
|
349
|
+
graphify path "<A>" "<B>" # Trace relationships between symbols
|
|
350
|
+
graphify explain "<concept>" # Focused explanation of a concept
|
|
351
|
+
graphify update . # Refresh after code changes (AST-only, no API cost)
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### Important: `.js` shadows `.ts`
|
|
274
355
|
|
|
275
|
-
|
|
276
|
-
- Add a provider adapter in `src/services/ai/`
|
|
277
|
-
- Write tests for untested tools
|
|
278
|
-
- Improve docs and examples
|
|
279
|
-
- Build a plugin or MCP server
|
|
280
|
-
- Improve Windows support
|
|
356
|
+
`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.
|
|
281
357
|
|
|
282
|
-
|
|
283
|
-
<img src="https://contrib.rocks/image?repo=ClewCode/ClewCode" alt="Contributors" />
|
|
284
|
-
</a>
|
|
358
|
+
Full developer reference in **[AGENTS.md](AGENTS.md)**.
|
|
285
359
|
|
|
286
360
|
---
|
|
287
361
|
|
|
288
362
|
## License
|
|
289
363
|
|
|
290
|
-
See [LICENSE.md](LICENSE.md)
|
|
291
|
-
|
|
292
|
-
Full version history: [CHANGELOG.md](CHANGELOG.md).
|
|
364
|
+
Clew Code is licensed under the **GPL-3.0 License**. See [LICENSE.md](LICENSE.md) for details.
|
|
365
|
+
Full release history is available in [CHANGELOG.md](CHANGELOG.md).
|