Content
# Clutch
Local AI Multi-Agent Orchestration and Supervision Console (Tauri Desktop App + Python Sidecar).
## What is this
**Clutch** is designed for independent developers and technical operations personnel, addressing two engineering pain points: "single agent dialogue context expansion" and "multi-agent collaboration process black box, difficult to modify". It's not meant to replace Claude Code / Cursor's generative capabilities, but rather to add a **persistent, observable, and editable** process control layer locally: you drag-and-drop SOP on the canvas, and the system schedules local CLI, MCP, and large models using LangGraph, and supervises execution and manual approval in a unified workbench.
**Tech Stack:** Tauri 2 · React 19 · FastAPI + LangGraph · Local First (Sidecar `localhost:8123`)
### Key Features (Overview)
| Capability | Description |
| --- | --- |
| **Visual Workflow Orchestration** | React Flow canvas defines multi-agent SOP, compiled into LangGraph state machine execution |
| **Local AI Tool Access** | Scan and connect local CLI such as Claude Code, Codex, Ollama, Aider |
| **Unified Supervision Console** | Chat flow, terminal logs, file tree, code diff, process progress visible on one screen |
| **Human-Machine Collaborative Gate Control** | High-risk operations or check failures suspended, supporting approval / rejection / retry |
| **Agent and Model Configuration** | Agent Manager, model API Key, Skills registry, MCP service gateway |
| **Hybrid Session** | Multi-session parallel, workflow refinement and automatic re-run, state recovery across sessions |
> **Want to learn about all features, architecture details, and operating mechanisms?** Please read **[`docs/PRODUCT_INTRO.md`](./docs/PRODUCT_INTRO.md)** (product introduction authoritative document, including pain point analysis, page function list, and data flow description). Developer architecture narrative see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
## Product Screenshots
**Hybrid Workflow Supervision Desk** — Multi-agent collaboration, process progress, and token statistics visible on one screen:
**Visual SOP Orchestration** — Zero-code drag-and-drop multi-agent pipeline on the canvas:
## Repository Structure
> Consistent with disk (excluding `node_modules`, `.venv`, `dist`, etc.). Governance layer five-level annotation see [`docs/document-governance.md`](./docs/document-governance.md).
```
clutch/
├── README.md # Project entrance (this page)
├── LICENSE · CHANGELOG.md # Open source and version (GitHub convention in root directory)
├── SECURITY.md · CODE_OF_CONDUCT.md · CONTRIBUTING.md
├── CLAUDE.md · AGENTS.md # Layer 1 — Governance and multi-AI tool index
├── package.json · pnpm-workspace.yaml · .env.example
├── scripts/ # verify · tauri-dev · doctor · release-preflight
├── apps/desktop/ # Tauri + React desktop end
├── services/orchestrator/ # Python Sidecar (LangGraph)
├── packages/shared-types/
├── workflows/ # Workflow JSON Schema + built-in template
├── docs/ # Product and architecture documents → docs/README.md
├── memory/ # Layer 3 — Agent cross-session runtime
├── specs/core/ # Layer 2 — Demand/task historical snapshot
├── e2e/ · experiments/ · runs/
└── .github/ · .husky/ · .cursor/ # CI · hooks · Agent rule pointer
```
**Decoupling Principle:** `apps/desktop` and `services/orchestrator` communicate only through loopback HTTP/WebSocket (development `8124`, packaging `8123`).
## Document Map
**Complete Index:** [`docs/README.md`](./docs/README.md) (grouped by role).
### Root Directory (Community and Governance)
| File | Purpose |
| --- | --- |
| [`CLAUDE.md`](./CLAUDE.md) | **Unique Authority**: Iron law, command, check-in, log specification |
| [`AGENTS.md`](./AGENTS.md) | Multi-AI tool entry index |
| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | How to contribute, Phase 1 PR policy |
| [`SECURITY.md`](./SECURITY.md) · [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) | Vulnerability report · Community guidelines |
| [`CHANGELOG.md`](./CHANGELOG.md) | Version change (current **1.0.0**) |
### Product and Architecture (`docs/`)
| File | Purpose |
| --- | --- |
| [`docs/PRODUCT_INTRO.md`](./docs/PRODUCT_INTRO.md) | **Recommended First Read**: Positioning, function, operating mechanism |
| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | System architecture, workflow, WebSocket |
| [`docs/UI_UX_GUIDELINES.md`](./docs/UI_UX_GUIDELINES.md) | Front-end React + Tailwind specification |
| [`docs/INSTALL.md`](./docs/INSTALL.md) · [`docs/BUILD_FROM_SOURCE.md`](./docs/BUILD_FROM_SOURCE.md) | Installation DMG · Source code build |
| [`docs/OPEN_SOURCE_RELEASE.md`](./docs/OPEN_SOURCE_RELEASE.md) | Open source release schedule OSR-xx |
### Agent Runtime (`memory/`)
| File | Purpose |
| --- | --- |
| [`memory/PROGRESS.md`](./memory/PROGRESS.md) | Cross-session progress relay |
| [`memory/FILEMAP.md`](./memory/FILEMAP.md) | Code modification to which file |
| [`memory/DECISIONS.md`](./memory/DECISIONS.md) | Architecture decision and open issue |
## Compatibility
> Detailed stability see [`docs/STABILITY.md`](./docs/STABILITY.md). **0.x version may break change at any time.**
### Platform
| Item | Support Level |
| --- | --- |
| macOS 14+ (Apple Silicon) | ✅ Official main target |
| macOS 14+ (Intel) | ⚠️ Best effort support, not fully tested |
| macOS 13 and earlier | ⚠️ Not guaranteed |
| Windows | 🚧 Architecture reserved, no official installation package |
| Linux | 🚧 No official installation package |
### Development Toolchain (source code build)
| Component | Version Requirement |
| --- | --- |
| Node.js | **≥ 20** (recommended 22 LTS) |
| pnpm | **≥ 9** (repository locked `9.15.0`) |
| Python | **≥ 3.11** (CI uses 3.11) |
| [uv](https://docs.astral.sh/uv/) | Latest stable version |
| Rust | Latest stable (only required for `pnpm tauri build`) |
Environment self-test:
```bash
./scripts/doctor.sh
```
## Quick Start
**Prerequisites**: Node 20+, pnpm 9+, Python 3.11+, [uv](https://docs.astral.sh/uv/), Rust (for Tauri packaging)
```bash
pnpm install
```
Start and verify commands see [`CLAUDE.md`](./CLAUDE.md) § Core Commands.
## Installation
> ### ⚠️ Unsigned DMG · First installation must read
>
> The `.dmg` in the current Release is **not signed or notarized by Apple**. macOS may prompt "**Unable to verify developer**" or "**Application is damaged**" — **This is Gatekeeper's normal response to unsigned applications, not a virus, nor is the package damaged.**
>
> **Copy and paste to use (terminal):**
>
> ```bash
> xattr -cr /Applications/Clutch.app && open -a Clutch
> ```
>
> Or: **Applications** → Right-click **Clutch** → **Open** → Confirm open.
> Detailed description and disclaimer: [`docs/INSTALL.md`](./docs/INSTALL.md) · Each Release description see [GitHub Releases](https://github.com/fancy1108/Clutch/releases).
### Install from Release (Terminal User · macOS)
Download the **macOS `.dmg`** from [GitHub Releases](https://github.com/fancy1108/Clutch/releases) (current version is unsigned build, which is also a common distribution method for open-source desktop applications):
1. Download the corresponding architecture DMG (Apple Silicon select `aarch64`) and drag it into **Applications**
2. **First open** if intercepted by Gatekeeper (including "**Damaged**" text), choose one:
- **Finder**: Right-click **Clutch.app** → **Open** → Confirm open
- **Terminal (recommended, copyable)**: `xattr -cr /Applications/Clutch.app && open -a Clutch`
3. About 5s inner sidecar should be ready: `curl -s http://127.0.0.1:8123/health` → `{"status":"ok"}`
Maintainer release: Tag `v1.0.0` (or subsequent `v1.x.x`) triggers [`.github/workflows/release.yml`](./.github/workflows/release.yml) automatic build and upload DMG; or local `cd apps/desktop && pnpm tauri build` and then manually upload to Release.
Complete installation instructions see [`docs/INSTALL.md`](./docs/INSTALL.md); data and privacy see [`docs/DATA_AND_PRIVACY.md`](./docs/DATA_AND_PRIVACY.md). After obtaining the Apple Developer account, you can provide code signature and notarization installation package.
### Build from Source (Developer)
```bash
git clone https://github.com/fancy1108/Clutch.git
cd Clutch
./scripts/doctor.sh
pnpm install
cd services/orchestrator && uv sync --extra dev && cd ../..
export CLUTCH_RUNTIME_MODE=hybrid # Optional
pnpm tauri:dev
```
Step-by-step instructions, split debugging, and local DMG building: [`docs/BUILD_FROM_SOURCE.md`](./docs/BUILD_FROM_SOURCE.md).
**Before contributing**, please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) and run `./scripts/verify.sh`.
## Security and CLI Permissions (Important)
Clutch schedules external AI CLI through local Sidecar (`127.0.0.1:8123` / development `8124`). Please understand the following **current version** behavior:
### CLI Default Skips Built-in Confirmation (`--dangerously-skip-permissions`)
For **Claude Code CLI** (`claude-cli`) and **Antigravity CLI** (`agy-cli`) and other accessed engines, Clutch **defaults** to append `--dangerously-skip-permissions` when calling. This will **bypass** the corresponding CLI's tool/write confirmation prompt, so that the workflow and Hybrid session can run automatically.
| Meaning | Description |
| --- | --- |
| **Applicable Scenario** | You have trusted the current authorized workspace and accept the Agent to automatically execute tool calls within the directory |
| **Risk** | CLI can modify files, run commands within the workspace (and CLI's own permission reachable range), **will not** ask again |
| **Permission Menu in UI** | Chat column next to `ask` / `auto_edit` / `plan` / `full` mainly for **Clutch built-in Agent's MCP gate control**; **does not change** the above CLI's `skip-permissions` default behavior |
**Permission Policy Statement:** The current stage defaults to maintaining the skip confirmation setting. If the security policy is adjusted to default `ask` (ask for each time), it will synchronously update this article and [`SECURITY.md`](./SECURITY.md).
Vulnerability report see [`SECURITY.md`](./SECURITY.md). Sidecar only listens to the local loopback address.
Connection Info
You Might Also Like
No recommendations available