OpenCharly — umbrella

One clone of the whole org — and the place all charly development happens. opencharly/opencharly is an org-level umbrella repo: every OpenCharly repo (409 today) is pinned here as a git submodule ("gitlink", in the org's vocabulary), flat at the root — submodule path == repo name for all but one alias (.github, pinned at the dotgithub/ path).

It is two things at once. It is a view of the org: one checkout in which every repo sits at the exact commit the rest of the org builds against. And it is the working root for the product — charly development happens here, in per-session worktrees, and lands through the org's PR-only chain. charly remains the product repo and the single source of truth; this umbrella is where you work on it.

Product docs: charly's README · opencharly.ai.

git clone https://github.com/opencharly/opencharly.git
cd opencharly
bash scripts/init-submodules.sh        # materialize the working set (needs only git + python3)
./charly/scripts/bootstrap-charly.sh   # builds charly/bin/charly — once per clone
export PATH="$PWD/charly/bin:$PATH"    # from here on this page reads `charly …`
charly task hooks                      # installs this clone's pre-commit gate

The umbrella has two non-charly entrypoints, and both have to be: the build that produces the charly binary cannot itself be a charly task, and neither can the materialization — the working set includes charly itself, so the binary does not exist yet when the first clone happens. scripts/init-submodules.sh materializes the working set, and charly/scripts/bootstrap-charly.sh builds the binary from the charly checkout it materialized; the initializer needs git and python3, and it checks both and names a missing one. Every command after the bootstrap is the installed-binary form — charly task …, exactly as on a host that installed a package. charly task init is that binary form of the same materialization: it runs the same script, so it carries the same two requirements. Without the export, the same commands run as ./charly/bin/charly task …; both forms are the same binary.

The umbrella is a view over the org, not a 9.5 GB checkout (measured 2026-10-22). It pins every OpenCharly repo as gitlinks, and the pins live in the umbrella's index — every pin is audited from the index, so a checkout is only needed for the repos you actually build against or edit. scripts/init-submodules.sh materializes a working set — the repos the project loads from, the pin contract's own repos, the harness corpus root, and the repos the umbrella's own gate scripts read — and leaves the rest as index entries:

Every figure in the table was measured on this machine on 2026-10-22; the bands carry the readings taken on 2026-10-27 as well.

Those sizes are the clone; the bootstrap builds the binary and leaves its build cache in the tree, so a bootstrapped light tree measures 129–129 M, against the 9.5 G a full checkout occupied on 2026-10-22. Sizes are du -sh at whole-unit granularity, and the packs move with the upstream repos, so the two shapes the runs repeated carry a band — the range the runs produced — rather than a number that stays put: the light clone measured between 77 M and 77 M, and the --all shape between 1.9 G and 2.2 G. The --recurse-submodules row is the baseline this replaces: one measurement, of a full checkout; it tracks the upstream mirrors, so it moves as they do. The --all shape's band is the openclaw mirror's module store — 480–520 M in a from-scratch clone, and more in a tree whose store was reused across runs, which holds more of that mirror's history and grows as the mirror does.

The bands are re-derived, not remembered. scripts/measure-clone.sh measures the shapes above from fresh clones of the tree under test and prints every reading; scripts/check-readme-measurements.mjs reads the bands this table commits, asserts that the prose agrees with the table, and — handed that script's log — asserts that every reading falls inside its band. The second is a step of charly task verify and of the pre-commit hook, so a figure the prose and the table disagree about is a failed gate rather than a sentence nobody notices.

A reading is a property of the TREE, not of the machine. The measurement clones the superproject over the transport, on the one branch that holds the tree under test: a local clone copies the source's entire object store — every commit on every branch, including other sessions' pushed branches — so a reading made that way drifts with the org's push traffic while the tree stands still. The gate fails on a measurement that clones the tree locally, and its self-test mutates the measurement's own clone invocation to prove the assertion can fail.

The samples half needs the run's own log, so it is a manual step after a measurement: the two automatic steps above run the comparison without --samples, and a reading nobody measured is a reading no gate can see.

bash scripts/measure-clone.sh > /tmp/measure.log
node scripts/check-readme-measurements.mjs --samples /tmp/measure.log

So a band a reading has outgrown is a failed check against the run that produced the reading — the run stamps the day it was taken (MEASURED=), and the comparison holds that day to the span this table states.

The last of those four sources is what keeps the light tree honest. The umbrella's gate scripts compare surfaces that live in submodules — the committed rulebook in action-review/charly.yml and the coordination shell in marketplace/scripts/coord.sh — and a gate skips a comparison whose surface is not checked out, so it still exits 0. Measured on a light clone, 2026-10-22: charly task verify reported 26/26 steps passed while six cross-repo comparisons never ran. The working set therefore includes the repos the gates read, so a light tree's gate covers what the full tree's covers — and the light tree now reports every step passed, none skipped, the same as the full tree.

The wall clocks are samples of repeated runs of the same step, measured from a fresh clone, so the two shapes the runs repeated carry the band the runs actually produced across this branch — rather than a single number: the light row's fresh clones measured between 14 s and 15 s — the whole of it is the network fetch of the working set's blobless clones — and the --all row's from-scratch materializations measured between 5 m 44 s and 6 m 43 s. The --recurse-submodules row is stated coarsely, as minutes: that shape was measured once, and its time is the mirrors' fetch. The --all row is the maintenance shape: it clones every declared path in parallel and then checks them out one at a time, and its time is dominated by the vendored upstream mirrors — openclaw alone, whose history measured 7.6 GB on 2026-10-22, is the largest of them, and a blobless fetch still brings down every commit and tree it holds.

scripts/init-submodules.sh clones blobless (--filter=blob:none): every commit and every tree are present, so "is this pin an ancestor of the remote's tip?" stays answerable, while the blobs of history are never fetched. --depth 1 is deliberately not used — a shallow clone cannot answer that question, so a healthy pin reads as divergent. The filter has to be an explicit flag: a filter = key in .gitmodules is not honoured by git submodule update.

charly task init is the same operation through the binary. The mode is chosen by the environment, not by a task parameter:

charly task init                                 # the working set
CHARLY_INIT_MODE=all charly task init            # every declared path
CHARLY_INIT_MODE=list charly task init --output  # print the set, change nothing
CHARLY_INIT_PATHS=a,b charly task init           # the named repos

--output is what makes the task's own output visible: the task runner prints its report on stderr and the step's output on stdout only in that mode.

The environment is the only channel that carries an operator's value as data: an upper-case task parameter's value is substituted into the command's text, and the shell then parses that text, so a parameter carrying a shell metacharacter would execute (measured: a parameter of $(touch /tmp/marker) created the marker). A lower-case parameter is not substituted at all — the expander's grammar is upper-case-initial — so it reaches the shell, finds no such variable, and its empty word vanishes. An environment value reaches the shell as a parameter-expansion result, which is never re-parsed — and an unknown mode is reported as a value, not run:

$ CHARLY_INIT_MODE='all; touch /tmp/pwned' charly task init
  [fail] run — materialize the umbrella's submodules
      exit=2, want 0 (stderr: FAIL: CHARLY_INIT_MODE must be working-set, all or list (got 'all; touch /tmp/pwned'))

The same law governs the manifest's own command steps: a braced reference in a command: step's text is claimed by the plan runner and expanded against the task's merged environment, and one it cannot resolve does not fail the step — it skips it, so the gate reads green over a check that never ran. A command step's text therefore carries no value at all: read the environment at run time, so the runner never sees it — with a bare $NAME, or, under set -eu, through $(printenv NAME 2>/dev/null || true) so an unset variable cannot abort the step before it runs. node scripts/check-task-command-vars.mjs holds that line, in the pre-commit gate and in charly task verify.

All submodule URLs are plain HTTPS, so forks work without extra configuration: every gitlink resolves to its opencharly/<repo> upstream over HTTPS, no credentials needed for a read-only checkout.

Then the one rule that keeps the checkout honest: never edit a submodule in place. Every repo you change gets its own worktree at .worktrees/<slug>/<repo>/, branched off a fresh origin/main, so the submodule's tracked checkout stays detached and clean at its recorded gitlink. Change lands only by pull request. The full model — worktrees, the pin contract — its intent model, the producer-first landing order, after-merge cleanup — is in AGENTS.md under The development model.

AGENTS.md is the one rulebook, and it is harness-neutral: every agent harness reads that same file directly, so no second copy exists to drift. Harness configuration now lives at this umbrella root and only here — a plain move-in of every harness's settings and workflows (Claude Code, Codex, opencode, pi, Kimi/reasonix, DSH), with no mirror and no parity gate. Skills live in neither: they come from the opencharly/marketplace corpus, which each harness resolves per its own conventions.

Every change lands the same way: a feat/ branch, a PR validated by charly/pr-validator, then native auto-merge — and tag-on-merge writes the CHANGELOG entry and the CalVer tag.

Build the binary once per clone and put it on PATH (both in Start developing above), then run the umbrella's own maintenance from the umbrella root. Every command below is the installed-binary form — charly task …, the same shape a packaged charly gives you:

charly task list enumerates them. Without the PATH export, the same commands run as ./charly/bin/charly task ….

Every submodule is listed below, grouped by category and alphabetically ordered within each table. The pinning policy in the next section says how each pin is kept current.

Two repos are deliberately not listed as their own-name submodules:

• opencharly/opencharly itself — the umbrella cannot pin itself; it is this repo.
• opencharly/.github — the org-wide community-health defaults and the reusable validation/merge workflows every repo inherits. It is pinned at the dotgithub/ path (submodule path != repo name), so this repo's own .github/workflows/ stays free for its CI dispatchers.

heroic-heroic is archived and intentionally not a submodule.

Each class has ONE placement rule, and the class prefix in the repo name states it:

• Core & contract — bare names (charly, sdk, spec, marketplace, docs): the product, the wire/IR contract, the generated corpus, the site.
• Distro image families — distro-<distro>: the base and builder, distro-exclusive OS layers, that distro's VMs and beds.
• Package repositories — charly-<distro> for the published repo and pkg-<distro> for package source: packaging plus its publishing bed.
• Candy layers — layer-<name>: ONE candy with its files beside it. A family's skill: entities live beside the code, plugin, or config they describe (AGENTS.md Part II #5), never in a repo that holds nothing else: a repo whose only content is skills is not a class.
• Product families — layer-<family>: a family's box(es), candy, VM, beds and skills (layer-agentteams is the canonical example; layer-openclaw follows it).
• Plugins — plugin-<word>: the provider candy, its Go module and its CUE schema.
• Pods / service bundles — pod-<name>: a candy with service: plus its skill.
• VMs — vm-<family>: kind: vm definitions plus VM skills.
• Product & tooling — bare or product-specific: appliances, CI action config, vendored upstreams.

The rule these placements follow — what may be bare, and why a product family is a layer-<family> repo — is stated once in AGENTS.md ("Repo classes and naming"); the lines above only place each class. The authoring procedure is /charly-internals:repo-setup, and charly task org-map verifies the tables below against the repo and .gitmodules.

6 repos — the product and the contracts it consumes.

6 repos — each maps to a box/<distro> inside charly; their pins follow charly's own gitlinks (the pin contract's edge).

