Skip to content
bendangeloPublic

About

A carrot on a stick for your coding agent: runs your plans overnight, one worktree each, and lands only what passes your gate.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

83 Commits

Folders and files

Repository files navigation

dangle

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.

Install

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 | sh

Or copy bin/dangle anywhere on your PATH.

Start

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 it

Plans

A 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.md and 865-name.md are both 865. A plan without a number goes by its name after the date, and its first words work too: shop-A1 names 2026-10-12-shop-A1-report-links.md (never shop-A10-…), on the command line and in depends=.
  • 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 lint fails 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 lint warns). The skill from dangle skill tells your agents all of this, and how to tidy a repository's existing plans into this shape.

Running

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 empty

A 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.

One plan at a time, more runners when you want them

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 run

Claims 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).

Plans that are already done

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 commit

Check 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.

Agents

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.

Customizing: everything is a file in .dangle/

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).

Disk: worktrees are build output too

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 regenerate

dangle 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_DAYS days ago (default 3), or is larger than PRUNE_MAX_GB GB (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.

The merge queue: one gate for every branch waiting

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-gate lands through the queue without the gate, in a batch of its own (a release's version bump); dangle land --now gates 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.

Landing your 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 with gh 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.

Worktrees by hand

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 remove

Landing 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.

Configuration

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:haiku

DANGLE_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.

Development

bin/check                        # shellcheck and the end-to-end tests
test/run.sh                      # end-to-end tests with a fake agent, alone

MIT license.

About

A carrot on a stick for your coding agent: runs your plans overnight, one worktree each, and lands only what passes your gate.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages