A carrot on a stick for your coding agent. Write plans during the day, and dangle works through them overnight: each plan gets its own git worktree, your agent implements it, your gate checks it, and only what passes lands.
o
\
\_______________________
|
|
? 1. You write plans. dangle holds out the stick.
[========o.....................) 4/12 2. Overnight, the agent chases plan after plan.
\|/
\\|//
.-'-.
| |
| | 10 landed 3. The gate passes, the plan lands: carrot.
\ /
V
It is one POSIX shell script. It needs git and an agent CLI, and it works with any language,
any agent (Claude Code by default,
Codex, opencode,
pi, or your own command) and any way of landing
(straight onto a branch, or through pull requests and CI).
Made for superpowers. Superpowers' brainstorming and
writing-plans skills write plans to docs/superpowers/plans/, which is where dangle looks
first. Use a strong model during the day to brainstorm and write the plans, then let dangle
run them overnight. It also works with plans from anywhere else: they are just Markdown files.
mise use -g github:bendangelo/dangle@latest
# (plain `github:bendangelo/dangle` works too, once a release is a day old: mise's
# minimum_release_age)
# or
curl -fsSL https://raw.githubusercontent.com/bendangelo/dangle/main/install.sh | shOr copy bin/dangle anywhere on your PATH.
cd your-repo
dangle init # writes .dangle/ with a gate for your language; read it
dangle skill # teaches your agents how to write plans for dangle
dangle doctor --agent # checks the setup and that the agent and fix agent answer
dangle --dry-run # what would run
dangle # run itA plan is a Markdown file in the plans folder (docs/superpowers/plans, docs/plans or
plans, or PLANS= in the config). Every *.md directly in it is active; subfolders are
inactive (done/ holds landed plans, hold/ parks one). dangle runs the first plan, in
filename order, whose dependencies have landed, and again until none is left: filename order,
except that a plan never runs before what it depends= on.
# Payroll: employee master file
<!-- dangle: depends=863,864 agent=claude:sonnet -->
Goal, files, steps, tests...
Done when: `cargo test payroll_employee`- The id is the plan's number:
2026-10-14-865-name.mdand865-name.mdare both865. A plan without a number goes by its name after the date, and its first words work too:shop-A1names2026-10-12-shop-A1-report-links.md(nevershop-A10-…), on the command line and independs=. dangle add <short-name> "<title>"makes the next plan file and prints its path: the number is one past the highest anywhere (every folder, the base branch, the remote's base branch), taken under a lock and the file created at once, so two agents writing plans at the same time never take the same number. A date prefix is added when the repository's plans use one.dangle lintfails on an active plan whose id another active or landed plan has, and warns when a parked one has it.depends=holds a plan back until those plans have landed (a dependency that fails holds it for the night).agent=picks the agent for it.Done when:is a command dangle runs after the gate; the plan lands only when it passes.- Private plans: if git ignores the plans folder (a public repository whose plans stay
out of it), dangle copies the plans into each worktree, never commits them, and moves a
landed plan to
done/on disk. - Keep plans small: one goal, one session, a few hundred lines at most (
dangle lintwarns). The skill fromdangle skilltells your agents all of this, and how to tidy a repository's existing plans into this shape.
dangle # every active plan, in order
dangle 865 870 # only these, in this order, then stop
dangle 865 --rest # 865 first, then everything else
dangle -a claude:haiku # pick the agent for this run
dangle -a opus # the default agent with another model
dangle status # ready, waiting, running, kept, on-<base>, submitted
dangle 866 # continue a failed plan in its kept worktree (--fresh: start over)
dangle --watch # never run out: wait for new plans when the queue is emptyA run of every active plan (no ids, or --rest) looks at the plans folder again before each
plan: a plan you write and commit while dangle runs is picked up and joins the end of the
queue (still never before what it depends= on). An uncommitted plan waits until you commit
it; a private plan, until it has not changed for a minute. With --watch, an empty queue, or
one blocked by a failed plan, waits for more (every DANGLE_POLL seconds, default 30) instead
of ending the run; Ctrl-C ends it and writes the summary.
Before it starts, dangle estimates how long the run will take from how long recent plan cycles took (agent, checks and landing); until it has history it assumes 30m–1h per plan:
estimate ~1h-2h for 2 plan(s) (30m-1h each, from 4 past plans)
While an agent or the gate runs, a line every 5 minutes says how long it has run and what it
printed last (HEARTBEAT=5m, 0 turns it off):
865 Payroll: employee master file
agent pi:ollama-local/qwen3.8:latest (log .git/dangle/logs/865.log)
... agent 5m │ Compiling operations v0.1.0
... agent 10m │ test payroll::employees::tests::creates ... ok
gate running (log .git/dangle/logs/865.gate.log)
... gate 5m │ gate: test passed in 115.7s
land 3e25cb7 on dev (pushed to origin)
For each plan dangle creates the worktree .worktrees/plan-<id> from the base branch, runs
the agent, commits anything it left uncommitted, merges the base branch in, moves the plan to
done/ in the branch, and runs the gate. A failed gate gets one fix-up run of the agent
(FIXES=) with the gate's output: FIX_AGENT= (or --fix-agent) can name a stronger agent
for the fix-up, and defaults to the plan's agent. Then, under a lock, it lands: squashes the
branch onto the base branch and pushes it. A plan that fails keeps its worktree for you to
look at.
A merge of the base branch that conflicts does not end the plan. Where both sides only added
lines at the same place (two plans adding to one list, match or doc section), dangle keeps
both, the base's lines first, and the gate checks the result (unless the base also added one of
the branch's lines to that file, which would list it twice). Any other conflict goes to the fix
agent (FIX_AGENT=, or --fix-agent; default the plan's agent) with merge-prompt.md, out of
its own budget, MERGE_FIXES= (default FIXES): a merge that takes an hour cannot spend the
gate's fix-ups, or the other way round. A resolution counts only when the merge is committed
with no conflict marker left, and is undone otherwise, saying why.
A conflict on a file with no text in it (a recorded screenshot baseline, an image, an archive),
or on a text file .gitattributes marks dangle-rerecord (a list of baseline hashes, where
neither side's line is the merged tree's: apps/snapshots.toml dangle-rerecord), goes to no agent, because the fix is to take one side and record the file again, not to read it.
With a .dangle/hooks/rerecord, dangle does that itself: it takes the base's side of each such
file, finishes the merge (any text conflicts go to the agent as usual), runs the hook in the
worktree with the files on stdin, one per line, and commits what it wrote; the gate then checks
the result. The hook's output is in .git/dangle/logs/<id>.rerecord.log, and a hook that fails
undoes the merge, saying so. Without the hook the landing is handed back with the files named.
When a merge does go to the agent, the files it cannot read are named in the prompt too, with
that instruction.
If the base branch lands while the agent works, the resolution is kept and the newer base is
taken in before the landing goes on (MERGE_ROUNDS= rounds at most): one landing, one
resolution, instead of the base moving again right after the merge. A conflict found while
landing lets go of the lock first, so no other landing waits on the agent, and the gate runs
again before the branch lands. dangle land by hand settles the added-lines kind too and leaves
any other conflict for you. Every landing keeps its own log, .git/dangle/logs/<id>.landing.log:
the base it merged, and why it stopped.
By default a run works on one plan at a time. That keeps everything simple: one agent, one build, one gate on the machine; a plan always starts from a base branch that already has the plans before it; and nothing ever needs to merge two agents' work at once.
When the machine has room for more, open another terminal in the same repository and start
another dangle. Runners in one repository share the work safely:
- each plan is claimed by the runner that starts it, and the others pass over it: when it lands they drop it from their count, when it fails there they leave it, and when that runner dies they take it over;
- a plan that depends on one another runner is working on waits for it to land, then runs;
- landings take turns (one lock), and each landing merges in what the others landed first.
dangle # terminal 1: the night's run
dangle # terminal 2: a second runner on the same queue
dangle 866 # or: just this one plan, beside the main runClaims live in .git/dangle/, so they are per clone: runners on two computers do not see each
other's claims. Either give each computer its own ids (dangle 864 865 on one, dangle 872 873
on the other), or set REMOTE_CLAIMS=1: each claim is then also the ref
refs/dangle/claims/<id> on the remote, a commit of its own naming the computer. Of two
computers that claim one plan, git takes only the first push (the second is not a fast-forward),
and the other runner passes the plan over (dangle status says running and on <computer>).
The ref goes when the plan lands or fails. A claim older than CLAIM_TTL (12h), or one this
computer left behind when its run died, is stale and taken over. An unreachable remote never
stops a plan: the local claim still holds.
A plan's landing (the gate, a fix-up, a wait in the merge queue) runs in the same process as the run, so a runner starts its next plan only once the last has landed. Nothing lands behind the runner's back: its output is the run's output, its result is the run's result, and when the run stops, so does the landing.
A plan whose agent never got to work is NOT RUN, not FAILED: the agent's session made no
tool call and no commit, and it either printed a provider error (error: 429 …, API Error: 529 …, a finalError or is_error in its event stream: overloaded, rate limit, out of
credit, signed out, network) or exited with an error within a minute (a bad flag). A provider
error is tried again after each RETRY_WAIT (default 5m 15m; 0 = never). A plan still
not run keeps its place in the queue (its empty worktree goes), the line in the summary
quotes the error, and the night stops: the next plan would meet the same outage. So FAILED
means the plan or the work; NOT RUN means the provider or the agent's setup.
The night also stops when the agent fails fast twice in a row, and says why the last one
failed, instead of failing every plan in minutes. The computer is kept awake
(systemd-inhibit or caffeinate). The summary is in .git/dangle/last-run.md, and the
logs are in .git/dangle/logs/: <id>.log (the agent), <id>.gate.log and
<id>.landing.log (what each landing merged, and why it stopped).
A repository's plans folder often falls behind its code: some plans were carried out by hand,
or by an earlier runner, and never moved. Running them again wastes a night. dangle audit
asks the agent about each active plan in a throwaway checkout (it changes nothing):
dangle audit -a claude:sonnet # a strong model is worth it for this
cat .git/dangle/audit.md # done / partial <what is missing> / todo, per plan
dangle audit --apply # moves the ones found done to done/, in one commitCheck the plans it calls done before --apply. A plan it calls partial is worth a short
"Corrections" section at the top saying what is already there; the skill from dangle skill
walks an agent through all of this.
One case needs no audit: a plan that failed (a conflict, a gate) whose kept worktree you then
fixed and merged into the base branch yourself, by merge, fast-forward, squash or cherry-pick.
dangle status shows it as on-<base>, and the next run retires it without an agent: the plan
moves to done/ through the usual landing, and the plans waiting for it run.
AGENT= in the config, -a for one run, or agent= in one plan. Your own default for every
repository goes in ~/.config/dangle/config (a repository's .dangle/config wins over it):
mkdir -p ~/.config/dangle
echo 'AGENT=pi:ollama-local/qwen3.8:latest' >> ~/.config/dangle/config| Spec | Runs |
|---|---|
claude (the default), claude:haiku |
claude -p --output-format stream-json --verbose --dangerously-skip-permissions [--model …] |
codex, codex:gpt-5 |
codex exec --dangerously-bypass-approvals-and-sandbox [--model …] |
opencode, opencode:anthropic/claude-sonnet-5-5 |
opencode run --auto [--model …] |
pi, pi:ollama/qwen3 |
pi -p --mode json --approve [--model …] |
opus |
the default agent with this model |
cheap |
ALIAS_cheap=claude:haiku from the config |
./scripts/my-agent |
your own command |
pi and Claude Code run in their streaming modes, and dangle turns each event into one line of
the log: → bash cargo test, → Edit src/lib.rs, or the agent's text. The raw events are
kept beside it (<id>.jsonl). That is what the heartbeat shows while an agent works.
Words after the spec are passed on (AGENT=opencode --variant high). The prompt is always the
last argument. An agent runs with DANGLE=1, DANGLE_PLAN, DANGLE_PLAN_FILE,
DANGLE_WORKTREE, DANGLE_BRANCH, DANGLE_BASE and DANGLE_MODEL set, and stdin closed.
Your own command can be a wrapper script for anything unusual (a container, a session id).
Agents run without permission prompts. That is what lets them work unattended, and it means they can run any command your user can. Run dangle in a container or VM for code you do not trust.
Each step is a short file your agents can read and change. Ask one: "make dangle copy node_modules into new worktrees" or "land through a GitHub PR and wait for CI".
| File | When | What |
|---|---|---|
config |
always | KEY=value settings (read, never run) |
copy |
new worktree | paths copied from the main checkout (copy-on-write where the disk can), or link <path> for a symlink: .env, node_modules, a warm target/ |
hooks/setup |
new worktree, after copy |
install dependencies, reserve a port, seed a database |
hooks/gate |
before every landing | your checks; exit 0 = may land |
hooks/rerecord |
a merge of the base where files with no text in them conflict | record those files (on stdin) again after the base's side is taken: screenshot baselines, generated images |
hooks/regate <old> <new> |
the base moved during a gate | exit 1 = no second gate (e.g. only docs changed) |
hooks/land |
landing, after the gate | replaces the built-in squash-and-push |
hooks/teardown |
before a worktree is removed | save a build cache for the next one |
hooks/prune <worktree> <days> |
dangle prune, and the start and end of a run |
free the disk a worktree is holding: drop build output and caches, keep what a rebuild needs (see below) |
audit-prompt.md |
dangle audit |
the audit prompt, with {{plan}} |
hooks/lint <plans> |
dangle lint |
your own plan checks (skill names exist, no forbidden commands); exit non-zero = error |
hooks/done <summary> |
end of a run | notify yourself: notify-send, ntfy, e-mail |
prompt.md, fix-prompt.md, merge-prompt.md |
each agent run | the prompts, with {{plan}}, {{branch}}, {{base}}, {{gate}}, {{gate_log}}, {{gate_tail}}, {{conflicts}}, {{binary_conflicts}} |
Hooks run with DANGLE_PRIMARY (the main checkout), DANGLE_WORKTREE, DANGLE_BRANCH,
DANGLE_BASE, and for land, DANGLE_TITLE, DANGLE_MESSAGE_FILE and DANGLE_REMOTE.
hooks/prune also gets DANGLE_PRUNE_DAYS and DANGLE_PRUNE_REASON (idle, size or
all).
Every worktree builds into its own directory, so agents never share a lock. The cost is disk:
a target/, node_modules/ or .venv/ per worktree. Two things collect it.
Finished plans are retired. After a plan has finished (landed, submitted, failed or not
run) and PRUNE_AFTER_RUNS plan cycles (default 2) have gone by without dangle using its
worktree, dangle removes the worktree: before and after a run, and after each plan, so a long
--watch session still cleans up. A branch with commits of its own stays, and dangle <id>
recreates the worktree from it and continues the plan; an empty branch, one whose work is on
the base branch, or a plan that has landed is deleted too. dangle never retires a worktree with
changes, one in use, the merge queue, or the one you are standing in. A submitted plan's
worktree goes as soon as the plan appears in the done folder on the base branch.
PRUNE_AFTER_RUNS=0 turns retirement off.
Build caches are pruned. dangle does not know which files are disposable, so the project
says so in hooks/prune:
#!/bin/sh
# .dangle/hooks/prune <worktree> <idle-days>: keep what makes a rebuild cheap, drop the rest.
cd "$DANGLE_WORKTREE" || exit 0
[ -d target ] || exit 0
cargo clean -p my-crate 2>/dev/null # or any cache your build system can regeneratedangle calls it, before and after every run, for each worktree that
- has no uncommitted changes (in tracked files), and
- was last used at least
PRUNE_DAYSdays ago (default 3), or is larger thanPRUNE_MAX_GBGB (default 0: no size cap), and - has not been pruned already: dangle remembers what the worktree held after the hook last ran, and prunes it again only once that has grown back by a tenth (or 16M, whichever is more). Without that, an old worktree stays "idle" for ever and the same build output is pruned, and reported, on every run.
It also runs in detached worktrees (the merge queue, dangle new checkouts), but never removes
them. It never touches a worktree whose plan another dangle is running, one a landing holds, the
merge queue while it gates, or the worktree you are standing in. dangle prune does the same
by hand (-n shows what it would do, --all ignores the age, the size and the memory of what
was pruned, --days and --max-gb override the config); dangle prune --rm also retires
finished plan worktrees as the run would, and removes plan worktrees that have no commits of
their own and no uncommitted files. dangle list shows each worktree's size.
A worktree the hook cannot get under the cap says so, because the hook keeps what a rebuild
needs: note @dev-full is still 45.9G after pruning (over PRUNE_MAX_GB=30; pruned again when it grows). It is pruned again when it has grown back, not on every run.
This is housekeeping, never a verdict: a failing prune hook is reported and the run goes on. The project decides the scope, and because only the worktree is pruned, a later run resumes with a slower build, never with lost source.
With several runners (or several people landing worktrees by hand), each landing runs its own
gate, side by side on one machine: N builds share the cores, so each takes N times as long, and
a landing whose base moved meanwhile may gate a second time. QUEUE=batch puts one gate on the
machine instead:
- a landing that is ready (the base merged in, the plan moved to
done/) submits its branch to the queue and waits; - whichever waiting landing finds the queue free drives it: it merges every branch waiting
into the queue worktree (
.worktrees/dangle-queue, kept between batches so its build output stays warm), runs the gate once, and lands each branch as its own squashed commit; - a batch that fails is split in half and each half gated again, down to the branch that broke it, which gets the gate log back (and its fix-ups, as without the queue); the others land;
- a branch that conflicts with one ahead of it in the batch is handed back to merge the base again, as on any landing;
dangle land --no-gatelands through the queue without the gate, in a batch of its own (a release's version bump);dangle land --nowgates and lands alone, outside the queue.
dangle queue lists the branches waiting and who drives the queue. A hooks/land turns the
queue off: the hook lands each branch its own way.
The built-in landing squashes the branch into one commit on the base branch and pushes it. A
hooks/land replaces that step; it runs in the worktree after the gate passed, holding the
land lock. examples/land/ has three:
github-pr: push, open a pull request, wait for CI withgh pr checks --watch, squash-merge.gitlab-mr: open a merge request that merges when its pipeline passes.merge-commit: a merge commit instead of a squash.
A hook that hands off without waiting (the PR merges later) leaves the plan submitted:
dangle skips it, and the plans that depend on it, until it shows up in done/ on the base
branch. A hook that waits keeps the night in order.
dangle's worktrees work for people too:
dangle new my-fix # .worktrees/my-fix, with copy + setup
cd "$(dangle path my-fix)"
dangle land # gate, squash, land, remove (--keep keeps it, --fix asks the agent;
# --fix-agent SPEC picks a stronger one for the fix-up)
dangle queue # with QUEUE=batch: the branches waiting to be gated together
dangle list # worktrees, ahead/behind, size, changes
dangle prune # run hooks/prune in the idle worktrees; -n first, --rm also retires finished ones
dangle rm my-fix # teardown, then removeLanding from inside the worktree (the usual way) empties it but leaves an empty placeholder
for the shell's working directory: a child process cannot move the shell, and deleting the
directory it stands in makes the next prompt warn (mise does). The next dangle command run
from outside removes the placeholder.
BASE=main # the branch plans land on (default: origin's HEAD, main, master)
PLANS=docs/plans # the plans folder
DONE=done # landed plans move to PLANS/DONE
AGENT=claude:sonnet # default: claude
FIX_AGENT=claude:opus # fix-ups after a failed gate or merge conflict (default: AGENT)
FIXES=1 # fix-up runs after a failed gate
MERGE_FIXES=1 # fix-up runs to resolve a merge of the base branch (default: FIXES)
MERGE_ROUNDS=3 # a landing takes a base that moved while resolving in, at most this often
AGENT_TIMEOUT=4h
STALL_TIMEOUT=60m # stop an agent with no new commit or edit for this long; 0 = never
RETRY_WAIT=5m 15m # waits before trying a plan again after a provider error; 0 = never
GATE_TIMEOUT=60m
GATE_TAIL=80 # lines of the gate log in a fix-up prompt ({{gate_tail}})
REMOTE=origin # none: never fetch or push
WORKTREES=.worktrees
BRANCH_PREFIX=plan-
MAX_LINES=300
HEARTBEAT=5m # a progress line while an agent or the gate runs; 0 = off
PRUNE_AFTER_RUNS=2 # retire a finished plan's worktree after this many plan cycles; 0 = off
PRUNE_DAYS=3 # prune build caches in worktrees idle for this long; 0 = off
PRUNE_MAX_GB=0 # also prune worktrees larger than this; 0 = no size cap
QUEUE=batch # landings share one gate (the merge queue); default: off
QUEUE_BRANCH=dangle-queue
REMOTE_CLAIMS=1 # claims are refs on REMOTE too: runners on other computers see them
CLAIM_TTL=12h # a remote claim older than this is stale and may be taken over
ALIAS_cheap=claude:haikuDANGLE_AGENT, DANGLE_FIX_AGENT, DANGLE_REMOTE, DANGLE_QUEUE and
DANGLE_REMOTE_CLAIMS in the environment override them.
dangle doctor checks that REMOTE/$BASE is reachable for a fetch. When a fetch fails anyway —
an empty or dead SSH agent, an offline laptop — dangle says why, once, and goes on with the
local BASE rather than repeating the warning on every poll.
bin/check # shellcheck and the end-to-end tests
test/run.sh # end-to-end tests with a fake agent, aloneMIT license.