10 repos — native package repos for supported distros.

13 repos — streamer product, appliance provisioning, org action, third-party pins, and the six vendored OpenClaw upstream forks.

4 repos — vendored pi agent packages and extensions (the OpenCharly pi-plugin forks and mirrors).

2 repos — the charly meta/skill candy layers.

13 repos — the omarchy desktop image composition layers.

2 repos — the omarchy PR evaluation beds and their run artifacts.

15 repos — check-bed and plugin fixture layers.

144 repos.

120 repos — charly plugin candies. Their providers: blocks register the kinds, deploys, verbs, steps, builds, builders, commands, engines, loaders, refs, agent runtimes and terminals charly speaks.

72 repos — pod/deployment bundles.

2 repos.

Every submodule is pinned to a specific commit (a gitlink), and currency answers whether the whole org is a single coherent snapshot:

• charly tracks its own default branch — the pin is the main commit the last sync recorded.
• every distro-* follows exactly the commit charly's own gitlinks pin (charly's box/<distro> ↔ this repo's distro-<distro>), so the umbrella means "the org exactly as charly sees it".
• sdk and spec are pinned the same way, at their own default branch's HEAD.
• every other repo follows its own default-branch HEAD.

This umbrella's .gitmodules records branch = <repo default> on all of its entries, so a future default-branch rename keeps working. The pins are advanced with charly task sync (the pin-contract bump — it advances EVERY pin this repo declares), run by hand and landed through the org's PR-only validation chain, which opens a PR and never pushes to the default branch. There is no scheduled workflow; charly task sync is the one path that moves a pin.

