English | 中文

Clade

Autonomous coding, evolved.

129 skills, 30 hooks, 36 agents, a safety guardian, and a correction learning loop — with native distributions for Claude Code and Codex, plus a provider-neutral MCP bridge for other editors.

Three ways to use Clade: the full Claude CLI framework, the native Codex plugin, or the provider-neutral MCP bridge. Add the optional Orchestrator for multi-worker observability, quality gates, and task routing.

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
2. MCP Server
3. What It Does
4. Self-Learning Mechanisms
5. Skills
6. Supported Languages
7. Documentation
8. Repo Structure
9. Contributing
10. License

Install

Claude Code — Full Framework

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.

Codex — Native Plugin

codex plugin marketplace add shenxingy/Clade
codex plugin add clade@clade

Start a new Codex thread, then invoke a workflow naturally or explicitly with $review, $verify, $investigate, and the other bundled skills. Open /hooks once to review and trust Clade's session-context and command-safety hooks.

Run $codex-usage setup minimal for a compact native footer. $codex-usage defaults to the equally compact project(branch)-9% (6d) pace view; icon and detail styles are optional. It never reads or exposes Codex credentials.

The native plugin runs directly in Codex and does not require Claude Code. It currently ships 21 provider-native core workflows; Claude-specific overnight orchestration remains in the full framework. See Native Codex Support.

MCP Server Only

If you want Clade tools in another MCP client:

pip install --upgrade clade-mcp

Version 0.2.0 adds the Codex execution runtime while keeping Claude as the backwards-compatible default. See MCP Server below for configuration and the MCP package guide for all runtime and sandbox options.

MCP Server — Use Skills in Any AI Editor

The MCP package exposes 32 bundled Clade skills, plus compatible user-installed skills, as callable tools via the Model Context Protocol. It can execute them with either Claude or Codex.

Claude Desktop or another client using Claude as its runtime:

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

Cursor / Windsurf:

{
  "mcpServers": {
    "clade": {
      "command": "clade-mcp",
      "env": { "CLADE_RUNTIME": "codex" }
    }
  }
}

CLADE_RUNTIME accepts claude (the backwards-compatible default), codex, or auto. Prefer the native Codex plugin inside Codex itself; adding the MCP server there would duplicate skills and spawn nested agent sessions. The same applies inside the full Claude Code framework, where Clade skills are already native.

What It Does

See How It Works for the full hook reference (30 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 for full details, detectors, schemas, and tunable env vars.

Skills (129)

Core Workflow

Autonomous Operation

Code Quality

Research & Planning

System

Blog & Content (30 skills)

SEO (25 skills)

Paid Ads (23 skills)

Email (6 skills)

See When to Use What for detailed usage guidance.

Supported Languages

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

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

Documentation

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

Architecture

Claude CLI layer (configs/ → installed to ~/.claude/): Full skill, hook, script, and agent framework.

Codex plugin (plugins/clade/): Generated provider-native core skills plus Codex lifecycle hooks. Distributed through .agents/plugins/marketplace.json.

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/              # 129 skill definitions
│   ├── hooks/               # 30 event hooks
│   ├── agents/              # 36 agent definitions
│   └── scripts/             # 35 shell + 13 Python utilities
├── plugins/clade/           # Native Codex plugin (21 generated core skills + hooks)
├── .agents/plugins/         # Codex marketplace manifest
├── 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.

See adapters/openclaw/README.md for setup.

Contributing

Contributions welcome — code, docs, issue triage, bug reports. See 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