# Clavue v13.2.1

![Clavue cover](https://unpkg.com/iclavue/image.png)

`clavue` is an execution-first AI coding CLI for real software work. It keeps the terminal as the control surface, uses direct repo tools for inspection/editing/verification, treats API providers as configurable routes, and includes native workflows for review, recovery, team inspection, and long-running sessions.

> **npm package name:** install from **`iclavue`** on the public registry (`npm install -g iclavue`).  
> **Launch commands (same engine):** **`clavue`** · **`agent`** · **`ai`** · **`chat`** (also `iclavue`).  
> The older unscoped package name `clavue` is under an npm security hold and must not be used.


## Install / upgrade (recommended)

The npm registry is the source of truth for the latest version (`npm view iclavue version`). Every path below resolves `latest` from npm, so a plain re-run upgrades an existing install:

```bash
npm install -g iclavue@latest && hash -r
clavue --version          # 13.2.1 (Clavue)
```

One-liner without a global install, or the install script (also npm-backed):

```bash
npx -y iclavue
curl -fsSL https://unpkg.com/iclavue/install.sh | bash
```

Pin a version:

```bash
npm install -g iclavue@13.2.1
curl -fsSL https://unpkg.com/iclavue@13.2.1/install.sh | bash -s -- 13.2.1
```

Inside a running session `/update` (or `clavue update`) checks `npm view iclavue@latest` and reinstalls. If `clavue --version` still prints an old number after an upgrade, run `clavue --version --detail` — a stale launcher from another package (`clavue@8.x`) may shadow the `iclavue` bin; `npm install -g iclavue@latest` re-links it, `repair.sh` cleans a half-finished install.

> The website mirror (`https://www.clavue.com/cli/install.sh`, `/downloads/clavue/VERSION`) is maintained separately by the site operator and may lag behind npm; when it does, use the npm / unpkg paths above.


## Product Philosophy

Clavue is built around a simple operating model: the user owns the workflow, the CLI owns the execution loop, and providers are replaceable routes.

- Execution first: every feature should help inspect, edit, run, verify, or recover real software work.
- Terminal-owned workflow: Clavue stays close to files, commands, diffs, permissions, and project state instead of becoming a detached chat surface.
- Provider control, not provider identity: official login, custom API profiles, and compatible gateways are routing choices. The product identity remains Clavue.
- Native coding workflows: direct file tools, shell execution, task tracking, worktrees, skills, and MCP resources are part of the runtime loop.
- Fast first run: install, choose an API configuration mode, paste URL/key or token, set model slots if needed, then start coding.
- Visible configuration: `/provider` and `clavue provider` expose the active route, saved profiles, credential mode, model slots, validation, repair, and current environment state.
- Practical autonomy: permission setup should make development smoother while still being explicit about trust boundaries.
- Continuity over spectacle: long-context recovery, compaction, `/team`, and `/retro` exist to keep work moving, not to add noise.

## What Clavue Is

- An execution-first AI coding CLI for inspecting, editing, running, verifying, and delivering code from the terminal.
- A native coding runtime with direct repo tools, shell execution, permissions, tasks, worktrees, skills, MCP resources, and resumable sessions.
- A provider control center for custom API URLs, API keys, auth tokens, model slots, route validation, and repair.
- A fast onboarding path for users who want official login, custom API configuration, CCR-compatible proxy routing, or manual setup later.
- A runtime that can use compatible providers and gateways without pretending those providers are the product.
- A set of native workflows for coding, review, recovery, team inspection, and retrospective improvement.

## Core Surfaces

Canonical primary command surfaces:

- `/help`: browse available commands and custom command sources.
- `/init`: create or refresh generated project rule files: `clavue.md`, `AGENTS.md`, and compatibility `CLAUDE.md`.
- `/provider`: configure, switch, validate, repair, copy, edit, delete, or save provider profiles.
- `/permissions` (`/approvals` compatibility alias): set the default permission mode so trusted development environments can run with less friction; use `/permissions autonomous` for an opt-in high-autonomy local development lane.
- `/team`: inspect local team readiness, active team config, and capability state.
- `/loop`: create, list, run, pause, resume, and stop closed-loop automations backed by durable `/goal` ledgers.
- `/retro`: run a multi-round repo retrospective and upgrade loop.
- `/tasks`: inspect task-board state for long-running work.
- `/resume`: continue saved sessions.
- `/doctor`, `/login`, `/logout`, `/mcp`, `/model`, `/parallel`, `/plugin`, and `/status`: primary setup, routing, orchestration, and diagnostics flows.

Secondary surfaces such as `/review`, `/compact`, `/config`, `/memory`, `/theme`, `/usage`, and `/vim` remain available for focused workflows. Compatibility aliases are documented only when they are part of a canonical flow; internal, hidden, disabled stub, and experimental commands are not public defaults. Long-context recovery includes proactive compaction plus reactive overflow recovery for long-running work.

## Study Guide

For full user-facing usage and learning documentation, start in [study/README.md](./study/README.md).

For provider and model routing setup, see [Clavue Provider And Model Best Practices](./docs/clavue-provider-model-best-practices.md).

For **developer / upgrade law**, start at [Baseline 12.0.1](./docs/clavue-baseline-12.0.1.md) and [Doctrine Map](./docs/clavue-doctrine-map.md). Superseded 11.x docs live in [`docs/old文档/`](./docs/old文档/README.md).

## Install

Requirements:

- Node.js 18 or newer
- macOS or Linux shell environment

Run once with `npx` when you do not want a global install:

```bash
npx -y iclavue
```

Run a specific version with `npx`:

```bash
npx -y iclavue@13.2.1 --version
npx -y iclavue@13.2.1
```

Install globally from npm when you want the `clavue` command to stay available:

```bash
npm install -g iclavue
clavue --version
clavue
```

One-line global install:

```bash
curl -fsSL https://unpkg.com/iclavue/install.sh | bash
```

Install a specific version globally:

```bash
curl -fsSL https://unpkg.com/iclavue@13.2.1/install.sh | bash -s -- 13.2.1
```

### Troubleshooting: `ENOTEMPTY` / `bash: clavue: No such file or directory`

`npm install -g iclavue` can fail with:

```
npm error code ENOTEMPTY
npm error ENOTEMPTY: directory not empty,
  rename '/usr/lib/node_modules/iclavue' -> '/usr/lib/node_modules/.iclavue-Txlq2RSw'
```

This is a generic npm bug that strikes large global packages (iclavue is
~74 MB unpacked / 4251 files) when an earlier install was interrupted.
npm's atomic-rename leaves behind a `.iclavue-<rand>` staging directory
that blocks every future install at the same path. The bin symlink also
goes missing, so `clavue` exits with `No such file or directory`.

One-liner fix:

```bash
curl -fsSL https://unpkg.com/iclavue/repair.sh | bash
```

The repair script removes live package dirs, staging leftovers, dangling
`bin/clavue` / `bin/iclavue` symlinks, then reinstalls `iclavue@latest`.
Set `CLAVUE_NO_INSTALL=1` to clean only.

Manual fallback if the script is unreachable:

```bash
PREFIX=$(npm prefix -g)
sudo rm -rf "$PREFIX/lib/node_modules/iclavue" \
            "$PREFIX/lib/node_modules/.iclavue-"* \
            "$PREFIX/lib/node_modules/clavue" \
            "$PREFIX/lib/node_modules/.clavue-"* \
            "$PREFIX/bin/clavue" \
            "$PREFIX/bin/iclavue"
npm install -g iclavue@latest
```

## Quick Start: Provider And Model Setup

Fastest path for custom API users:

1. Install with `curl -fsSL https://unpkg.com/iclavue/install.sh | bash`
2. Start with `clavue`
3. At `请选择 API 配置模式`, choose `自定义 API 配置`.
4. At `请选择模型路由模式`, choose the family that matches your models.
5. At `请选择操作`, choose `1. 添加配置`.
6. Enter a profile name, API base URL, authentication type (`API Key` or `Auth Token`), credential, and model slots.
7. After saving, choose `no` at `返回主菜单？` to enter Clavue with the saved default profile.
8. Run `/provider` inside Clavue, or `clavue provider` from the shell, to reopen the provider manager.
9. Run `/model` only for main-session model selection. In combination mode it follows the current `/provider` Primary slot; helper and planning slots remain owned by `/provider`.

Recommended model-slot setup:

```text
主模型 (primary): your main coding model for user turns / mainLoop (e.g. claude-sonnet-4-6 or gpt-5.4)
Haiku 模型 (smallFast): fast helper for light background roles only (classify yolo, memory search, tool quick-summary, hooks/background)
Sonnet 模型 (subagent/general): workhorse for subagent execution, daily coding, summarize/extract (day-to-day heavy but not planner)
Opus 模型 (plan/guide): planning / high-capability / guide roles
```

Note: smallFast roles are intentionally rare in main interaction (by design for cost/speed); most visible work uses primary/subagent/general. In GPT-5.5 + DeepSeek combo routing, DeepSeek Flash powers smallFast/general helper slots; Codex Spark/DSpark aliases are separate OpenAI-family model names and are not the DeepSeek lightweight lane. Use `clavue provider doctor` to see live role→model mapping.

Useful recovery commands:

```bash
clavue provider        # reopen the same API setup manager
clavue provider list   # list saved profiles without opening the UI
clavue provider current
clavue provider doctor # diagnose source-of-truth, drift, validation, and next repair action
clavue provider validate
```

Use `clavue auth login` only if you want the official Anthropic login path. Custom API users do not need official login.

## First Useful Session

Start Clavue from a repository and ask for one reviewable unit of work:

```text
Inspect the failing test around provider routing, make the smallest source fix, run the targeted test, then run the relevant verification command before reporting back.
```

Clavue should inspect files directly, edit the source, run commands such as `node --test tests/<file>.test.mjs`, and report what was verified.

## First-Run Setup Modes

On first launch, Clavue should make the setup choice obvious:

```text
请选择 API 配置模式:
  使用官方登录
  自定义 API 配置
  使用 CCR 代理
  跳过（稍后手动配置）
```

- Use official login when you want the official Anthropic account flow.
- Use custom API configuration when you have an API base URL plus API key or auth token.
- Use CCR proxy when your environment already standardizes on a compatible proxy route. Existing ZCF/CCJK routes can be imported with `clavue provider import --from zcf` or `clavue provider import --from ccjk`.
- Skip only when you want to configure later with `clavue provider`; `/provider` is available after entering a configured session.

After API setup, Clavue can also ask for a default permission mode. The recommended path for a trusted local development machine is the efficient development mode; the maximum-permission mode is intentionally reserved for environments you fully trust.

For deployments, releases, builds, packaging, and operational maintenance where file edits should proceed but shell commands must still be confirmed, use trusted ops mode:

```bash
clavue --permission-mode trustedOps
```

You can also set it in settings with `"permissions": { "defaultMode": "trustedOps" }`. `trustedOps` behaves like `acceptEdits` for file edit tools in the current workspace, but Bash/PowerShell commands still ask before execution. The legacy `dontAsk` permission mode is deprecated and will not activate from CLI or settings; migrate `dontAsk` defaults to `trustedOps` for release/build/deploy workflows.

For P0-P3 development loops where the repo and machine are trusted, run:

```text
/permissions autonomous
```

You can also run `/permissions` and choose `Autonomous development` from the mode picker. This installs the Clavue autonomous development preset. It makes Clavue more proactive for normal local engineering work by using `bypassPermissions` plus scoped development rules, while keeping explicit confirmation rules for release, publish, push, destructive, and infrastructure actions. The intended workflow is: let the model choose the best implementation path, inspect/edit/test autonomously, then leave final review and release decisions to the user. When Clavue detects trusted repair, TODO, upgrade, or routine local test/build work while autonomy is not active, it can recommend `/permissions autonomous` as the smoother development lane.

This package is intended for users who want an execution-first coding CLI with direct repository tools, native workflow orchestration, explicit permission control, and configurable provider routing when compatible providers or gateways are part of the setup.

On macOS, `clavue` avoids Keychain by default and stores local credentials in `~/.clavue/.credentials.json` so startup does not trigger system Keychain prompts. If you explicitly want the old Keychain behavior back, launch with `CLAVUE_USE_KEYCHAIN=1 clavue`.

## Long-Running Session Memory

Clavue automatically restarts normal long-running sessions with `--max-old-space-size=8192` before loading the full CLI. This prevents the common Node default ~4GB heap limit from killing large coding sessions with `Reached heap limit Allocation failed - JavaScript heap out of memory`.

Useful controls:

```bash
CLAVUE_MAX_OLD_SPACE_SIZE_MB=12288 clavue
CLAVUE_DISABLE_HEAP_REEXEC=1 clavue
NODE_OPTIONS="--max-old-space-size=12288" clavue
```

`clavue --version` stays on the zero-load fast path and does not restart.

## CLI Entry Points

Version check:

```bash
clavue --version
npx -y iclavue --version
npx -y iclavue@13.2.1 --version
# available after a global install and launcher setup
clavue --version
```

Provider/config entry point:

```bash
clavue provider
```

Anthropic account login/token commands:

```bash
clavue auth login
clavue setup-token
```

`clavue auth login` and `clavue setup-token` are only for Anthropic account auth flows. They are not the provider-profile entrypoint.

## In-Session Workflows

`/provider` manages saved profiles, current environment state, API URL, credential type, provider mode, and model-slot routing from one place. With no arguments it starts at the provider mode picker: combination mode for explicit multi-slot routing, single mode for one family/profile, and full API entry for official login, custom API, CCR, or manual setup. Use it when you want to switch, validate, repair, or save the active route.

```text
/provider
/provider list
/provider current
/provider doctor
/provider save-current kimi-main
/provider adopt-current kimi-main
/provider validate
/provider repair
/provider use gpt54-main
/provider use kimi-main
/provider clear
```

`/model` is the main-session model control. With no arguments it asks whether you want combination mode or single mode. Combination mode keeps the active `/provider` Primary model as the main session model and leaves the other slots under provider control; single mode opens the direct model picker. `/model <model-name>` remains the fast one-command override.

Runtime orchestration is adaptive by default after install. `orchestrationExecMode: "full"` does not mean every turn runs a full reviewer panel: simple edits stay on fast paths, complex or high-risk implementation turns add adversarial reviewer/verifier/judge phases, fallback cases use recovery chains, and release requests enter a release gate. This is the "fast and good" default: spend extra model work only where risk justifies it. If needed, set `orchestrationExecMode` in settings to `"observe"` for telemetry-only planning or `"off"` for the old single-model behavior. The benefit of `full` is better quality control for risky work; the cost is more latency and model usage on those risky turns.

The Mao supervisor ledger is still used internally by delivery gates; user-facing `/mao` and `/codex` command surfaces are hidden while native Team/Agent workflows remain the public agent system.

`/team` inspects real local team state from the active config root instead of giving a generic explanation. By default that is `~/.clavue/teams`, but it follows `CLAVUE_CONFIG_DIR` if you launch clavue against a different config root.

```text
/team
/team list
/team current
/team status myteam
/team show myteam
/team check
```

Typing `agent teams` at the start of a prompt opens the same native `/team` flow instead of sending that phrase to the model as plain text. Agent teams are enabled by default in Clavue; set `CLAVUE_DISABLE_AGENT_TEAMS=1` or `CLAVUE_AGENT_TEAMS=0` before launch only if you need to disable them. Use `/team check` for a concrete readiness report.

`/retro` runs a multi-round repo retrospective and upgrade loop guided by `PRODUCT.md` and `ARCHITECTURE.md`, with `tisheng.md` treated as historical context only when it still agrees.

```text
/retro
/retro provider control center stability
/retro onboarding and route validation
```

Companion commands are still available and can either follow the current app provider or bind to a saved `/provider` profile independently.

```text
/girl
/boy
/bigdaddy
/girl provider
/girl provider list
/girl provider inherit
/girl provider use <profile>
```

## Remote Sessions And Long Context

- Remote headers and status lines use the remote cwd instead of echoing the local machine path.
- Clearing a remote conversation clears the backend session before resetting the local UI.
- Idle task boards label unfinished work as needing continuation instead of implying active execution.
- Proactive compaction stays enabled for large sessions, and reactive overflow recovery remains available when a route still hits a hard context limit.

## Compatibility And Routing Notes

- Provider profiles live only under `~/.clavue` (or `CLAVUE_CONFIG_DIR`); nothing is imported from `~/.ccjk`, `~/.ufomiao/zcf` or `~/.claude`, and switching a profile never writes to those tools' files.
- Switching a profile (`/provider <name>`, `/provider official|byok|toggle`, or picking a line in the panel) sets the global default and binds the current chat; env is applied once, never re-bound per request.
- Proxy GPT routes stay on the Anthropic-compatible `/v1/messages` path by default. Set `CLAVUE_API_DIALECT=openai_responses` only when you explicitly want the Responses adapter for that gateway; `MYCLAUDE_API_DIALECT` remains a legacy-compatible alias.
- Recommended saved profile pattern: `gpt54-main` for a validated `gpt-5.4` route across the primary and inherited slots.
- Recommended saved profile pattern: `gpt53-all` when the route is validated for `gpt-5.3-codex` across the main thread and helper lanes.
- Recommended saved profile pattern: `kimi-main` or `glm-main` for provider-native routing with that provider's API URL and credential.

## Package And Release Model

- Source repo: `https://github.com/mycode699/clavue`
- Public package: `https://www.npmjs.com/package/iclavue` (CLI command: `clavue`)
- Public install entrypoint: `npx -y iclavue`
- `src/` is the development surface for new changes, while the checked-in `dist/` bundle is the current shipped runtime artifact
- `types/generated/` holds generated contract types that stay outside authored runtime source
- npm is the only package publishing target; GitHub Releases are not part of the normal release path
- Official website release updates are generated locally as changelog blocks and version usage notes before any site edit or deploy
- npm distributes the same tracked top-level runtime entrypoints that power `dist/cli.js`, without shipping nested `dist/` development artifacts, `.map` files, or `.d.ts` files
- `npm run verify:source-build` rebuilds the CLI from `src/` into `experimental-dist/` and smoke-tests the Node entrypoints as a structural guard
- `dist/` is still the shipped artifact today, but release verification now requires both tracked `dist/` integrity and a bootable source rebuild
- Trusted publishing is the intended npm release path so new tags do not require repeated local OTP prompts

## Developer Verification

```bash
npm run validate:repo
npm run verify:dist
node scripts/verify-provider-command-sidecar.mjs
npm run verify:source-build
npm run check:source-purity
npm test
npm run check
npm run check:release
npm run build
npm run package:release
```

- `npm run validate:repo`: checks package metadata, required tracked files, workflow presence, and tag/version consistency
- `npm run verify:dist`: smoke-tests `dist/cli.js`, provider setup, provider command, and release-critical sidecars
- `node scripts/verify-provider-command-sidecar.mjs`: focused guard that fails if `dist/provider-command.js` drifts from the authored provider command source
- `npm run verify:source-build`: rebuilds from `src/` into `experimental-dist/` and requires `--version` plus `--help` to boot under Node
- `npm run check:source-purity`: fails on inline source maps, compiler-transformed React output, generated stubs, or generated types inside `src/`
- `npm test`: runs packaging and release regression tests with Node's built-in test runner
- `npm run check`: quick local verification gate used by CI for normal pushes and PRs
- `npm run check:release`: full release verification gate with vendoring, clean dist verification, dist smoke, source rebuild, source purity, boundaries, and tests
- `npm run build`: runs `check:release` and previews the publishable npm tarball with `npm pack --dry-run`
- `npm run package:release`: runs `check:release` and produces archives in `release-artifacts/`
- `npm run rebuild:experimental`: manual alias for `npm run verify:source-build`
- `npm run rebuild:experimental:legacy`: older reconstruction path kept for manual investigation

For source reconstruction work there is still `npm run rebuild:experimental`, and the older `npm run rebuild:experimental:legacy` path remains available for comparison. Both write only to generated paths. The plugin-based rebuild is now part of local and CI verification, but it still does not replace tracked `dist/` as the shipped release artifact.