The agent that works where you do.

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 — Claude, GPT, Gemini, DeepSeek, local Ollama models, and 25+ other providers — all on your machine, no telemetry, no vendor lock-in.

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

• Prerequisites
• Quick Install
• Getting Started
• Usage Examples
• Features
• Use Cases
• CLI Quick Reference
• Configuration
• Security
• Documentation
• Architecture
• Development
• Contributing
• Star History
• License

Prerequisites

• Node.js 18+ or Bun 1.x (recommended for development)
• An API key from at least one supported provider (see Providers docs)
• Optional: Git, Playwright (for browser automation), microphone (for voice input)

Quick Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/ClewCode/ClewCode/main/scripts/install.ps1 | iex

npm (cross-platform)

npm install -g clew-code

This installs two equivalent binaries: clew and clewcode.

Getting Started

cd your-project
clew                      # Launch the REPL
clew -p "fix the tests"   # One-shot mode
clew --resume last        # Pick up where you left off

First launch walks you through provider setup — pick a provider (Claude, OpenAI, Gemini, OpenRouter, etc.) and enter an API key. This is saved to your local config, never committed. After that, use /model to switch providers mid-session.

Usage Examples

Ask questions about a codebase

> how does authentication work in this repo?
> where is the retry logic for API calls defined?

Clew Code searches and reads files on its own — no need to paste code in.

Make a change

> refactor the UserCard component to use the new Avatar component

It reads the relevant files, edits them, and shows a diff-style summary of what changed. Prompts for permission before writing, unless you've set an auto-approve rule.

Fix and verify

> fix the bug in src/utils/parser.ts where empty arrays throw
> run the test suite and fix any failures

Combines file edits with the Bash tool (npm test / bun test), looping until tests pass or it needs your input.

Slash commands

/help              # list all commands
/model             # switch LLM provider/model for this session (d = save as default)
/code-review       # review the current diff for bugs
/debug             # structured debugging workflow
/loop 5m /deploy-checklist   # run a command on a recurring interval

Run /help inside the REPL for the full, current list — commands grow over time via skills and plugins.

Multi-file / multi-step work

> migrate all usages of the old Logger class to the new one across src/

For larger jobs, Clew Code plans the work (/plan, or automatically for complex asks), then executes step by step, checking in at natural checkpoints. /rewind restores code or conversation to any prior checkpoint if something goes wrong.

Research a codebase or topic

> /research "How does auth work in this repo?"

Searches code, docs, and the web, then compiles a dossier with source references.

Connect external tools (MCP)

> list open PRs assigned to me and summarize what's blocking each one

Wire in GitHub, Slack, a database, or any Model Context Protocol server via /mcp, and use it from the same session.

Features

Use Cases

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

CLI Quick Reference

-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

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, /delegate, /sessions, and many more.

Configuration

Environment Variables

| 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 | Web search provider (first choice) | | BRAVE_API_KEY | No | Web search fallback if Tavily fails | | SERPER_API_KEY | No | Web search fallback if Tavily and Brave fail | | JINA_API_KEY | No | Web search fallback, tried last of the keyed providers | | ANTIGRAVITY_CLIENT_ID | No | Custom Google OAuth client ID for Antigravity/google-assist | | ANTIGRAVITY_CLIENT_SECRET | No | Custom Google OAuth client secret for Antigravity/google-assist | | ANTIGRAVITY_PROJECT_ID | No | Google Cloud project ID for Antigravity/google-assist | | ANTIGRAVITY_ENDPOINT | No | Custom endpoint URL for Antigravity/google-assist | | 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.

Session Recovery Fallback

Clew Code supports resuming sessions from other rebranded or legacy variants of the CLI tool. If a session is not found in the primary .clew configuration home directory, the tool automatically scans and loads sessions from the following directories in your user home:

• .codex
• .opencode
• .claude
• .gemini
• .antigravity

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.

{
  "rules": [
    "Always use the project's existing test framework for new tests",
    "Prefer named exports over default exports"
  ]
}

Enterprise Audit Logging

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.

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

Example:

CLEW_AUDIT_LOG=1 CLEW_AUDIT_LOG_PATH=.clew/audit bun run dev

Security

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.