A pin is a gitlink — the recorded commit, checked out detached and clean — and charly task verify asserts exactly that. A dangling pin is a failure.

The pins move only through the pin contract, and three different questions have three different answers. Ask the right one:

verify being green does not mean the org is current: a tree can be perfectly consistent while every pin is behind what its repo serves. So the gate names the pins that are not current — currency asks that other question, and when a pin waits on its source it names the producer leg instead of leaving you to discover it an hour later. A pin that is behind is an advance available NOW, in its producer's own repo, so the gate reports it and stays green; only a pin the workflow cannot judge, or two sides that disagree, fails it.

The sanctioned catch-up is one sequence, and it is the only one that moves a pin:

charly task sync                        # the pin-contract bump — it advances EVERY pin this repo declares, in the index; it commits nothing
charly task init                        # materialize the paths the wave advanced, AT their new pins
charly task verify                      # judge the tree against the pins it records
# …then land the pin wave as a PR through the org's validation chain

On a tree that was never materialized, the materialization comes first — the project cannot load before its import: paths exist, so the wave's own first verb would not run. bash scripts/init-submodules.sh is that step (see Start developing); the sequence above follows it unchanged.

A wave needs no full set: the bump advances a path with no checkout in the index — a leaf to the tip its remote serves for its branch=, an edge to the twin the source's tree records — and a path with a checkout is still rolled in that checkout, so the two keep agreeing. It still fails loud for every path it cannot advance: a sync over a tree it could not fully advance must never report success. That is why the order is sync → init → verify — the sync writes the pins, the init materializes the checkouts at those pins, and the verify judges them. The daily tree stays light, and so does a wave. A repo you merely want to work on is one CHARLY_INIT_PATHS=<repo> charly task init away.

Never catch up by hand. A pin is advanced by charly task sync and lands as a PR. It is never hand-edited in the index, never re-pointed at a branch tip, and never "fixed" by checking out a newer commit inside the submodule: the pin is the index entry, and the checkout follows it.

MIT — see LICENSE. Each submodule is governed by its own repository's license.