Stephenson-Software/gardener

gardener is a safety-gated Python CLI that dispatches Claude Code against
a fleet of software repos, in two distinct ways:
- **align** checks one target repo at a time against a **conventions
repo you supply** — your own engineering conventions and alignment
checklists, in a git repo gardener only ever reads — and, if authorized,
fixes what's missing.
- **tend**/**garden**/**overnight** make real, broader progress on a
repo (or a whole opt-in list of them, unattended overnight) by
dispatching *that repo's own* -dev-loop Claude Code skill —
triage, implement, test, PR — never merging without an explicit,
separate per-repo opt-in. Those skills are generated by
create-dev-loop,
gardener's open-source companion project; tend bootstraps one
automatically if the target repo doesn't have one yet.
gardener's own job is orchestration and safety-gating, in plain Python. The
actual reading/analysis/implementation judgment is delegated to a
dispatched, safety-gated claude CLI invocation in every mode — gardener
never itself decides what "aligned" means or what a fix should look like;
it only decides *how much a dispatched Claude run is allowed to do about
it*. See Usage below for the full command set.
Description
- **gardener align --repo **: clones the target repo
read-only, clones (or refreshes) a local cache of your
conventions repo (the source of truth for what
"aligned" means — gardener is only the tool that consumes it), builds a
prompt combining that repo's ALIGNMENT_PROMPT.md with the target
repo's identity and the requested mode's constraints, and dispatches one
headless claude -p run to produce a gap checklist — or, if explicitly
authorized, to act on it.
- **gardener tend --repo **: dispatches the target repo's
*own* -dev-loop skill instead — real triage/implement/test/PR
work, not a conventions gap-check. See
gardener tend
in the usage docs.
- **gardener garden** + **gardener overnight**: an opt-in list of repos
and the unattended batch dispatcher that tends them one after another
overnight. See docs/OVERNIGHT.md.
- **gardener dashboard**: a local, read-only web UI over gardener
status's own run history plus every tend/overnight log still being
written to, so an unattended overnight run doesn't require polling the
CLI by hand to see what it's doing; /live shows what each concurrent
slot is doing right now and how close the run is to its usage limit. See
docs/DASHBOARD.md.
- **gardener hub** (optional): one run history across every device that
runs gardener. Devices still write locally first and push a copy, so a
hub that is down costs nothing but delay. The hub serves the normal
dashboard over the combined history, behind basic auth and/or UserAuth
sign-in. See docs/HUB.md.
- **gardener doctor**: a read-only pre-flight check over gardener's own
local state — the CLIs it shells out to, the state directory, every
cache clone's refresh-readiness, and whether each garden/allow-list
entry still resolves to itself on GitHub. Every check comes from a
failure that really did consume a garden slot on a real overnight run
(a clone left dirty by a killed dev-loop run fails tend every night
afterward; a renamed target repo fails in a way that looks fixed for
exactly one run after you clear the cache). It reports findings and the
exact command to fix each, and repairs nothing itself. Exits 1 on any
error, so it works as a gate before the nightly run. See
gardener doctor.
- **Agent harnesses**: Claude Code (claude -p) is the default agent.
GARDENER_HARNESS=command hands the same jobs to any program you
name instead, such as a local-model runtime like Orket on hardware that
can serve a capable model. Report mode works out of the box; write modes
need an explicit opt-in, because gardener can't enforce its tool scoping
on a program it doesn't control. See docs/HARNESSES.md.
- **gardener update**: fast-forwards gardener's own checkout to origin
— gardener overnight does this automatically before each run (opt out
with --no-self-update), so a box running it unattended stays current
without anyone needing to notice new commits and git pull by hand. See