Larch

Larch is a Claude Code workflow automation framework that orchestrates multi-agent design, code review, and implementation through collaborative AI-driven processes.

New to larch? First prepare your repository for agent-assisted development, then follow the flow below.

Primary Flow

1. Create an issue describing the task/problem with /issue or /file-bug, or manually
2. Verify an existing report with /triage when its diagnosis needs evidence before planning
3. For contested or open-ended work, use /debate to produce a three-vendor proposal
4. Design it with /design (the detailed reviewed design is stored in the issue)
5. Implement it with /implement

Support Skills

• Manage issues and their dependencies: /issue, /umbrella, /complete-umbrella, /audit-umbrella, /file-bug, /triage, /combine-issues, /block-issue, /deps
• Various analysis tools: /report-tokens, /fluff-analysis, /difficulty-calibration, /rejected-analysis, /analyze-issues, /audit-runs
• larch management: /status, /upgrade-larch, /larch-size

Table of Contents

• Setup
  • Installation and Setup — prerequisites, auth (API keys or web login) for Claude / Codex / Cursor, plugin install and permissions, /status validation, /upgrade-larch
  • Preparing Your Repository. Ready your repo for larch and agent-assisted development: instruction files (CLAUDE.md/AGENTS.md), guardrails (guidelines, hooks, linters), and the checks run-relevant contract
  • Contributing — local dev plugin install, plugin cache vs. working-tree version, Mermaid CLI setup
  • Clean-Main Entry Contract — the /implement and /design clean main entry preconditions, plus /implement feature-branch continuation
  • Fork CI Dry-Runs — remote setup for /implement --forked
  • macOS Keychain Interactions — Cursor CURSOR_API_KEY and keychain auth troubleshooting
  • Optional Helpers — installing optional tools like ast-grep
• Reference
  • Features
  • Skills
  • Aliases
  • Review Agents — the unified code-reviewer archetype
  • Run Logs — remote run archives, local cache copies, manifests, and tracking-issue comments
  • Run-log Storage Contracts — configuration resolution, provider operations, archive and cache layouts, sync, errors, and Rust handoff
  • Analyzer State — mutable analyzer markers, ledgers, measurements, locking, and legacy import
  • Security References: security document taxonomy, ownership, and runtime packaging contract
  • Topology Projection — stable anchors for cross-doc topology counts
  • Linting — linters, Makefile targets, halt-rate regression harness
  • Issue-Anchored Plan — live wire format for the /design ↔ /implement plan handoff and clarification round-trip
• Architecture and workflow
  • Rust Architecture — crate ownership, dependency direction, external boundaries, and release constraints
  • Rust Async Runtime — cancellation, timeouts, bounded tasks, signals, and child shutdown
  • Rust Testing — shared fixtures, test boundaries, coverage, and CI partitioning
  • GitHub Service Inventory: typed operation ownership and production consumers
  • Workflow Lifecycle — how skills compose end-to-end
  • Agent System — parallel subagent orchestration
  • Design Flow — direct plan drafting and plan review
  • Voting Process — the voting panel protocol
  • Point Competition — reviewer scoring system

Features

• Direct design planning and plan reviews — Step 2b drafts the plan directly, then the validation panel reviews it.
• Voting-based review resolution — The YES/NO panel protocol adjudicates plan and code review findings.
• Persistent proposal debates: Cursor, Codex, and Claude negotiate from read-only repository evidence, then publish a cross-linked prose proposal before design.
• Reviewer competition scoring — Reviewers earn points based on finding quality; a scoreboard tracks accepted, neutral, and rejected findings.
• Tracked runs — Every skill invocation keeps local lifecycle bookkeeping. With run-log storage enabled, it publishes one terminal archive below the derived tool and client-repository root, such as s3://zhupanov/larch/larch/run-logs/<skill>/<run-id>.tar.gz. Without storage configuration, it warns and completes without a remote archive, synchronized cache entry, or pending publication. Nested and alias invocations keep distinct parent-linked run identities.
• Progress statusline — clone-local breadcrumbs show live larch progress without adding report text to model context.
• Tiered architectural knowledge — Optional ARCHITECTURAL_INVARIANTS.md and ARCHITECTURAL_GUIDELINES.md files are supplied to authoring agents plus the dedicated code-review compliance specialist and /design Architecture/Standards reviewer as untrusted, scope-bound evidence.

