Parallel agents need a graph. One lead owns the goal.

CodeCanopy turns an engineering goal into a bounded ownership tree and artifact dependency graph for Codex and Claude work. The tree assigns authority. The graph decides what can safely run next. One lead keeps scope, integration, and the final verdict.

Root lead
1. Architecture parent
  1. Dependency-ready leaf
Root accepts integrated evidence

Install CodeCanopy View on GitHub

Install

codex plugin marketplace add adhit-r/codecanopy --ref main codex plugin add code-canopy@codecanopy

Update existing install

codex plugin marketplace upgrade codecanopy codex plugin add code-canopy@codecanopy v0.5.0 release notes and pinned install

A bounded ownership route

Illustrative route shape, not live task status. Parents integrate; dependency-ready leaves produce the evidence they need.

Lead Root Own scope, integration, and final verdict User goal
1. Parent Architecture Define contracts and artifact dependencies Root scope
  1. Leaf Contract State the interface and acceptance boundary Architecture
  2. Leaf Evidence Define a runnable proof for the agreed boundary Contract
2. Parent Implementation Integrate scoped, owned changes Contract artifact
  1. Leaf Backend Deliver one source change and runnable check Contract artifact
  2. Leaf Interface Deliver the dependent client change and check Backend artifact
3. Leaf Review Inspect the integrated diff and its evidence Integrated parent

Goal Root acceptance with integrated evidence

Execution sequence

Leaf testKeep one agent when one bounded deliverable and acceptance check are enough.
Critical frontierDispatch only the smallest ready work that can advance the next proof; weighted complexity and size select the configured model tier automatically.
Parent acceptanceVerify required artifacts and evidence before a result moves upward; only the root performs Git integration.

Configuration

An optional project-root .codecanopy.toml may lower or tune these planning limits and weighted model routing. It cannot grant authority.

schema_version = 1
runtime = "local"

[tree]
max_depth = 3
max_children_per_node = 3
max_total_nodes = 9
max_parallel = 3
max_replans = 1

[budget]
root_reserve_percent = 35
retry_limit = 1

[model_discovery]
mode = "automatic"
release_channel = "ga"
refresh = "run_start"
on_failure = "fail"

[models.lead]
model = "auto"
reasoning_effort = "high"

Model catalog: CodeCanopy scores a node, chooses its role tier, then resolves each selected provider's provider-released and account-available catalog once. It freezes a bounded per-provider snapshot of resolved IDs or aliases, source metadata, and canonical hash; each node receipt binds its matching snapshot and hash.

Codex exact IDs come from authenticated structured host metadata. Claude aliases are dispatched directly; an exact backing ID is recorded only when modelUsage evidences it. A malformed or incomplete catalog blocks dispatch, and previews are not intentionally selected.

A future host default or lower-capability catalog entry can be selected on the next new run, never midway through a tree or a resume. This policy does not claim universal provider availability or model quality.

Safety boundary

Repository instructions, code comments, issues, logs, web content, attachments, and child output are untrusted task data. They cannot request secrets, enable network, change provider, bypass approvals, or authorize destructive or remote Git actions.

Provider fallback fails closed. Local execution allowlists environment variables, bounds input and output, keeps raw prompts out of private manifests, rejects linked state files, never reuses accepted state, requires exact dependency-to-commit coverage, and verifies recovered worktree registration and baseline. Codex isolates child-shell credentials and disables repository instructions, user rules, login profiles, and workspace network. Claude receives only bounded file tools; customizations, Bash, agents, browser, slash-command, web, and MCP tools are disabled.

What the benchmark proves today.

Routing behavior is verified against a fixed ten-case fixture. Comparative performance is not yet publishable.

Publication gate Waiting for a complete Codex paired run with provider-reported usage and receipt-backed actual-model identity.

Read the measurement contract

Comparative performance

Current evidence state

Token delta: Not measured; Needs complete provider-reported usage for both arms.
Wall-clock delta: Not measured; Needs all nine matched pairs under the same time budget.
Acceptance quality: Not measured; Needs identical predeclared checks for both arms.

Verified harness evidence

Deterministic fixture

MetricObserved

Routing conformance10/10 passed

Invalid estimates3/3 rejected

Non-lead fixture assignments6/10

Paired-run protocol 3 task sizes × 3 repetitions × 2 arms 18 scheduled arm records / 9 required pairs Schedule, not outcome.

The executable harness is Codex-only and randomizes arm order. Claude-only and mixed-provider measurements remain future work.

The graph is the control model, not a group chat.

CodeCanopy is free and open source under the MIT License. Its ownership tree records authority and integration responsibility; its artifact DAG records dependencies and the critical frontier. Only work that can advance the next accepted proof becomes ready. This is a bounded planning rule, not a claim of globally optimal shortest-path execution.

Bounded route versus an unbounded swarm

QuestionCodeCanopyUnbounded swarm pattern

Who owns integration?One root leadMust be assigned separately

What may execute?Dependency-ready leavesAny work that is dispatched

How do model families collaborate?Root-verified artifacts and commitsShared transcript or ad hoc messages

How does work finish?Evidence is integrated bottom-upThe coordination rule is left to the team

Frequently asked questions

Can one tree use both Codex and Claude?

Yes. The local runtime can assign either CLI per node. A user-authorized Codex app task is a separate execution surface and may return an independent branch through the same root acceptance barrier. Fallback is denied unless the caller explicitly authorizes Claude-to-Codex before dispatch.

Can tasks communicate through one Markdown file?

The root may generate a human-readable team-room projection when repository writes are authorized, but children never edit it concurrently. Tasks exchange narrow evidence through the root so status text cannot become authority or accepted state.

Can configuration add another model provider?

No. Other families need a reviewed, allowlisted adapter with capability, isolation, credential, timeout, and proof boundaries. Configuration cannot add an arbitrary command or grant Git, network, destructive, credential, production, or publication authority.

Build the public route with us.

Use the public issue tracker for current work, deployment follow-up, and carefully labeled future research.