cc-master Deep Dive: Turn Any Coding Agent Session into a Long-horizon Project Lead

Core idea: cc-master turns any supported coding agent session — Claude Code, Codex, Cursor, or kimi-code — into a "project lead for long-running work." You bring the idea and make the few calls that truly need you; it helps break the work down, run independent pieces in parallel, track progress and quota, and verify the result against an explicit goal. The board survives context resets and session handoffs, so work can continue without relying on one conversation's memory — this is the essential difference between it and "an agent inside a single conversation."

1. Project Overview

1.1 What is it?

cc-master is an Agent orchestration framework (written in TypeScript) open-sourced by nemori-ai, aimed at upgrading "a single coding agent session" into a project lead that can survive days of work, run multiple threads in parallel, and persist across sessions.

Official one-line positioning:

cc-master turns a supported coding-agent session into a project lead for long-running work. You bring the idea and make the handful of calls that truly need you; it helps break the work down, run independent pieces in parallel, track progress and quota, and verify the result against an explicit goal. The board survives context resets and session handoffs, so the work can continue without relying on one conversation's memory.

One-sentence summary: in the age of AI-assisted coding, cc-master reroutes your human attention to where it is actually worth spending — the dirty work of breaking things down, scheduling, progress and quota bookkeeping is handed to the "project lead," and you only handle direction and major decisions.

1.2 Project metadata

1.3 What it is NOT (important boundary)

But please don't misunderstand — this is NOT "make a wish and AI handles everything." Taste, design, direction — the decisions only you can make still belong to you; what it takes off your plate is only the breaking down, scheduling, progress and bookkeeping that should have buried you otherwise.

When NOT to use cc-master:

A fix that's a couple of lines you can finish in ten minutes? Just do it — don't call in a "project lead," that's overkill and only makes you slower. It is built for goals one person can't watch over, that run for days, and that fan out into many threads at once. The bigger, messier, and longer the work, the more it's worth using.

1.4 Who it is for (three target personas)

2. Core Idea

2.1 Attention Reallocation

At bottom it does one thing: in the age of AI-assisted coding, it reallocates your attention to where it's actually worth spending.

At bottom it does one thing: in the age of AI-assisted coding, it reroutes your attention to where it is actually worth spending. Human attention is a scarce resource; instead of staring at every agent's output and tracking every line of progress, concentrate your attention on the judgments only you can make.

2.2 The conductor never plays an instrument

The conductor never plays an instrument.

This is cc-master's most important design red line: the coordinator coordinates and never does unit work itself. Any change pushing the main thread toward "implementing it myself" or "reviewing it myself" is the wrong direction. This principle runs through skill design, hook design, and the board state machine.

2.3 Six charter goals

The project charter lists six goals (some still evolving):

1. Async parallel multi-threaded push, goal-complete delivery
2. Control token consumption pacing (quota-aware)
3. Master the boundary between autonomous decisions and human-machine collaboration (which calls to escalate to humans)
4. Goal slicing, management, update, planning
5. Scheduling orchestration that maximizes efficiency within reasonable resource consumption
6. Select the right model by complexity / difficulty / duration (O/T1/T2/T3)

2.4 The essential difference from "fully autonomous agents"