Skills

larch ships public skills with the plugin (skills/); private skills live under .claude/skills/ and are dev-only (not exported). Both are listed below; shortcut aliases are in the Aliases section. See docs/skills.md for full per-skill detail.

Public skills

Name	Arguments
/alias	[--merge] [--private] <alias-name> <target-skill> [preset-flags...]
Create an alias for a larch skill with preset flags. Auto-routes to skills/<n>/ in plugin source repos and .claude/skills/<n>/ elsewhere; --private forces the latter.
/block-issue	<ISSUE_A> <ISSUE_B> [--repo owner/name] --operator-invoked [--triage-controlled --expected-updated-at TIMESTAMP]
Express and verify a native GitHub blocked-by relationship between two issues using the addBlockedBy GraphQL mutation. Live mutation requires explicit operator invocation. Triage-controlled calls add exact target freshness, protected-state, security, relation read-back, and fresh-timestamp checks.
/file-bug	[--urgent] <bug description>
Investigate a user-described bug read-only, compose a detailed issue body whose root-cause section starts with a canonical Origin: line, then file it via /issue with dedup enabled. New issues are assigned to the GitHub user authenticated in gh. --urgent changes the title prefix. Aborts to SECURITY.md disclosure if the report looks security-sensitive; never edits the repo.
/triage	<issue-number> [--repo OWNER/REPO] [--report-only]
Verify and root-cause an eligible non-security issue against an immutable main snapshot before /design. Duplicate and dependency triage inspects open rows from at most the 100 newest issue records. A verified verdict may update or close the issue; --report-only and inconclusive results never mutate GitHub.
/cleanup	[--run-id <ID>]
Remove stale larch session temp directories from ~/.cache/larch/sessions/, /tmp, and the OS temp root $TMPDIR resolves to (a per-user path distinct from /tmp on macOS) by a bounded five-level nested-activity scan (LARCH_CLEANUP_RETENTION_DAYS, default 7): a directory is deleted only when the scan finds no file newer than the cutoff, so a directory with fresh deep activity is retained even when its top-level mtime is stale. Live session directories named by current environment or session pointers are retained regardless of age. Reaps dangling current-design-env-*.sh symlinks. Always runnable regardless of concurrent Claude sessions.
/combine-issues	[--oos]
Combine related issues from the 100 most recent open issues into fewer broader ones (closing the sources) to reduce token spend. --oos operates only on [OOS]-prefixed issues, discards stale items, and proposes an aggressive combination scheme.
/complete-umbrella	<umbrella-issue-N>
Implement every direct leaf of one managed umbrella serially. Fresh admission comes from the live reciprocal direct-leaf graph, not the /umbrella proposal marker, and requires at least one selectable leaf. One durable Rust-driven bgjob owns the full leaf loop: each iteration fetches one live graph, uses it to verify the prior child and select the smallest-numbered unblocked open leaf, synchronizes clean main, and launches a thin child on the same Claude model with larch skills disabled. A session-keyed pointer makes the same command reattach to a live loop or recover a dead child without replacing its leaf handoff root. Before implementation, recon/design preserves or creates the issue plan and writes an executable brief. It routes to /design only for a malformed existing plan block or a leaf body with no discernible requirements. A missing plan, leaf size, or cross-leaf sequencing concern does not stop an actionable leaf. The normal path runs fresh implement, adversarial-review, and ship contexts; a standalone driver handles PR, five-minute CI, merge-queue submission or direct admin merge, issue lifecycle, and branch cleanup. An exact orphaned bgjob result may continue only after a fresh remote proof that the same leaf is already closed [DONE]. Other failed children write a bounded step, leaf, and reason envelope and hard-stop the run. After all leaves close, the invoking agent audits the combined result, files and attaches exact new leaves for concrete gaps, and repeats until it can mark the parent [DONE] and close it.
/audit-umbrella	<umbrella-issue-N>
Audit one open top-level managed umbrella at a fresh detached default-branch snapshot. It builds a complete evidence ledger inline, persists the full corrective batch before mutation, and limits exact leaf deduplication to the 100 most recent open issues. It files only exact new leaves, assigns every created leaf to the GitHub user authenticated in gh, reconciles native sub-issue and blocked-by relations, and reads the final graph back. It never implements leaves, closes, or retitles the umbrella.
/deps	[--repo owner/name] [--pair-cap N]
Audit open issues by in-flight title prefix, conservatively refresh mutable REGULAR bodies, propose stale REGULAR closes, and infer dependencies with an explicit-ref scan plus latent semantic pass. Mutates only after AskUserQuestion approval. Dependency writes use /block-issue. --pair-cap is explicit partial-audit mode.
/debate	[-s|--vote-stalemates] <issue-number | free-form description>
Run a read-only, persistent Cursor/Codex/Claude negotiation and publish a cross-linked [PROPOSAL] issue. Default mode asks the operator to decide stalemates; -s uses the anonymized voter panel without operator input.
/design	[-p|--partition] [--brainstorm] [--per-round-approval] [--skip-approve|-s] [--no-dedup] [--run-id <ID>] [--difficulty <TRIVIAL|MODERATE|HARD>] <issue-N | feature description>
Author or refresh an issue-anchored implementation plan in GitHub (plan markers in the issue body). -p/--partition routes Step 2b.5 directly to the decomposition panel when no plan-size threshold trips; size triggers show the Override/Cancel prompt. An approved partition hands its exact batch and dependencies to /umbrella, which keeps dedup enabled, converts the original issue in place, and leaves it open above native leaf sub-issues. Optional --brainstorm runs Step 1d.5 ideation before the Step 1d.7 outline-approval gate (Gate A re-entry only post-plan) (see docs/skills.md). Gate B auto-applies accepted findings by default; --per-round-approval restores the explicit per-round apply prompt. --skip-approve/-s auto-approves the Step 1d.7 outline and Gate C final plan without an AskUserQuestion (no other prompts are skipped). The old --approve and --hard flags are rejected; use --per-round-approval for explicit Gate B prompts. Finalize runs upstream /larch:issue batch filing for accepted non-security OOS (Step 5b) before writing and publishing the larch:plan block (5c); tmpdir cleanup is Step 6.
/difficulty-calibration	[--log-root DIR] [--out FILE]
Compare predicted and realized difficulty tiers from the synchronized run-log cache. Diagnostic only; changes no thresholds, panels, tokens, routing, or reviewer points.
/fluff-analysis	[--include-in-progress] [--cutoff ISO8601] [--since-version X.Y.Z] [--min-group N] [--log-root DIR] [--out FILE]
Characterize review fluff from the synchronized run-log cache through its Rust-owned scripts/larch.sh command. Analyze which /design and /implement suggestions get rejected, deferred to OOS, or accepted but low-value, then print data-driven recommendations.
/implement	[--merge] [--forked] [--draft] [--no-admin-fallback] [--no-logs-commit] [--coder <claude|codex|cursor>] [--run-id <ID>] [--force|-f] [--self-review] [--self-implement] [--difficulty <TRIVIAL|MODERATE|HARD>] <issue-N>
End-to-end implementation from the positional GitHub <issue-N> after /design has written larch:plan into that issue's body. Any decision to replace the target with two or more implementation issues must use /umbrella; the single scope-disposition follow-up and OOS disposition issues are not target partitions. Step 5 always runs review-and-fix CLI with the internal review panel (no public --panel argv): hard ceiling of 2 for every tier, TRIVIAL singles, MODERATE pairs, HARD pairs with the Codex review role, pruning on round-1 productivity for round 2, three static specialists per vendor plus at most one dynamic archetype pair. Reviewer dispatch uses --no-fallback, so missing vendors drop rows instead of cross-vendor or Claude reviewer backfill. --merge enables CI, then uses the default-branch merge queue when enabled or the existing direct merge otherwise; --forked is mutually exclusive with --merge. Use --force (or -f) to skip the item 4 plan-adequacy audit and downgrade only the documented force Preflight gates to warn-and-proceed (default off; does not affect coder selection). --self-review skips the external panel for a thorough inline self-review at Step 5. --self-implement forces coder=claude, independent of --force (default off). Preflight audit refusal exits 3 (distinct from flag/plan hard errors exit 2).
/issue	[--input-file FILE] [--intra-batch-deps-file FILE] [--blocked-by-issue N] [--title-prefix PREFIX] [--label LABEL]... [--body-file FILE] [--dry-run] [--no-dedup] [--no-dep-llm] [--sentinel-file PATH] [<issue description or title>]
Create one or more GitHub issues with LLM-based semantic duplicate detection and inter-issue blocker-dependency analysis over at most the 100 newest issue records. Every new issue is assigned to the GitHub user authenticated in gh. --no-dedup skips both passes; --no-dep-llm keeps dedup but skips the LLM dependency pass. One Rust batch owner handles deterministic ordering, creates, dependency wiring, rollback, transitive skips, and counters. Batch/wiring flags (--input-file, --body-file, --blocked-by-issue, --intra-batch-deps-file, --sentinel-file) are used mainly by calling skills.
/umbrella	[--skip-approve|-s] [--no-dedup] <issue-N | description>
Create or resume a flat [UMBRELLA] issue whose direct leaves are durable native sub-issues that block it. Every new issue is assigned to the GitHub user authenticated in gh. One approval precedes all mutation; --skip-approve/-s follows the same proposal, sentinel, and graph-verification path. A Rust composer derives exact leaf identities, prefixes, opening text, and normalized body bytes from the approved batch. A record-less umbrella is adopted only after typed reads prove it has no direct sub-issues and no open blockers; closed blocker bodies are not read. A nested /design or /implement split may supply its already-approved exact batch and dependency graph; /umbrella persists that proposal, runs deduplicating /issue filing, converts the managed original atomically, and writes the parent completion sentinel only after verification. Deduplication and exact in-flight recovery inspect at most the 100 newest issue candidates. A resume reconciles only an exact title/body match before creating anything else, and never nests umbrellas.
/learn-from-bugs	[-n COUNT] [--state closed|open|all] [--repo OWNER/REPO --root PATH] [--search QUERY] [--zones a,b] [--full] [--file|-s] [verbal description]
Mine a repository's closed bug reports for recurring root-cause patterns, then propose preventions ranked by mechanical enforceability: lint rules, architectural invariants (including hook-contract best-home), guideline entries, regression tests, and issues to file for still-broken code. Report-only by default and approval-gated for apply follow-ups: it compresses each body to a compact root-cause digest whose origin classifier reads an explicit Origin: line first and records the matched or rejected signal, maps every recurring principle to the repo's existing coverage (guidelines, invariants, hooks, and lints) before proposing the residual gap, and runs the synthesis inline with no sub-agent fan-out. A durable scan marker makes the default search incremental and newest-first. A zero-selection window with unread matches keeps the marker unchanged and asks for --full or a larger limit. --full re-mines the prior window. The report opens Section 2 with a generated origin distribution (counts, percentages, referenced #origin -> #current chains, regression ratio) and marks guideline-only residuals with a prose-only prevention warning. --zones "a,b" scopes mining to an OR-group topical query; --file / -s groups all six residual proposal categories, computes caller-supplied dependency edges from declared proposal dependencies and shared implementation files, previews the batch through deterministic issue owners, and forwards non-empty edges through the single semantic /issue filing pass. Filing keeps /issue's semantic dependency analysis enabled, assigns every created issue to the GitHub user authenticated in gh, requires no separate approval prompt, and does not apply proposed changes directly. Unrecognized tokens remain verbal search text; -f is not a filing alias.
/pause
Pause a running /design; saves state to GitHub for cross-session resume when run-log storage is configured. Source: skills/pause/SKILL.md.
/rejected-analysis	--n DAYS
Recover verified real rejected code-review findings from the synchronized run-log cache and file issues by default. Open-issue overlap checks inspect at most the 100 most recent open issues. Security-sensitive findings are not public-filed, OOS-deferred findings are excluded, and the stable finding_hash uses file plus concern only, excluding run metadata and filesystem state.
/report-tokens	--skill <design|implement> [--no-issue] [--no-plot] [--run-id <ID>]
Analyze structured token reports from the synchronized run-log cache with Rust-owned `scripts/larch.sh report-tokens analyze`, price Claude/Codex/Cursor runs through `larch_core::report::RATE_TABLE`, plot skill-aware trends, and print cost-reduction suggestions.
/research	[--no-issue] <research question or topic>
Collaborative best-effort read-only research with the fixed-shape topology documented in the research skill — planner pre-pass, Codex-first research lanes by angle, and the validation panel. Every run includes unconditional citation validation (HEAD-fetches cited URLs under SSRF guards, validates DOIs, spot-checks file:line refs) emitted as a fail-soft PASS / FAIL / UNKNOWN ledger spliced into the final report.
/review	[--diff] [--subagent] [--dynamic-archetypes <N>] [--session-env <path>] [--step-prefix <prefix>] [--difficulty <TRIVIAL|MODERATE|HARD>] [<description>]
Code review with the specialist panel described in docs/review-agents.md. --diff: review branch changes and implement fixes. <description>: review existing code; description mode records voting outcomes and OOS artifacts locally — file follow-up issues with /issue when you want GitHub tracking. --subagent, --dynamic-archetypes, --difficulty, --session-env, and --step-prefix are used mainly by /implement Step 5.
/review-and-fix	--findings-file <path> [--session-env <path>] [--review-tmpdir <path>]
Apply accepted review findings as code fixes via Codex/Cursor/Claude-subagent dispatch. Internal sub-skill invoked by /review in diff mode and by /implement Step 5; not a standalone user entry point.
/set-up-forked-open-source-repo	--upstream <owner/repo> --fork <owner/repo> [--mirror-confirmed] [--init-submodules]
Configure the current checkout for upstream/fork OSS contribution: verify the fork, optionally sync it from upstream, rewire remotes, disable upstream pushes, and set main tracking.
/status	(none)
Print the current larch version and health status of external vendor tools (Codex and Cursor), using the same probe machinery as /implement.
/upgrade-larch	[--run-id <ID>]
Preflight the latest immutable release, refresh the runtime-only plugin install, bootstrap its matching executable, and verify the new cache root without deleting Claude-managed versions.
/voter-calibration	[--log-root DIR] [--min-votes N] [--outlier-threshold R] [--high-severity-threshold R] [--out FILE]
Measure voter agreement and chronic outlier voters from the synchronized run-log cache through its Rust-owned scripts/larch.sh command. Diagnostic only; does not affect spawning, thresholds, tokens, or reviewer points.

Private skills

Dev-only: not shipped with the plugin; runnable only inside the larch source tree.

Name	Arguments
/agnix-fix	<upstream-issue-number> [extra-flags...]
Fix an open agent-sh/agnix issue end-to-end via fork-CI dry-run: fetch the upstream issue body, provision the skip-changelog label on the fork, then forward to /implement --forked with the positional upstream issue number.
/analyze-bugs	[-n COUNT] [--deep-max M] [--deep-model sonnet|opus|fable] [--refresh] [--sample K] [--repo owner/name]
Dev-only verification of recent filed [BUG] issues. Defaults to -n 200, keeps compact durable state under the local XDG state directory, prints a report by default, and offers one combined follow-up issue only after approval.
/validate-merged	[--max-merges N] [--repo owner/name]
Dev-only validation of recent merged changes for possible unfiled bugs. Defaults to the previous 48 hours and at most 20 merges; durable state stays under the local XDG state directory.
/analyze-issues	[--limit N] [--span-days N] [--top-K N] [--categories=auto|default] [--log-root PATH] [--repo OWNER/REPO] [--lenient] [--ground-truth-verdict] [--since-date DATE] [--min-runs N] [--min-larch-version VERSION]
Generate a backlog-and-process insight report from a repo's GitHub issues. By default it synchronizes the repository-scoped run-log cache once; --log-root selects an offline or operator-provided corpus. Verdict mode skips the full backlog report, emits a filtered corpus block with explicit gate PASS/FAIL, and gates token allocation on a post-52.1.0, post-2026-06-26, incentivized-era realized-outcome corpus with strict started_at eligibility and a mechanical #5544 shipped check: closed with closedByPullRequestsReferences, not NOT_PLANNED.
/audit-runs	--skill <design|implement> [<verbal-description>] [--repo owner/name] [--allow-concurrent]
Audit recently-merged larch run logs for anomalies, file the chain-of-history audit-report issue, and propose bug-issue follow-ups that require explicit user direction before any filing. Proposal duplicate classification is capped at the 100 newest matching issues.
/larch-size	(none)
Report tracked repository line counts by language and test status, plus larch-logs size breakdowns. Takes no flags.
/rebalance-tests	[--kind {harness,rust,all}] [--repo owner/name] [--n-runs N] [--branch-prefix PREFIX] [--n-verify-runs N] [--n-rust-shards N] [--max-shard-wall-clock SECONDS] [--max-rust-shard-wall-clock SECONDS] [--experimental-wall-clock-override NOTE] [--compile-affinity TARGET=GROUP:SECONDS] [--workflow FILE] [--baseline-branch BRANCH] [--dry-run]
Rebalance CI test harness shards, Rust coverage shards, or both through the checked Rust workflow; create one PR and verify exact CI runs. Every selected timing leg fails closed on incomplete evidence or its configured performance limit.
/release	[--dry-run] [--skip-approve|-s] [--bump major|minor|patch] [--repo OWNER/REPO]
Operator-run release cut (model cannot auto-invoke): gather merged PRs, create a version candidate, merge it through the normal queue, create and tag a runtime projection commit whose first parent is the merged main commit, validate the complete attested asset set on a draft GitHub Release, publish it as an immutable release, verify it, promote it to Latest, then run /upgrade-larch.

Non-skill entrypoints

Name	Arguments
scripts/larch.sh	<larch domain> <verb> [arguments...]
Verify and install the exact release-matched Rust executable when needed, then replace the shim process with it. Local --plugin-dir checkouts require an explicit LARCH_BINARY.
scripts/larch.sh checks run-relevant	--site <site> [--tmpdir DIR] [--repo-root DIR] [--allow-skip]
Consumer-provided validation entrypoint (not a SlashCommand skill). Orchestrators call it through scripts/larch.sh checks run-relevant --site <site> --tmpdir <tmpdir>. Not part of the plugin surface; each consuming repo provides its own executable script.
scripts/larch.sh checks rust-clippy	--repo-root DIR (--changed-from-git | PATH...)
Bounded local Rust selector: maps changed paths to the smallest safe default-feature Clippy package or target set. It is used by the local pre-commit hook and make rust-check; CI owns exhaustive Rust checks.
scripts/larch.sh issue migration-audit	--repo owner/name --chief N [--output FILE] [--table-output stderr|stdout|none]
Read-only aggregate for migration plans, blockers, owners, leases, command migration, clean-install coverage, and production runtime escape hatches. Emits stable JSON plus an optional count table.

See docs/skills.md for full details on each skill.

Aliases

Shortcut skills shipped with the plugin. Each alias forwards to an existing skill with preset flags.

Alias	Equivalent
/im	/implement --merge (same public flags as /implement; requires positional <issue-N>)
/f	/implement --force --self-review --self-implement (same public flags as /implement; requires positional <issue-N>)
/fm	/implement --force --self-review --self-implement --merge (same as /f --merge; requires positional <issue-N>)