• 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 a secondary LLM

Documentation

| Guide | Description | |---|---| | Quick Start | Launch the CLI and start coding | | Installation | One-liner, npm, or build from source | | CLI Reference | Full CLI options, providers, commands | | Configuration | Settings files, hooks, permission modes | | MCP Guide | Connect external tools and APIs | | Plugins | Lifecycle hooks and customization | | Security & Permissions | Permission scopes, guardian system | | Skills System | Automate repeatable workflows | | Memory System | SQLite-backed long-term memory | | Peer-to-Peer LAN | Discover, delegate, swarm commands | | Architecture | Agents, Subagents, Peers | | Troubleshooting | Common issues and fixes |

Also available on the GitHub Wiki.

Architecture

┌─ REPL ──────────────────────────────────┐
│  Ink + React 19               ┌──────┐ │
│  Slash commands / skills      │Tools │ │
│  Streaming / history          │ x76  │ │
│  state/AppState.tsx           └──┬───┘ │
└────────┬─────────────────────────┘     │
         │                ▲              │
         ▼                │              │
┌─ QueryEngine ───────────┴──────────────┘
│  Streaming · tool loop · compaction
│  Checkpoints · Max Mode · /rewind
│
│  query.ts (non-streaming: subagents)
└──┬────┬────┬────┬────┬────┬────┐
   ▼    ▼    ▼    ▼    ▼    ▼    ▼
┌────┐┌────┐┌────┐┌────┐┌────┐┌──────────┐
│ MCP││LSP ││Git ││Web ││Task││ Provider │
│    ││    ││    ││    ││    ││ Manager  │
└────┘└────┘└────┘└────┘└────┘└──────────┘
   │         LAN           │       │
   ▼         ▼             ▼       ▼
┌──────┐┌─────────┐┌──────────┐┌──────────┐
│ vec  ││ Peer    ││ Agent    ││ Agent    │
│Memory││ Server  ││Runtime   ││ Subagent │
└──────┘└─────────┘└──────────┘└──────────┘
│  Autonomous task queue + cron + DA       │
└──────────────────────────────────────────┘

• Entry: src/main.tsx → src/replLauncher.tsx boots the Ink/React 19 REPL
• REPL screen: src/screens/REPL.tsx routes input to commands or the query engine
• Query paths: src/QueryEngine.ts (streaming with tool loop) + src/query.ts (non-streaming for subagents, background tasks)
• Providers: src/services/ai/ — 32 providers behind one interface, normalized errors/usage
• Tools: src/tools/<ToolName>/, 80 tool packages extending Tool, registered in src/tools.ts
• Services: src/services/ — MCP client, autonomous queue, vec memory, session search, plugins, LSP, voice, audit log, and more

Full detail, including tool inventory and service list: AGENTS.md.

Development

git clone https://github.com/ClewCode/ClewCode.git
cd ClewCode
bun install
bun run dev               # Live-reload REPL (with feature flags)
bun run dev:channels      # Dev with development channels loaded
bun run build             # Production build to dist/
bun run start             # Run the compiled build
bun test                  # Full suite (vitest-compatible runner)
bun test --bail           # Stop on first failure
bun test path/to/file.test.ts          # Single file
bun test -t "test name"                # By test name
bun run check:ci          # Biome lint + format check (no autofix)
bun run lint              # Biome lint with autofix
bun run check             # Lint + format with autofix
bun x tsc --noEmit         # TypeScript check only

Full Pre-Push Gate

bun run check:ci && bun x tsc --noEmit && bun test --bail

Or run the /clew-verify skill, which runs the full gate and a real CLI smoke test — green tests alone don't prove an Ink TUI feature actually works.

Release

Pushing a v* tag triggers the GitHub Actions release and npm publish. Before tagging: bump package.json, update CHANGELOG.md, run the full gate above. The workflow publishes to npm only; configure the repository NPM_TOKEN secret for authentication. See AGENTS.md § Release or run the /clew-release skill.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

• Report bugs via GitHub Issues
• Discuss ideas in GitHub Discussions
• Read AGENTS.md for full architecture and code conventions

Star History

License

GPL-3.0. See LICENSE.md.

Release history in CHANGELOG.md.