• Not "one prompt runs everything" — it introduces an explicit Goal Contract and verification gate, and the result must be checked item by item against the goal.
• Not a single conversation — the Board persists to disk (~/.cc_master/boards/*.board.json), surviving context resets and session handoffs.
• Not for every kind of work — it has explicit "when NOT to use it" boundaries (small fixes: just do them, don't call the project lead).

3. Detailed Tutorial

3.1 Hard prerequisites

3.2 One-line install (ccm engine + plugin together)

# Install ccm engine + plugin (auto-detects harness by default)
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash

3.3 Install options (pin version / target harness)

# Pin both engine and plugin versions (the two flags are independent and both optional)
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- \
  --ccm-version ccm-v0.23.0 --plugin-version v0.22.0

# Pin only the engine; plugin uses latest
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- --ccm-version ccm-v0.23.0

# Target a specific harness
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- --harness claude-code
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- --harness cursor
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- --harness kimi-code

# Install for every harness
curl -fsSL https://raw.githubusercontent.com/nemori-ai/cc-master/main/install.sh | bash -s -- --all-harnesses

3.4 Key environment variables

3.5 Starting orchestration in each harness

After install, use the native entry point for your harness:

# Claude Code (slash command)
/cc-master:as-master-orchestrator <your goal>

# Codex (subcommand)
$cc-master-as-master-orchestrator <your goal>

# Cursor (Agent chat slash command)
/as-master-orchestrator <your goal>

# kimi-code (namespaced plugin command)
cc-master:as-master-orchestrator <your goal>

3.6 Daily command cheat-sheet

3.7 The shape of one full workflow

1. You:        /cc-master:as-master-orchestrator "Migrate the blog site to the new i18n architecture"
2. cc-master:  Create a Goal Contract → slice the goal into a DAG (T0 research → T1/T2 parallel implementation → T3 verification)
3. cc-master:  Assign each task a model role per O/T1/T2/T3, dispatch workers to Claude Code / Codex / etc.
4. Hit a call that truly needs you → /cc-master:discuss or /cc-master:bulk-discuss
5. Context nearly full → /cc-master:handoff-to-new-session → new session --resume, board is restored as-is
6. All tasks done → verify-board gate checks each Goal Contract clause → /cc-master:stop to archive
7. Optional:    /cc-master:retro → /cc-master:distill turns the lessons into team assets

4. System Architecture

4.1 Three-layer product model

┌─────────────────────────────────────────────────────────┐
│  cc-master plugin (per-harness adapters)                  │
│  commands / skills / rules / hooks                          │
│  → Claude Code · Codex · Cursor · kimi-code            │
├─────────────────────────────────────────────────────────┤
│  ccm CLI + @ccm/engine (independent product)              │
│  board / Goal Contract / worker / agent registry /      │
│  quota / model policy / runtime / monitor / viewer      │
├─────────────────────────────────────────────────────────┤
│  ccm web-viewer (read-only, embedded in the ccm binary)   │
│  Graph / Board / List / Timeline / DecisionCard          │
└─────────────────────────────────────────────────────────┘

• Layer 1: per-harness plugin adapters — translate the same commands/skills/hooks into each harness's native shape.
• Layer 2: ccm CLI and @ccm/engine — the harness-decoupled engine product, responsible for the board, worker, quota, and model policy.
• Layer 3: ccm web-viewer — read-only browser view (Graph / Board / List / Timeline / DecisionCard).

4.2 The source-to-adapter projection model (paragoge style)

plugin/src/                      ← canonical source (SSOT)
  skills/                        ← SAP: <skill>/canonical/ + adapters/<host>/strategy.yaml
  hooks/                         ← PHIP: _manifest/ + _hosts/<host>/ + implementations/<host>/
  commands/                      ← command body source
  adapters/                      ← cross-surface host-native invocation maps
plugin/dist/<host>/              ← generated adapter artifacts (committed to the repo)
  cc-master-plugin-claude-code-<version>.zip
  cc-master-plugin-codex-<version>.zip
  cc-master-plugin-cursor-<version>.zip
  cc-master-plugin-kimi-code-<version>.zip

4.3 Board v2 data model (narrow waist)

The Board is a JSON file at ~/.cc_master/boards/<UTC-timestamp>-<pid>.board.json:

{
  "schema": "cc-master/v1",
  "goal": "...",
  "owner": { "active": true, "session_id": "abc123", "heartbeat": "..." },
  "git": { "worktree": "/.../.claude/worktrees/i18n", "branch": "feat/i18n-rollout" },
  "wip_limit": 4,
  "tasks": [
    { "id": "T0", "status": "done", "deps": [], "artifact": "commit a1b2c3", "verified": true },
    { "id": "T1", "status": "in_flight", "deps": ["T0"], "mechanism": "sub-agent", "handle": "bg-7a" },
    { "id": "D1", "status": "blocked", "blocked_on": "user", "title": "Should the PR be split into two?" }
  ],
  "log": []
}

Task status enum: ready / in_flight / blocked(blocked_on:"user"|"<taskid>") / done / escalated / failed / stale / uncertain

Narrow-waist principle: only a small fixed set of fields are depended on by hooks — schema / goal / owner.session_id / git / tasks[{id,status,deps}] plus the status enum; everything else is "free-form for the agent." To change the narrow waist, you must update every hook + test in the same PR.

4.4 Eight distributed Skills (shared across all harnesses)

4.5 O / T1 / T2 / T3 unified model assignment

4.6 Hooks: dormant-until-armed

Every hook is fully dormant until the session is taken over by as-master-orchestrator and the board is activated; only bootstrap-board.sh is the exception (it IS the arming action). Seven categories of capability:

4.7 Quota posture and Monte Carlo prediction

• Quota posture: per-provider cached machine-level quota signals — Claude Code 5h/7d, Codex 7d hard limit, Cursor billing cycle, kimi-code rolling 5h/7d.
• Monte Carlo prediction: runs thousands of simulations on a schedule, producing a delivery-probability estimate — instead of guessing "it'll be ready tomorrow," you get a distribution.

4.8 Dual version line (ADR-022)

The plugin and engine are two independent version lines, pinnable separately — this guarantees "engine upgrades don't blow up plugins, plugin updates don't have to wait for the engine."

5. Design Philosophy

5.1 The conductor never plays an instrument

The coordinator coordinates, and never does unit work itself. Any change pushing the main thread toward "implementing/reviewing it myself" is the wrong direction — this is the single most important red line in the entire system.

5.2 Attention reallocation

The system's ultimate goal is not "automate everything," but to reroute human attention to where it is actually worth spending. Deterministic dirty work — breaking down, scheduling, progress, bookkeeping — gets automated; the non-outsourceable judgment — taste, design, direction — stays with the human.

5.3 ship-anywhere

Hooks only use bash + node/JS (the runtime guaranteed by the Claude Code host), not jq / python / raw TS; they don't depend on agent-teams or scheduled routines (unreliable); scheduled primitives (CronCreate) are used only for watchdogs, never for normal scheduling.

5.4 dormant-until-armed

If not activated, it does not exist: every hook is fully dormant until the session takes over and the board is activated, pushing "side effects when not in use" to zero.

5.5 Narrow waist

Hooks only depend on a tiny fixed field set; everything else is free-form space for the agent; changing the narrow waist must update every hook + test in the same PR. This lets the system balance "deterministic core" against "agent freedom."

5.6 Dual version-line decoupling

Plugin and engine release independently and can be version-pinned separately; the architecture decision is captured in ADRs (39 already exist). This embodies "long-horizon architecture decisions": make selections on a 3-year horizon, no temporary workarounds.

5.7 Explicit usage boundary

The most counter-intuitive part of the design philosophy is proactively drawing the "shouldn't use" boundary: ten-minute small fixes — just do them, don't call a project lead. The system is built for "too big, too messy, too long" goals — the larger the work, the more worth using it.

6. Synthesis: opinions and conclusions

1. A single conversation's memory should not be the only work state: persisting the Board to disk, surviving context resets and session handoffs, is the key step that takes long-horizon agent work from "demo" to "production-ready."

2. Orchestration over invention: cc-master doesn't invent a new agent — it orchestrates Claude Code / Codex / Cursor / kimi-code together — reusing existing authentication and capability; the value is in "conducting," not "the instrument."

3. Human attention is a scarce resource; reallocate it: automating deterministic dirty work (breaking down / scheduling / bookkeeping) while preserving non-outsourceable judgment (taste / design / direction) is the right division of labor in the age of AI-assisted coding.

4. "Wish-driven full automation" is a fake need: the explicit Goal Contract + verification gate + discuss mechanism prove that real usable orchestration must put humans back in the decision loop, not bypass them.

5. Quota awareness is the foundation of long-horizon work: Monte Carlo delivery prediction + per-provider quota posture turns "can it ship on time" from gut feeling into a probability distribution.

6. A deterministic core and agent freedom can coexist: the narrow-waist board + dormant hooks + ship-anywhere runtime give the system both verifiable determinism and agent flexibility.

7. Cross-harness adaptation is systems engineering: projecting the same set of skills/hooks/commands onto the native shape of 4 harnesses (SAP/PHIP model) is more sustainable than "writing a separate stack for each harness."

8. Boundary awareness is a sign of maturity: explicitly saying "when not to use" reflects a tool's clarity about its own positioning more than piling on features does.

References

• Repo home: https://github.com/nemori-ai/cc-master
• Chinese README: README_zh.md
• Feature manual: design_docs/feature-manual.md
• Capability model: design_docs/cross-harness-orchestration-capability-model.md
• Full spec: design_docs/spec.md
• Glossary: design_docs/glossary.md
• Architecture decision records: adrs/ADR-001…ADR-039
• Command catalog: plugin/src/skills/using-ccm/canonical/references/command-catalog.md