Getting Started with Clutch

English {#english}

Time: ~5 minutes after install · Audience: first-time users (no coding required)

What you'll do

Install Clutch from a release package
Complete the first-launch setup wizard
Send your first message in Chat

Before you start

You need	Notes
macOS 14+ or Windows 10/11 (x64)	See compatibility. Windows installers are not yet verified on physical hardware — macOS is the primary tested platform.
A project folder	Any git repo or folder Clutch may read/write
At least one AI backend	Cloud API key or a local CLI (Claude Code, CodeBuddy, Codex, Ollama, …)

You do not need Node, Python, or Rust to use the desktop app.

Step 1 — Install

macOS (Apple Silicon) — terminal (easiest):

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

Or with Homebrew:

brew tap fancy1108/clutch
brew install --cask clutch

Or manual download:

Open GitHub Releases and download the latest installer for your OS.
macOS: drag Clutch.app into Applications. If macOS blocks launch, see Install guide — Gatekeeper.
Windows: run Clutch_*_x64-setup.exe or the MSI. Not yet verified on real Windows hardware — CI-built only; report issues on GitHub.

Clutch is a desktop app, not an npm install -g CLI. See INSTALL.md for install.sh / install.ps1 options.

Quick Gatekeeper fix (macOS, copy-paste):

xattr -cr /Applications/Clutch.app && open -a Clutch

Full install details: docs/INSTALL.md

Step 2 — First-launch wizard

On first open, Clutch shows a full-screen setup wizard. Follow the steps in order:

Step	What it means
Welcome	Waits until the local backend (Sidecar) is healthy
Workspace	Pick the folder agents may work in — only this tree is writable
Models	Add a cloud API key (DeepSeek, Anthropic, OpenCode Zen, …) or skip if you will use local CLI only
Tools	Scan and Connect CLIs already on your machine (Claude Code, CodeBuddy, Ollama, Codex, …)
Flow guide	Short tour of Chat vs Workflow
Permissions	Pick Clutch Agent mode (default Agent; also Plan / Full / Ask)
Ready	Launch into the main app

Skipped the wizard? Open Settings (gear, bottom-left) and complete: Workspace → Models → Tools.
Developers can replay the wizard: INSTALL.md — first-use checklist.

Step 3 — Your first chat

In the sidebar, click New Chat.
At the bottom, pick an Agent (e.g. a connected Claude or Ollama agent).
Type a short message — e.g. "What files are in this repo?"
Watch the Chat stream, Terminal logs, and file tree on the right.

Tip: If you see "model not available" or "model not found", open Settings → Models and pick a model that is actually configured, or Settings → Tools to connect a local CLI.

Step 4 (optional) — Run a workflow

Workflows are multi-step SOPs on a canvas (several agents in sequence).

Settings → Workflows SOP — open a built-in template or create one.
Enable it from Chat or start a run from the workflow panel.
Approve or reject steps when Clutch pauses for human review.

Product tour: PRODUCT_INTRO.md · Architecture: ARCHITECTURE.md

Common setups

Goal	What to configure
Claude Code locally	Settings → Tools → Rescan → Connect `claude`
Cursor Agent CLI	`curl https://cursor.com/install -fsS \| bash` → Settings → Tools → Rescan → Connect `cursor-agent`
CodeBuddy CLI	`npm install -g @tencent-ai/codebuddy-code` → Settings → Tools → Connect `codebuddy` → run `codebuddy` once to log in
Grok CLI (D14)	Install `grok` on PATH per xAI docs → Settings → Tools → Rescan → Connect Grok CLI (`grok-cli`)
Ollama locally	Install Ollama, pull a model (`ollama pull qwen3:8b`), Settings → Tools → Connect Ollama; pick the model in Agent settings or Models
Cloud API only	Settings → Models → Clutch Agent tab → add provider key → activate a model
CLI agent models	Settings → Models → Claude Code, OpenCode, or MiMo Code tab (read-only scan; configure in the CLI or CC Switch)
Allow network (D15)	Settings → General → Allow network → Clutch Agent gains builtin `web_search` (off by default)
Strict sandbox (D21)	Settings → General → Strict sandbox → reject paths/commands that escape the authorized workspace
Cross-session memory (D16 / B-39)	Settings → General → Memory on/off + Clear memory; say `记住：…` then open Files → `.clutch/memory/MEMORY.md`
Tool hooks (D17)	Add `.clutch/hooks.json` (project) or user prefs `hooks.json` with PreToolUse/PostToolUse deny rules
Capability packs (D35)	Settings → Skills → Import pack (dir/zip); Uninstall removes mounted skills/hooks/MCP snippets
Slash commands (D18)	In Chat composer type `/` → `/plan` `/compact` `/todos` `/help` (+ Skills)
Terminal Orchestra	Single Agent chat → pick any connected CLI agent → toggle Terminal mode (embedded xterm PTY). Bottom OrchestratorBar matches Chat input dock; dispatch history shows CLI session resume commands (`claude --resume`, `codex resume`, `opencode -s`, `mimo -c`, `zcode --resume`, …)
MiMo Code CLI	`curl -fsSL https://mimo.xiaomi.com/install \| bash` (or `npm install -g @mimo-ai/cli`) → Settings → Tools → Connect MiMo Code CLI
ZCode CLI	Install ZCode desktop app → symlink `~/.local/bin/zcode` → `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` → Settings → Tools → Connect ZCode CLI
Headless / CI Agent (D36)	Sidecar running + workspace authorized → `curl -X POST http://127.0.0.1:8124/api/agent/run -H 'Content-Type: application/json' -d '{"prompt":"…","workspace_path":"/abs/path"}'` or `cd services/orchestrator && uv run python -m src.headless_cli -p "…" --workspace /abs/path --json`
OpenCode Zen (free)	opencode.ai/auth → Zen → API Keys → Settings → Models → OpenCode Zen → pick a free model → Save
Agnes (free)	Settings → Models → Clutch Agent → Agnes key → built-in Agnes 3.0 Flash (chat), Agnes Image 2.5 Flash, Agnes Video 2.5 Flash (720P)
CC Switch users	Keys can be imported from `~/.cc-switch` on startup
Remote HTTP MCP	Settings → MCP → Clutch Agent → Transport HTTP → paste URL (Figma example: `https://mcp.figma.com/mcp`) → Register → Test. API keys in Env; OAuth remotes open a browser. Guide: `mcp-servers/figma.md`

UI map (30 seconds)

Sidebar          Main area              Right panel
────────         ─────────              ───────────
New Chat    →    Chat / Workflow    →   Terminal · Files · Diff
AI Agents        canvas
Workflows
Settings ⚙       (Models · Tools · …)

Troubleshooting

Problem	Try
App won't open (macOS)	Gatekeeper steps
"Cannot connect" / empty UI	Quit fully (`Cmd+Q`), reopen; check `curl -s http://127.0.0.1:8123/health`
Model 404 / not found	Settings → Models — pick an installed Ollama tag or valid API model
CLI not listed	Settings → Tools → Rescan; ensure CLI works in Terminal `PATH`
Folder picker dead	Use Clutch.app, not `pnpm dev` in a browser

More: INSTALL.md — troubleshooting · GitHub Issues

CLI permissions (read once)

Clutch may call local CLIs with --dangerously-skip-permissions so workflows can run without per-tool prompts. Only use on folders you trust. Details: README § Security

Next steps

All features: PRODUCT_INTRO.md
macOS auto-update (v1.0.2+): UPDATES.md
Build from source: BUILD_FROM_SOURCE.md
Contribute: CONTRIBUTING.md

Chinese (Simplified) {#chinese}

用时： 安装后约 5 分钟 · 读者： 第一次使用、无需写代码

你会完成什么

从 Release 安装 Clutch
走完首次启动的设置向导
在聊天里发出第一条消息

开始之前

需要	说明
macOS 14+ 或 Windows 10/11 (x64)	见兼容性说明。Windows 安装包尚未在实体机上完整验收 — 目前以 macOS 为主要测试平台。
一个项目目录	任意 git 仓库或文件夹，Clutch 只在该目录内读写
至少一种 AI 能力	云端 API Key 或本机 CLI（Claude Code、CodeBuddy、Codex、Ollama 等）

使用桌面安装包时，不需要安装 Node、Python 或 Rust。

第 1 步 — 安装

macOS（Apple Silicon）— 终端一键安装：

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

或 Homebrew：

brew tap fancy1108/clutch
brew install --cask clutch

或手动下载：

打开 GitHub Releases，下载适合你系统的最新安装包。
macOS： 将 Clutch.app 拖入 应用程序。若被系统拦截，见安装指南 § Gatekeeper。
Windows： 运行 Clutch_*_x64-setup.exe 或 MSI。尚未在真实 Windows 实体机上完整验收 — 目前仅 CI 构建；问题请提交 Issue。

Clutch 是桌面应用，没有 npm install -g clutch。详见 INSTALL.md 中的 install.sh / install.ps1。

macOS 终端一键解除拦截（可复制）：

xattr -cr /Applications/Clutch.app && open -a Clutch

完整安装说明：docs/INSTALL.md

第 2 步 — 首次设置向导

第一次打开会出现全屏设置向导，按顺序完成即可：

步骤	含义
欢迎	等待本机后端（Sidecar）就绪
工作区	选择 Agent 可以读写的项目目录
模型	填写云端 API Key（含 OpenCode Zen 等），或若只用本机 CLI 可暂时跳过
工具	扫描并 Connect 本机已装的 CLI（Claude Code、CodeBuddy、Ollama、Codex 等）
流程引导	了解「单聊」和「工作流」的区别
权限模式	选择 Clutch Agent 权限（默认 Agent；另有 Plan / Full / Ask）
就绪	进入主界面

跳过了向导？ 点左下角 Settings，依次配置：工作区 → Models → Tools。
开发环境可重新弹出向导：INSTALL.md §6。

第 3 步 — 发出第一条聊天

侧栏点击 New Chat（新对话）。
底部选择一个 Agent（例如已连接的 Claude 或 Ollama Agent）。
输入简短问题，例如：「这个仓库里有哪些文件？」
在中间看聊天，右侧看 终端日志 和 文件树。

提示： 若提示 模型不可用 或 model not found，请到 Settings → Models 选择已配置好的模型，或到 Settings → Tools 连接本机 CLI。

第 4 步（可选）— 跑一条工作流

工作流是在画布上编排的多 Agent SOP（多个步骤串联）。

Settings → Workflows SOP — 打开内置模板或新建。
在 Chat 中启用，或从工作流面板启动运行。
需要人工审批时，在界面里 批准 / 打回 / 重试。

功能全景：PRODUCT_INTRO.md · 架构：ARCHITECTURE.md

常见配置

目标	怎么配
本机 Claude Code	Settings → Tools → Rescan → Connect `claude`
Cursor Agent CLI	`curl https://cursor.com/install -fsS \| bash` → Settings → Tools → Rescan → Connect `cursor-agent`
CodeBuddy CLI	`npm install -g @tencent-ai/codebuddy-code` → Settings → Tools → Connect `codebuddy` → 终端运行 `codebuddy` 完成登录
Grok CLI（D14）	按 xAI 文档安装 `grok` 并加入 PATH → Settings → Tools → Rescan → Connect Grok CLI
本机 Ollama	安装 Ollama，执行 `ollama pull qwen3:8b`，Settings → Tools 连接 Ollama；在 Agent 或 Models 里选模型
只用云端 API	Settings → Models → Clutch Agent 标签页 → 填 Key → 激活模型
CLI Agent 模型	Settings → Models → Claude Code、OpenCode 或 MiMo Code 标签页（只读扫描；在 CLI 或 CC Switch 中配置）
允许联网（D15）	Settings → General → Allow network → Clutch Agent 可用内置 `web_search`（默认关）
严格沙箱（D21）	Settings → General → Strict sandbox → 拒绝逃出已授权工作区的路径/命令
跨会话记忆（D16 / B-39）	Settings → General → Memory 开关；说「记住：…」后在 Files 打开 `.clutch/memory/MEMORY.md`
工具 Hooks（D17）	项目 `.clutch/hooks.json` 或用户偏好目录 `hooks.json` 配置 PreToolUse/PostToolUse 拒绝规则
能力包（D35）	Settings → Skills → Import 导入目录/zip；Uninstall 卸载挂载的 skills/hooks/MCP
斜杠命令（D18）	Chat 输入 `/` → `/plan` `/compact` `/todos` `/help`（及 Skills）
Terminal Orchestra	Single Agent 聊天 → 选择任意已 Connect 的 CLI Agent → 切换终端模式（嵌入式 xterm PTY）。底部 OrchestratorBar 与 Chat 输入栏同款贴底；派发记录含 CLI Session 恢复命令（`claude --resume`、`codex resume`、`opencode -s`、`mimo -c`、`zcode --resume` 等）
MiMo Code CLI	`curl -fsSL https://mimo.xiaomi.com/install \| bash`（或 `npm install -g @mimo-ai/cli`）→ Settings → Tools → Connect MiMo Code CLI
ZCode CLI	安装 ZCode 桌面应用 → 将 `~/.local/bin/zcode` 软链到 `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` → Settings → Tools → Connect ZCode CLI
无 UI / CI Agent（D36）	Sidecar 已启动且工作区已授权 → `curl -X POST http://127.0.0.1:8124/api/agent/run …` 或 `cd services/orchestrator && uv run python -m src.headless_cli -p "…" --workspace /绝对路径 --json`
OpenCode Zen（免费）	opencode.ai/auth → Zen → API Keys → Settings → Models → OpenCode Zen → 选免费模型 → 保存
Agnes（免费）	Settings → Models → Clutch Agent → 填 Agnes Key → 内置 Agnes 3.0 Flash（对话）、Agnes Image 2.5 Flash、Agnes Video 2.5 Flash（720P）
CC Switch 用户	启动时可从 `~/.cc-switch` 导入
远程 HTTP MCP	Settings → MCP → Clutch Agent → Transport HTTP → 填网址（Figma 例：`https://mcp.figma.com/mcp`）→ Register → 测试连接。API Key 写 Env；OAuth 远程会打开浏览器。步骤：`mcp-servers/figma.md`

界面速览

侧栏              主区域                 右侧面板
────              ──────                 ────────
New Chat    →     聊天 / 工作流画布  →   终端 · 文件 · Diff
AI Agents
Workflows
Settings ⚙        （Models · Tools · …）

常见问题

现象	处理
macOS 打不开	Gatekeeper 步骤
连不上 / 空白	完全退出（`Cmd+Q`）再开；`curl -s http://127.0.0.1:8123/health`
模型 404 / 找不到	Settings → Models — 选本机已安装的 Ollama 或有效 API 模型
CLI 扫不到	Settings → Tools → Rescan；确认终端里能直接运行该命令
选文件夹无反应	必须用 Clutch.app，不要用浏览器开 `pnpm dev`

更多：INSTALL.md § 故障排除 · 提交 Issue

CLI 权限（建议读一遍）

部分本地 CLI 默认带 --dangerously-skip-permissions，工作流才能自动跑通。请只在信任的项目目录使用。详见 README § 安全。

下一步

全部功能： PRODUCT_INTRO.md
macOS 应用内更新（v1.0.2+）： UPDATES.md
源码构建： BUILD_FROM_SOURCE.md
参与贡献： CONTRIBUTING.md

Navigation Menu

Repository navigation

GETTING_STARTED.md

GETTING_STARTED.md

Getting Started with Clutch

English {#english}

What you'll do

Before you start

Step 1 — Install

Step 2 — First-launch wizard

Step 3 — Your first chat

Step 4 (optional) — Run a workflow

Common setups

UI map (30 seconds)

Troubleshooting

CLI permissions (read once)

Next steps

Chinese (Simplified) {#chinese}

你会完成什么

开始之前

第 1 步 — 安装

第 2 步 — 首次设置向导

第 3 步 — 发出第一条聊天

第 4 步（可选）— 跑一条工作流

常见配置

界面速览

常见问题

CLI 权限（建议读一遍）

下一步

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started with Clutch

English {#english}

What you'll do

Before you start

Step 1 — Install

Step 2 — First-launch wizard

Step 3 — Your first chat

Step 4 (optional) — Run a workflow

Common setups

UI map (30 seconds)

Troubleshooting

CLI permissions (read once)

Next steps

Chinese (Simplified) {#chinese}

你会完成什么

开始之前

第 1 步 — 安装

第 2 步 — 首次设置向导

第 3 步 — 发出第一条聊天

第 4 步（可选）— 跑一条工作流

常见配置

界面速览

常见问题

CLI 权限（建议读一遍）

下一步