For developers · Orchestrator
Dispatcher
On this page
gitoodo dispatcher runs in the foreground (own process, own service later) and starts one Claude
worker per ready issue, each in its own git worktree behind a PTY. It is a client of the
classifier: it reads the read model, claims work with next, reports with done and never writes
labels itself. stalled and needs-human go out as Request::Flag; only the classifier sets them.
What it does#
- Push loop (5 s): repos in an active state, ready issues by score, host choice
(
choose_host, local host only for now), claim via the classifier, lease, worktree (dispatch.worktree_root, branchdispatch.branch_prefix), worker start. Limits come fromdispatch.max_workers,cores_per_workerandmin_free_memory_mb. - Leases (60 s): every running worker's lease is renewed; leases of an earlier dispatcher run are released at start (their workers died with it).
- Hang policy: no output and no hook ping for
dispatch.hang_timeout_secondsrestarts the worker in the same worktree; afterdispatch.max_restartsrestarts the issue is flaggedstalled. A locked login (see "Usage limits") is waiting, never a hang or a restart. - Exit with a pull request:
merge_when_ready(the forge's auto-merge where the forge itself requires checks, else merge pinned to the head SHA once the checks pass). Pending pulls are retried every minute; failed checks restart the worker. Exit without a pull request counts as a restart. Merge gate (dispatch::merge::decide, pure): the style is the configured one (default squash) when the repo settings allow it, otherwise the first allowed of squash, fast-forward-only, merge, rebase. Every merge is pinned to the checked head SHA (Forgejohead_commit_id). The style per repo is the one set for that repo in Settings → Dispatcher (repos[].merge_method), else the globaldispatch.merge_method; the first attempt of each pull logs the effective style and why (merge style squash (repo setting),squash (dispatcher default), orsquash (dispatcher default rebase is not allowed by the forge)). Behind-base update (#383): a pull whose branch is behind its base is brought up to date locally and the checks are awaited again. Fast-forward-only and rebase rebase the branch onto the base (linear history); squash and merge commit merge the base into the branch. The push uses the credential-free askpass path of the worker push; a worker branch is rewritten only when the worktree has it checked out clean at the pull's head SHA, and only with--force-with-leaseon that SHA, so a foreign push is never overwritten. A real conflict is not retried: the pull gets a comment naming the files and the issueneeds-human. At most 3 updates per pull. A satellite run is updated on the satellite (#391): the dispatcher sendsupdate_branchover SSH and the satellite runs the same update with its own git credentials (helper or SSH key, no token, no extra forge permission), pushing with the same lease. When the satellite has no usable credential or is unreachable, the run log states why and the issue goes toneeds-human. The forge's own "update branch" call is not used, except on GitLab projects with fast-forward or semi-linear merges: there GitLab rebases the branch itself (its rebase call on the merge request) and the new head is awaited like a push; a branch GitLab cannot rebase (conflict) takes the local update. GitLab's 406 ("branch cannot be merged") is a refusal like 405/409, so a refused, stale branch is updated instead of failing. Which checks gate: the checks the forge requires, read from the classic branch protection and, on GitHub, the rulesets of the base branch (GET /repos/{o}/{r}/rules/branches/{branch}, rulerequired_status_checks); on Gitea/Forgejo the protection rule named like the base branch, else the first glob rule that matches it (release/*,{main,dev}; byprioritywhere reported), whose required contexts may be globs too; on GitLab the head pipeline when "Pipelines must succeed" is on (pending until it exists; a pipeline of an older head counts as pending). Only then is the forge's auto-merge used, since without required checks it would merge at once. When the forge requires nothing or hides its rules, every check the head reported gates (statuses and check runs: success, neutral and skipped pass, pending waits, a failure fails), plus the repo's extra checks. A head with no check at all waitsdispatch.ci_grace_seconds(default 180 s, 0-3600) from when the gate first saw it, so CI that has not started yet is not taken for "no CI"; a repo without CI merges after that. Failed merge calls: the next attempt waits 1, 2, 4 … up to 30 minutes (a back-off round does not use up a merge attempt), and the alertmerge_failednames a cause category (auth401/403,protection,conflictor behind,not_acceptable406,server,other), never the forge's text; the same cause for the same pull is alerted once, then again only after 1 h, 2 h … up to a day; a new cause at once. The full error stays in the dispatcher log. - Sweeper (5 min and after each merge): removes worktrees of merged or closed issues and their
local branches; a worktree with unmerged commits is reported once (
needs-human) and kept. The same tick runs the reconcile round of the repo hygiene (#771): Gitoodo's worktrees and branches without lease or worker, also after a crash, in every checkout and on satellites; stale remote branches; maintenance; and the disk guard before each new local worker. - Shutdown: SIGTERM or ctrl-c stops the workers, removes the control socket and exits.
- Logs go to
dispatcher.jsonlin the log folder (logging) with issue keys only, never tokens; stderr only takes bootstrap output (dispatcher.stderr.log).
dispatch.worker_program (default claude) can be overridden for one run with the environment
variable GITOODO_WORKER_PROGRAM; an empty value is ignored.
Settings in the app#
Settings → Dispatcher edits the dispatch block of orchestration.json (worker limit, usage
threshold, worker program, clone and worktree folders, base branch, merge style, trusted authors).
The app sends the form to the core, which runs the same validation as the daemon
(Config::field_errors) and writes the file only when every field is valid; otherwise each problem is
shown at its field. Settings without a field in the app (branch prefix, restarts, timeouts) are kept
as they are, and their errors are shown above the form. A running dispatcher reads the file every
round, so changes apply on its next round; without a running dispatcher they apply at its next start.
The merge style offers what the core supports; the default is squash. Below it, every repo with a
rule can choose its own style or "default" (follow the global style). The repo's own settings win: a style it does not allow falls back as described under "Exit with a pull request".
Worker commands#
gitoodo ask [--issue <key>]reads a JSON spec from stdin (id,to, optionalcontext(at most 3 lines),deadline,questionswithtext,kind,options,recommendation), renders it in question format v2 (docs/question-format.md) asworkerblock, posts it as a comment, asks the classifier forneeds-humanand parks the worker: it is stopped without restart or report until a human answers. The issue defaults toGITOODO_ISSUE, which the dispatcher sets (account/owner/name#n).gitoodo worker follow-up --title <t> --body-file <path|-> [--label <kind>]proposes a follow-up issue for work outside the worker's own issue (spec 8.3, #337). See "Worker follow-up issues".gitoodo hook status-line|stop|stop-failurereports a Claude hook to the dispatcher; silent when none runs.
Attach protocol#
Unix socket dispatcher.sock in the private runtime folder (dispatcher_rpc::socket_path), mode 0600
in a 0700 folder; newline-delimited JSON (crates/core/src/dispatcher_rpc.rs). On Windows the same
protocol runs over the named pipe \\.\pipe\gitoodo-dispatcher-<user> (dispatcher_rpc::pipe_name): its
DACL grants access to the current user's SID only, remote clients are rejected and the first instance
is created exclusively, so a second dispatcher or a foreign process cannot take the name (#354; the
pipe code is the small gitoodo-pipe-security crate, the only place with unsafe). A pipe serves one
client per instance, so the dispatcher creates the next instance before it hands over a connection.
Named pipes have no half-close: the client detaches by shutting down its write side. A connection starts
with one request:
| Request | Reply |
|---|---|
{"cmd":"list"} | workers: issue, worker, host, restarts, agent, started_at (unix s; optional, #723) |
{"cmd":"park","issue":k} | ok, or error when no such worker runs |
{"cmd":"stop","issue":k} | ok, or error when no such worker runs |
{"cmd":"restart","issue":k} | ok, or error (no such worker, parked) |
{"cmd":"hook","issue":k,"event":e} | ok; optional "usage": a snapshot |
{"cmd":"status"} | status: usage, lock, counts (below) |
{"cmd":"attach","issue":k} | stream of frames, see below |
After attach the dispatcher sends output frames (hex bytes; first the 256 KiB backlog, then live
output) and a final exit frame. The client may send input frames (hex bytes) at any time; they are
written to the worker's terminal, and {"frame":"resize","cols":c,"rows":r} frames, which set the size of
the worker's terminal (zero sizes are ignored). Bytes of the terminal are opaque, so a client can render
them with any terminal emulator. Closing the connection detaches; the worker keeps running.
Human control (#568)#
The dispatcher reads control.json on every push tick (spec §5.7). While the global switch is
paused it starts no worker and merges nothing, and it stops the running ones (lease released,
in-progress removed, no needs-human). Workers of a repo that is no longer active are stopped
the same way. A held PR keeps waiting without using a merge attempt, a vetoed PR is flagged
needs-human and never merged. Questions, stalls, failed merges and vetoes are written to
activity/alerts.jsonl for the app's desktop notifications; a failed merge call carries its cause,
which the app words in the UI language.
Steering from the overview (#352)#
The overview steers through the dispatcher and the existing mechanisms; every Tauri command needs
orchestrator mode and returns {action, target} or a steering error (kind: "steering" with a
reason: direct_mode, dispatcher_offline, refused (the dispatcher's message names the cause),
invalid_state). Direct mode has no dispatcher, so the commands are refused there.
| Command (Tauri) | Effect |
|---|---|
park_worker(issue) | park: the worker ends without restart or report and keeps its lease (waiting for a human) |
stop_worker(issue) | stop: the worker ends for good; the lease is released and the issue gets the needs-human flag, so it is not dispatched again by itself |
restart_worker(issue) | restart: kills the process and starts it again in the same worktree; counts as a restart |
boost_issue / unboost_issue | adds / removes the manual boost label (score.boost_label) the queue score already reads |
pause_repo / resume_repo | repo state active to paused and back in orchestration.json; other states are invalid_state |
issue is the worker key (<account>/<owner>/<repo>#<n>) from dispatcher_workers. Steering reaches
workers on the local host only; workers on a satellite are not in the dispatcher's local list and
answer refused.
In the overview, each row of a worker that runs on this host offers park, restart and stop. Stop
and restart ask once before they run. Issues that wait in the queue offer a boost toggle, and a
boosted issue keeps the toggle so it can be unboosted. Active and paused repos offer pause or
resume in their header. Every action shows a pending, done or failed line under its row, and a
steering error is shown in plain words. When the app turns out to be in direct mode, the controls
disappear and one line says why. The read model marks a boosted issue with boosted: true.
Live terminal in the app#
In orchestrator mode the agent dashboard asks the dispatcher every five seconds for its workers
(dispatcher_workers; quiet, "no dispatcher running" is a normal state). An issue with a running
worker gets a "Terminal" button; it attaches (dispatcher_attach), shows the backlog and live output in
xterm.js, sends keystrokes (dispatcher_input) and the terminal size (dispatcher_resize), and
"Detach" closes the connection (dispatcher_detach). The socket client lives in
crates/core/src/dispatcher_client.rs; on Windows the commands answer unsupported.
Usage limits#
The dispatcher tracks the Claude login of this host: the 5-hour window, the weekly window and the
weekly window per model, each with percent used and reset time, plus the time of the report and a
stale flag (no report for 10 minutes). Sources, newest report wins:
- Status line: workers start with
--settingsthat setsstatusLinetogitoodo hook status-line; itsrate_limitsJSON from stdin is forwarded asusagein thehookrequest. - OAuth usage endpoint (
https://api.anthropic.com/api/oauth/usage), for times when no session runs. Polled at most every 5 minutes and only while workers are wanted; failures back off exponentially up to 1 hour andRetry-Afteris honoured. The token is read-only from Claude's own login (macOS keychain, else~/.claude/.credentials.json), kept in memory, never refreshed, never logged or sent to the app. - StopFailure hook: a usage-limit failure marks the limit as reached.
Gating: at or above dispatch.usage_threshold_percent (default 90, 1..=100) no new worker starts;
running ones continue. When the limit is reached the login is locked until the reset (5 minutes
when the reset is unknown): the lock is not a hang and no restart is counted. At the reset the
dispatcher types continue and Enter into the terminals of the workers that hit the limit.
{"cmd":"status"} replies {"reply":"status","status":{...}} with usage (windows, stale,
updated_at), threshold_percent, throttled, locked_until (unix seconds or null), workers,
max_workers and queued (ready issues without a slot, as of the last push round).
In orchestrator mode the app's status bar asks for it every 15 seconds (dispatcher_status) and
shows the 5-hour and weekly percentages; a click opens the details: reset times, throttled or locked
(with the time work resumes), how old the values are (stale marked), running workers and queue
length. A window whose reset time has passed counts as 0 %. Without a dispatcher the bar only says
"Dispatcher off"; in direct mode it shows nothing.
Worker delivery#
gitoodo worker pr [--title T] [--body TEXT] pushes the worker's branch and opens the pull request
with Closes #N (default title: issue title plus (#N)); gitoodo worker push only pushes. Both
run in the worker's worktree, read GITOODO_ISSUE, and hand the delivery to the dispatcher's
broker (capability in GITOODO_WORKER_CAPABILITY), which holds the account's token. Inside a worker
without a capability they refuse and never fall back to the keychain (release-gate review H2,
docs/security.md). The token never reaches the worker's environment, files, git config, remote URL
or logs.
How the push gets its credential: git push runs as a child in a scratch git directory Gitoodo
configures itself (token_git.rs; objects from the checkout, never its config or hooks) with an
explicit https URL built from the account origin (not the worktree's origin), system and global
config off, hooks and fsmonitor off, credential.helper and core.askPass cleared,
GIT_TERMINAL_PROMPT=0, and GIT_ASKPASS pointing at the gitoodo binary itself
(gitoodo askpass). Only that child gets GITOODO_ASKPASS_USER/GITOODO_ASKPASS_TOKEN/
GITOODO_ASKPASS_HOST; the askpass call answers git's username and password prompts from them, and
only for prompts that name the forge host. Details and the proxy rule: docs/security.md. Alternatives rejected: a token in the
remote URL or git config (persists on disk and in ps), a credential helper script (a file with
the secret path or token), a setup-assistant check only (needs credentials in the worker's reach).
The same route serves the dispatcher's fetch of the base branch before it cuts a worktree
(worker_pr::fetch_base) and the branch updates (#385). Git output is scrubbed of the token, and
a refused login (missing, expired or unauthorized token) is turned into a readable reason.
Satellites hold no token and still fetch with their own git credentials. Branch guard: never main, master, dev, HEAD or the base
branch; the refspec is HEAD:refs/heads/<branch>, so there is no force push.
Residual risk: for the few seconds of the push the token is in the environment of the git child
(same user, readable by processes of that user, as for any askpass flow). Limits: a worker on a
satellite has no token, so these commands refuse there; delivery from satellites is open (only the behind-base update runs there, with the satellite's own git credentials). The path
of the gitoodo binary must not contain spaces.
Worker follow-up issues#
A worker that finds work outside its issue (a bug elsewhere, a missing test, outdated docs) proposes
it with gitoodo worker follow-up; the worker brief says when to use it and that it is never a way to
split or hand off the worker's own task. The command reads the body from the file (- is stdin, at
most 16 KiB) and sends a follow_up action to the broker with the worker's capability, like
worker pr; there is no direct path, so a worker without a capability or on a satellite is refused.
The broker checks, in order: capability and issue path, title and body (follow_up::validate), the
repo setting worker_follow_ups in orchestration.json (default on; Settings → repo options "Workers
may propose follow-up issues"), a live lease of this worker on its issue (the lease file in the state
folder), and the budgets: dispatch.max_follow_ups_per_run per run (default 3, 0–20, no field in the
form; 0 switches the brief line off and refuses every proposal) and 10 per repo and hour. A
proposal that creates nothing (duplicate, unknown label, forge error) gives its slot back. Then
follow_up::open creates the issue with the account's token: dedupe by normalised title against the
open issues, body with the worker's text (<!-- defused) plus the footer "Follow-up from #N (worker
W)" and the gitoodo:follow-up marker, label gitoodo when the repo has it and the optional kind
label (only existing labels that are no workflow, priority, host or release label), and a note on the
parent issue. The issue is never labelled ready; the classifier's intake asks the repo's human for
approval (docs/security.md, "Worker follow-up issues").
Replies are one line for the worker: the new issue number on success, otherwise
follow-up issue not created: <reason>. Forge and transport errors are logged
(dispatch.follow_up_refused, dispatch.follow_up_created, without tokens or texts) and reach the
worker only as the broker's generic refusal.
Deviations from the spec#
- Only the local host is used; the host abstraction is in place for SSH satellites (step 8).
- The hang policy counts in one-second ticks; the git-change signal is not fed yet, so output and hook pings are the only proof of life.