Quick start
Waggle lets many keepers (humans who own work on a repo) and their agent teams share one repo without colliding. Its first usable piece is the gate, a GitHub merge check for repos where AI agents write code; Nectar, Quorum and the multi-keeper parts are roadmap, not built yet. This page takes a repo from nothing to a required check in about ten minutes. Waggle is pre-1.0: the gate spec describes what the code does today, and the recipes have not been run end to end with each agent tool.
What you get
Section titled “What you get”On a repo where the check is required and PRs are required, the gate fails a PR whose commits change paths outside the claim of the task each commit names, or whose task’s claim does not name the PR’s branch. Each task gets a claim: the directories it may change and the branches its PR may come from. The gate reads the claims from git and compares them with the PR’s commits.
Before you start
Section titled “Before you start”- A GitHub repo you administer. v0.1 supports GitHub only (
waggle initrefuses any other forge). - Go, to build
wagglefrom source, or a tagged release archive (waggle_<version>_<os>_<arch>) if one exists for the version you want. - A clean clone of a pushed commit of Waggle, so the Action ref the installer writes exists on GitHub.
Install
Section titled “Install”- Build
wagglefrom a clean clone of a pushed commit, checked out at<commit-sha>:go build -o <path outside the clone>/waggle ./cmd/waggle. Build outside the clone: an untracked binary inside it makes the next build stamp a modified tree, andinit --gate-onlythen refuses. Tagged releases carrywaggle_<version>_<os>_<arch>archives and aSHA256SUMSfile; check a download against itsSHA256SUMSline. - In your repo, run
waggle init --gate-only. It writes.github/workflows/waggle-gate.yml,.waggle/control/config.yamland.waggle/hive/DECISIONS.md. - Commit those files. The install PR changes the workflow and
.waggle/, so it fails its own gate. If a rule already requires the check, it needs an admin merge. - Require the check
verify-leases-and-tiers, and PRs, on your default branch. Without both, the gate binds nothing. - Run
waggle doctor. It checks that this clone can push claim refs and that a rule requires the check with up-to-date branches. It does not check that PRs are required, required reviews, code-owner review, or which app may post the check.
The full workflow is in the gate spec. A pin is written <commit-sha>; for a release tag, read the commit with git rev-parse vX.Y.Z^{commit}.
Write a claim
Section titled “Write a claim”Before an agent starts a task, a trusted coordinator writes its claim, never the agent doing the work. In a hive (the repo’s shared Waggle setup) that is your queen, the coordinating agent you talk to as keeper. Today she writes the claim when she dispatches a forager or builder (worker agents); turning your conversation into GitHub issues is coming soon. Without a queen, you or your orchestrator run the command:
waggle claim T-123 --dirs internal/parser,docs --gate light --owner <your GitHub login> --branch t-123Then the agent works on branch t-123 and names the task in every commit subject, T-123: fix the tokenizer. Open the PR. The gate runs verify-leases-and-tiers:
- a commit that touches
cmd/main.gofails withpath is outside the claim directories, becausecmdis not in the lease; - a PR from branch
fix-parserfails withclaim does not name this pull request's branch, because the claim lists onlyt-123.
When the PR merges, give the claim back: waggle release T-123 (after a squash or rebase merge, waggle release T-123 --unmerged). See Claims and leases for every rule.
What it does not do
Section titled “What it does not do”The gate does not schedule or run agents and is not a sandbox. Its limits are written down in the gate spec. The two to know on day one:
- The required check can be forged. A workflow or a token with the right permissions can post a passing check of the same name. Bind the check to GitHub Actions, give agents credentials limited to Contents and Pull requests, and require a person’s approval. None of these is complete alone.
- It binds only on PRs. A merge that skips PRs skips the gate, and an admin bypass merges without it.
- The gate: what each check does, with the code that does it
- Claims and leases
- Configuration and CLI reference
- Recipes for Claude Code agent teams and the Copilot cloud agent