Clade

English | [中文](README.zh-CN.md)

Clade

Autonomous coding, evolved.

124 skills, 27 hooks, 36 agents, a safety guardian, and a correction learning loop — all working together so Claude codes better, catches its own mistakes, and can run unattended overnight while you sleep.

Two layers: CLI (product center — skills, hooks, scripts you live in) + Orchestrator (observability + gates + execution adapter — watch parallel workers, verify quality gates, route work).

> If this saves you time, a star helps others find it. Something broken? Open an issue.

> Blog post: Building Clade — motivation, design decisions, and lessons learned.

Table of Contents

1. [Install](#install)
2. [MCP Server](#mcp-server--use-skills-in-any-ai-editor)
3. [What It Does](#what-it-does)
4. [Self-Learning Mechanisms](#self-learning-mechanisms)
5. [Skills](#skills-124)
6. [Supported Languages](#supported-languages)
7. [Documentation](#documentation)
8. [Repo Structure](#repo-structure)
9. [Contributing](#contributing)
10. [License](#license)

Install

Full Framework (recommended)

git clone https://github.com/shenxingy/clade.git
cd clade && ./install.sh

Installs skills, hooks, agents, scripts, and safety guardian. Start a new Claude Code session to activate.

> Requires: jq. Platform: Linux and macOS.

MCP Server Only

If you just want the skills in Cursor, Windsurf, Claude Desktop, or any MCP client:

pip install clade-mcp

See [MCP Server](#mcp-server--use-skills-in-any-ai-editor) below for configuration.

MCP Server — Use Skills in Any AI Editor

The MCP server exposes all 124 Clade skills as callable tools via the Model Context Protocol. Works with any MCP-compatible client.

Claude Desktop / Claude Code:

{
  "mcpServers": {
    "clade": { "command": "uvx", "args": ["clade-mcp"] }
  }
}

Cursor / Windsurf:

{
  "mcpServers": {
    "clade": { "command": "clade-mcp" }
  }
}

> Prerequisite: Claude Code CLI must be installed — skills execute via claude -p.

What It Does

| When | What fires | Effect | |------|-----------|--------| | Session opens in a git repo | session-context.sh | Loads git context, handoff state, correction rules, model guidance | | Session opens in a git repo | commit-archeology.sh | Mines git log for recurring fix patterns (wiring/deploy/compat gaps, Claude-overridden) — injects top 4 | | Claude runs a bash command | pre-tool-guardian.sh | Blocks dangerous ops: migrations, rm -rf, force push, DROP TABLE | | Claude edits code | post-edit-check.sh | Async type-check (tsc, pyright, cargo check, go vet, etc.) | | You correct Claude | correction-detector.sh | Logs correction, prompts Claude to save a reusable rule | | Claude marks task done | verify-task-completed.sh | Adaptive quality gate: compile + lint, build + test in strict mode |

See [How It Works](docs/how-it-works.md) for the full hook reference (27 hooks).

Self-Learning Mechanisms

Two mechanisms keep Clade aligned with reality without manual upkeep:

• Commit Lessons (reactive) — commit-archeology.sh mines git log for recurring fix patterns (wiring-gap, deploy-gap, compat-gap, claude-overridden) and injects the top 4 at every session start.
• Doc Align (preventive) — doc-align.py declares shared facts in docs/facts.json (auto-derived from filesystem); checks/auto-fixes drift across every *.md. A PostToolUse hook flags drift the moment you edit a doc, so stale counts never reach commit.

Both work on any project Claude Code is run in (universal, in ~/.claude/scripts/). Both are silent no-ops on repos that haven't opted in.

See [Self-Learning Mechanisms](docs/learning-mechanisms.md) for full details, detectors, schemas, and tunable env vars.

Skills (124)

Core Workflow

| Skill | What it does | |-------|-------------| | /commit | Split changes into logical commits by module, push by default | | /sync | Check off completed TODOs, append session summary to PROGRESS.md | | /review | 8-phase coverage review — finds AND fixes issues, loops until clean | | /verify | Verify project behavior anchors (compile, test, lint) |

Autonomous Operation

| Skill | What it does | |-------|-------------| | /start | Autonomous session launcher — morning brief, overnight runs, cross-project patrol | | /loop GOAL | Goal-driven improvement loop — supervisor plans, workers execute in parallel | | /iloop TASK | In-session iterative loop — Stop hook re-prompts until done (no background workers) | | /batch-tasks | Execute TODO steps via unattended sessions (serial or parallel) | | /orchestrate | Decompose goals into tasks for worker execution | | /handoff | Save session state for context relay between agents | | /pickup | Resume from previous handoff — zero-friction restart | | /worktree | Create git worktrees for parallel sessions | | /poke | Heartbeat after esc — 3-line status, auto-continues if still progressing | | /status | Session dashboard — background agents, loops, worktrees, unpushed commits | | /go | Execute the recommendation from your most recent A/B/C option set |

Code Quality

| Skill | What it does | |-------|-------------| | /review-pr N | AI code review on a PR diff — Critical / Warning / Suggestion | | /merge-pr N | Squash-merge PR and clean up branch | | /investigate | Root cause analysis — no fix without confirmed hypothesis | | /incident DESC | Incident response — diagnose, postmortem, follow-up tasks | | /cso | Security audit (OWASP + STRIDE) | | /map | Generate ARCHITECTURE.md with module graph + file ownership |

Research & Planning

| Skill | What it does | |-------|-------------| | /research TOPIC | Deep web research, synthesize to docs/research/ | | /model-research | Latest Claude model data + auto-update configs | | /next | "What's next?" — fast 1-shot recommendation (default); /next deep for multi-round interview | | /brief | Morning briefing — overnight commits, costs, next steps | | /retro | Engineering retrospective from git history | | /frontend-design | Create production-grade frontend interfaces |

System

| Skill | What it does | |-------|-------------| | /audit | Clean up correction rules — promote, deduplicate, remove stale | | /document-release | Post-ship doc sync (README, CHANGELOG, CLAUDE.md) | | /pipeline | Health check for background pipelines | | /provider | Switch LLM provider | | slt | Toggle statusline quota pace indicator |

Blog & Content (30 skills)

| Skill | What it does | |-------|-------------| | /blog | Full lifecycle — brief → outline → write → SEO check | | /blog-write | Write SERP-informed articles from scratch | | /blog-rewrite | Optimize existing posts for quality and SEO | | /blog-audit | Full-site health scan (thin content, meta, cannibalization) | | + 26 more | analyze · audio · brand · brief · calendar · cannibalization · chart · cluster · discourse · factcheck · flow · geo · google · image · locale-audit · localize · multilingual · notebooklm · outline · persona · repurpose · schema · seo-check · strategy · taxonomy · translate |

SEO (25 skills)

| Skill | What it does | |-------|-------------| | /seo | Full SEO audit suite | | /seo-technical | Crawlability, indexability, Core Web Vitals | | /seo-page | Deep single-page analysis | | /seo-content | E-E-A-T and content quality scoring | | + 21 more | audit · backlinks · cluster · competitor-pages · content-brief · dataforseo · drift · ecommerce · flow · geo · google · hreflang · image-gen · images · local · maps · plan · programmatic · schema · sitemap · sxo |

Paid Ads (23 skills)

| Skill | What it does | |-------|-------------| | /ads | Multi-platform ads audit suite | | /ads-google | Google Ads — Quality Score, PMax, bidding | | /ads-meta | Meta Ads — Pixel/CAPI, creative fatigue, Advantage+ | | /ads-create | Create new ad campaigns from brief | | + 19 more | amazon · apple · attribution · audit · budget · competitor · creative · dna · generate · landing · linkedin · math · microsoft · photoshoot · plan · server-side-tracking · test · tiktok · youtube |

Email (6 skills)

| Skill | What it does | |-------|-------------| | /email-write | Compose high-converting emails (PAS, AIDA, BAB frameworks) | | /email-audit | Deliverability audit — SPF, DKIM, DMARC, blacklists, health score | | /email-sequence | Design automation sequences (welcome, nurture, re-engagement) | | + 3 more | check · plan · review |

See [When to Use What](docs/when-to-use-what.md) for detailed usage guidance.

Supported Languages

Auto-detected — hooks and agents adapt to your project:

| Language | Edit check | Type checker | Test runner | |----------|-----------|-------------|-------------| | TypeScript / JavaScript | tsc (monorepo-aware) | tsc | jest / vitest | | Python | pyright / mypy | pyright / mypy | pytest | | Rust | cargo check | cargo check | cargo test | | Go | go vet | go vet | go test | | Swift / iOS | swift build | swift build | swift test | | Kotlin / Android / Java | gradlew | gradlew | gradle test | | LaTeX | chktex | chktex | — |

All checks are opt-in by detection — if the tool isn't installed, the hook silently skips.

Documentation

| Guide | Contents | |-------|----------| | [Maximize Throughput](docs/throughput.md) | Skip permissions, batch tasks, parallel worktrees, terminal + voice | | [Orchestrator Web UI](docs/orchestrator.md) | Chat-to-plan, worker dashboard, settings, iteration loop | | [Overnight Operation](docs/autonomous-operation.md) | Task queue, parallel sessions, context relay, safety | | [How It Works](docs/how-it-works.md) | Hooks, agents, skills internals, correction learning, model selection | | [Configuration](docs/configuration.md) | Settings, thresholds, adding custom hooks/agents/skills | | [When to Use What](docs/when-to-use-what.md) | Detailed usage guidance for every skill | | [Who to Learn From](docs/who-to-learn-from.md) | Vetted watch-list of the agentic-coding frontier — people, repos, bot behavior, reviewed quarterly |

Dotfile Sync

Keep ~/.claude/ in sync across machines — memory, corrections, skills, hooks, and scripts.

~/.claude/scripts/sync-setup.sh            # auto-detect NFS or GitHub
~/.claude/scripts/sync-setup.sh --github   # explicit GitHub backend

Fully automatic once configured. See [Configuration](docs/configuration.md) for details.

Architecture

CLI layer (configs/ → installed to ~/.claude/): Product center. Skills, hooks, scripts you invoke daily. Works standalone, no server needed.

Orchestrator (orchestrator/): Observability + gates + execution adapter. Watches parallel workers, enforces quality gates, routes tasks, provides web UI for multi-project oversight. Optional — CLI works independently.

Web UI (orchestrator/web/): Read-only observation window. Task queue, worker status, cost dashboard, settings. No production logic — all executes via CLI.

clade/
├── install.sh               # One-command deployment
├── configs/                 # ← THE PRODUCT CENTER
│   ├── skills/              # 124 skill definitions
│   ├── hooks/               # 27 event hooks
│   ├── agents/              # 36 agent definitions
│   └── scripts/             # 38 shell + Python utilities
├── orchestrator/            # ← THE EXECUTION ADAPTER
│   ├── server.py            # FastAPI app, routes, WebSocket
│   ├── worker.py            # WorkerPool, SwarmManager, task dispatch
│   ├── task_queue.py        # SQLite task queue + CRUD
│   └── web/                 # ← THE OBSERVATION WINDOW
│       └── src/             # React + Vite UI (served from dist/)
├── docs/                    # Guides and research
├── adapters/openclaw/       # OpenClaw integration (mobile monitoring)
└── templates/               # Settings, CLAUDE.md templates

OpenClaw Integration

Monitor and control overnight loops from your phone via OpenClaw.

| Skill | Trigger | Effect | |-------|---------|--------| | clade-status | "how's the loop going" | Iteration progress, cost, commits | | clade-control | "start a loop to fix tests" | Start/stop autonomous loops | | clade-report | "what did it do overnight" | Session report, cost breakdown |

See [adapters/openclaw/README.md](adapters/openclaw/README.md) for setup.

Contributing

Contributions welcome — code, docs, issue triage, bug reports. See [CONTRIBUTING.md](CONTRIBUTING.md).

Known Limitations

1. Loop on non-code tasks (research/docs) fails silently — workers produce no diff, loop reports failure
2. Workers inherit parent env — project-specific env vars leak into worker shells; sanitize before overnight runs
3. Context budget is per-session — multi-day runs may exhaust context; use /handoff + /pickup

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shenxingy
• Source: shenxingy/Clade
• License: MIT
• Homepage: https://alexshen.dev/en/blog/clade

Install and usage instructions live in the source repository linked above.