For developers · Orchestrator
Gitoodo Orchestrator – Specification (v1)
On this page
- 1. Goal and scope
- 2. Principles
- 2.1 The system never blocks itself
- 2.2 Facts and labels
- 3. Architecture
- 3.1 Components
- 3.2 Communication
- 4. The app
- 5. Ledger: labels, questions, trust
- 5.1 Label catalog
- 5.2 Manually set labels (not by the bot account)
- 5.3 Trust and approval
- 5.3.1 Orchestrator account (#764)
- 5.4 Question format v2
- 5.4.1 Routing and forwarding (#704)
- 5.5 Dependencies
- 5.6 Activating a repository
- 5.7 Human control (#568)
- 6. Classifier
- 7. Dispatcher
- 7.1 Loop (push model)
- 7.2 Branches and worktrees
- 7.3 Session environment
- 7.4 Hang detection (v1)
- 7.5 Questions (gitoodo ask)
- 7.6 Leases and dead workers
- 7.7 Claude usage limits
- 7.8 Pull requests and merge
- 7.9 Blockade table (proposal)
- 8. Workers
- 8.1 Contract
- 8.2 Prompt template (proposal)
- 8.3 gitoodo ask
- 9. Sweeper
- 10. Release planning (optional per repo)
- 11. Satellites
- 12. Orchestrator chat
- 13. Configuration (proposal)
- 14. Quality requirements
- 15. Migration plan (proposal; each step mergeable, the system stays usable in between)
- 16. To verify during implementation
Status: agreed design, ready for implementation planning (2026-11-12).
Source: design interview with the maintainer on the planning whiteboard. This file is the single source of
truth for the orchestrator; where it contradicts older docs (docs/daemon.md, docs/status-model.md,
the former integration doc of the external orchestrator, docs/question-format.md), this file wins and those docs are to be updated.
Values marked (default) are configurable. Items marked (proposal) were not decided in detail by the maintainer and may be refined by the implementer; flag deviations in the PR description.
1. Goal and scope#
Gitoodo grows from a tray app into an open-source orchestrator that runs many Claude Code sessions deterministically across several machines, using a forge (Forgejo or GitHub) as the ledger.
- Open source, built for other people: all identifiers (labels, services, config keys, markers) are English and configurable. Human-facing text follows the app language of Gitoodo.
- The existing integration of an external agent orchestrator is removed and replaced. It was only the reference for several mechanisms below (worktrees, usage limits, remote hosts).
- Clean start: no recognition of the old German labels, keywords or question format.
Version 1: classifier, dispatcher with local and remote workers, sweeper, gitoodo ask, answering
questions in Gitoodo, orchestrator chat, Claude usage limits in the status bar, release planning
(optional per repo).
Later: screenshot-based hang detection (screenwatch), mobile app (QR pairing, LAN TLS), GitLab for the orchestrator (the existing GitLab adapter for the plain app stays), releasing dev to main from Gitoodo, AI review of PRs.
2. Principles#
2.1 The system never blocks itself#
- Reconstructible: every state can be rebuilt from facts on the forge after a restart, crash or lost cache. Local databases are caches, never the truth.
- Nothing waits forever: every waiting or locked state has a deadline or a way out and becomes visible to the human at the latest then.
- Fallback instead of standstill: when a service or path fails, the others keep working (e.g. polling instead of webhooks). Exception: a fallback must never hide a failure. Where it would, use self-start plus a clear error instead of a silent substitute (e.g. the app in orchestrator mode, section 4).
- Failures stay small: a problem affects one issue or one host, never the whole queue.
- Every component documents where it can block and how it heals (blockade tables below).
The main host is not always on. When it is off, the system stands still; this is intended. After waking, every service first reconciles with the forge, then acts.
2.2 Facts and labels#
- The forge is the only source of truth. Services write facts (comments, assignees, PRs, lease audit comments, question blocks) and labels.
- Each label group has exactly one owner – the component that makes that decision. Nobody else writes labels of that group. Owners recompute their group from the facts on every run and overwrite it; there is no "conflict resolution".
- Services are deterministic. LLMs run only inside workers and the chat.
3. Architecture#
3.1 Components#
| Name | Binary / command | Job | Not responsible for |
|---|---|---|---|
| Gitoodo (app) | Gitoodo.app (binary renamed internally to gitoodo-app) | GUI, orchestrator chat, questions, status | hosting services, writing service labels |
| Classifier | gitoodo classifier | readiness, dependencies, PR links, answer detection, release planning | starting workers, merging |
| Dispatcher | gitoodo dispatcher | assigning issues, starting/stopping sessions, limits, hang detection, PR auto-merge | classification labels, writing code |
| Sweeper | gitoodo sweeper | removing merged branches and worktrees | deleting unmerged work |
| Ask | gitoodo ask | a worker's question to the human | waiting for the answer |
| Satellite | gitoodo satellite | hosts worker PTYs and the sweeper on a remote host | scheduling |
| MCP server | gitoodo mcp | the chat's tools | file or shell access |
| Attach | gitoodo attach <issue> | view/interact with a running session in any terminal | – |
| Worker | a Claude Code session (no own binary) | one issue, one worktree, PR | labels, other workers, merging to main |
| Forge adapter | library in gitoodo-core | uniform API for Forgejo and GitHub | business logic |
| Ledger | Forgejo or GitHub (exactly one forge per project, configured per repo) | issues, labels, PRs, milestones, branch protection | running services |
- One program
gitoodowith subcommands; each service runs as its own process and system service, started and stopped independently. Today'sgitoodo-clibecomesgitoodo. - Shipping (#355): the direct-distribution app bundles the CLI as a Tauri sidecar
(
bundle.externalBin, overlaysrc-tauri/tauri.sidecar.conf.json, built byscripts/build-sidecar.sh). Installing copies it to a stable per-user folder (paths::bin_dir,GITOODO_BIN_DIRoverrides) and registers classifier and dispatcher there as system services with automatic restart (launchdKeepAlive, systemdRestart=always; Windows: classifier only, task with restart on failure; the dispatcher needs named-pipe control first). The app shows app, installed CLI and running classifier versions and offers a reinstall on a mismatch. The sandboxed store builds (storefeature) ship no sidecar and install no services: they are a viewer and the orchestrator runs from the direct build or a manual CLI install. - Today's daemon (
docs/daemon.md) is split: queue/lease logic moves into the dispatcher, label hygiene into the classifier. Destructive catalog transfer on activation is dropped (section 5.6). - Where things run: main host – classifier, dispatcher, sweeper, local workers, app. Satellites –
gitoodo satellite(workers + sweeper), controlled by the main host's dispatcher over SSH. - Forge adapters in v1: Forgejo and GitHub. Capabilities: issues, labels, comments, dependencies, branches, PRs, auto-merge, milestones, events/webhooks with polling fallback (default 5 min).
3.2 Communication#
- App ↔ services: local socket / named pipe (as today's daemon: mode 0600, user-only pipe).
- Dispatcher ↔ satellite: SSH only (stdio bridge, JSON lines). No open ports on satellites.
- Workers never talk back to the dispatcher directly; they write to the forge (
gitoodo ask, PRs). - Writes from the app (answers, approvals, chat actions) go straight to the forge; in orchestrator mode the app then nudges the classifier to re-read immediately.
4. The app#
- Two modes, selectable in the app, with the consequences explained in the UI:
- Direct mode: the app polls the forges itself, as today. No orchestrator, no label maintenance; status is derived from assignees and PRs.
- Orchestrator mode: the app shows the services' picture via the local socket (classifier: issues/labels; dispatcher: workers, queue, leases, hosts), plus chat, worker control and limits. If the services are down, the app tries to start them; if that fails it shows a clear error state instead of data. It never silently falls back to direct mode.
- Repositories: connect a forge, Gitoodo lists all repos, the user switches them individually or
in bulk. In the app a fetched repo is on (fully autonomous) or off; pausing is an action
on a repo that is on, not a level picked during setup (#599). Stored states:
off(not fetched,disabled_repos),observed(shown as "off": fetched, nobody writes; default for newly imported repos),paused(on and paused: classifier works, dispatcher assigns nothing),active(on). The stored values need no migration:observedreads as off,pausedas on + paused,activeas on. Switchable in the app and by chat (project focus, e.g. "only A and B now"). Since #569 the repository list selects all, by owner or row by row and switches the selection in one step; the repo detail edits the config-only options per repo (the human whose questions get assigned, whether release planning runs). - Guided setup (#569): the onboarding offers orchestrator mode and hands over to the setup
assistant (service, account and rights, labels, repo, local copy, skill and
AGENTS.md, first worker; see setup.md). The assistant writes only the marked Gitoodo section ofAGENTS.mdin the local copy, on request, and never commits. - Issues from the app (#569): the orchestrator view creates an issue per repo, optionally with the ready label set at once.
- Questions: questions on which other issues wait are sorted first and show the number of waiting issues. After 2 h (default) unanswered – or the question's own deadline – Gitoodo notifies again.
- Status bar: per Claude login the remaining 5-hour and weekly limit with reset time; when locked, clearly when work resumes; stale values are marked as stale.
- Viewing sessions: live terminal view of any worker (local or remote) in the app.
5. Ledger: labels, questions, trust#
5.1 Label catalog#
Names are canonical defaults; users can map them to their own names. Never created: type:*,
needs-classification (nothing in the system consumes them) and answered (answers are detected
from the comment order, section 5.4).
| Group (question) | Label | Owner | Meaning | Self-healing |
|---|---|---|---|---|
| 1 Placement: where and how urgent? | priority:p0…p3 | classifier, human | dispatcher order. p0 now, p1 next, p2 normal, p3 some day | missing → p2 |
os:windows / os:macos / os:linux | classifier, human | OS the worker must run on | missing → any host; no matching host online → waits visibly, notify | |
host:<name> | human (optional) | pins an issue to one host | host offline long → notify | |
| 2 Readiness: may it start? | needs-clarification | classifier | contradiction (dependencies, PR link); starts a clarification worker | clarification fails → needs-human |
blocked | classifier | an open dependency | lifted when all dependencies are closed; cycle → needs-clarification | |
ready | classifier | may be worked on (see 5.3) | unanswered approval blocks this issue and its dependents, visibly | |
| 3 Workflow: what is happening? | in-progress | dispatcher | reserved, prevents double assignment, shows who works on it | see 7.6 |
in-review | dispatcher | PR open, auto-merge to dev enabled, waiting for green CI | CI red / conflict → new session; no movement → notify | |
stalled | dispatcher | still failing after 3 restarts | blocks this issue and its dependents, waits for the human | |
| 4 Human: is something waiting for you? | needs-human | question mechanism: whoever asks via gitoodo ask sets it; answer detection (classifier) removes it | worker question, approval or clarification; the kind is in the question block | deadline in the block, reminder (section 4) |
| 5 Pull requests: is the PR clean? | needs-issue-link | classifier | PR without issue; merge blocked by a failing status check | lifted once the link is unambiguous |
| 6 Release (optional) | release:next | human (also via chat) | scope of the next release | see section 10 |
| 7 Marker (no question) | gitoodo | classifier | teal #29aea9; set on every open issue and open PR of paused and active repos, so you see the classifier handles it. Added only, never replaces another label; in no exclusive group | missing → added; label missing → recreated |
Precedence: blocking wins (blocked over ready). Dispatcher candidates: open, ready, repo
active, no in-progress / needs-human / stalled, all dependencies closed.
5.2 Manually set labels (not by the bot account)#
The forge records who set a label.
readyby hand = approval; dependencies still win.blockedby hand without a dependency fact = deliberate hold until the human removes it; the classifier comments once.needs-clarificationby hand starts a clarification worker.- The chat may set the labels a human sets (priority,
host:,release:next), never service labels.
5.3 Trust and approval#
- Issues and PRs by trusted authors (maintainers, own bot, configurable list) become
ready/ are auto-merged without approval. Trusted from the start (#599): the connected account, the repo'shuman, the logins intrusted_authors(own bot accounts), everyone with write access and the members of the organisation owning the repo (Forgejo/Gitea and GitHuborgs/{org}/members/{login}; GitLab's inherited group members already count through the member level). The settings show this list next to the editabletrusted_authors. - Others get an approval question (
needs-human, kindapproval). Yes →ready. No → the classifier closes the issue with a comment. Reopened by a trusted person = approval; by anyone else = ask again. - Foreign contributions (#705): the approval question is the only question a foreign
contribution gets. It is addressed to the maintainer, but the author reads it too, so its English
context explains the process ("A maintainer decides before an AI agent works on this; you'll get
an answer here."); a short description adds a line, and the maintainer's yes also covers it (no
clarification question to the stranger afterwards). It never carries a recommendation. A question
counts as asked when the bot or a trusted person wrote it, so changing the connected account does
not ask again; the only second question is the one after a reopen of a refused issue. The per-repo
rule
foreign_intake(default on) switches new approval questions off; such issues then wait untouched. The cap of five comments per repo and run stays. - Bundled approvals (#705): "Fragen an mich" shows "N fremde Beiträge warten auf Freigabe" above the
list, with every open
intake-approval-*question (title, author, repo, age), oldest first. Each item needs its own explicit yes or no (buttons or Y/J and N; Enter and Space never answer, arrows skip); there is no bulk answer and no preselection. An answer waits five seconds and can be undone (U, Backspace, Cmd/Ctrl+Z or the row's button) before it is posted throughanswer_questionin the normal answer format; leaving the view posts the answers already given. A failed post puts the item back to unanswered. - Optional spec link (#705): per repo (
label_spec_link, default off, Settings → repo → Rules) theneeds-humanlabel description becomes "Waits for the maintainer. Questions: https://gitoodo.com/spec/questions/v2/" (within the forges' 100 characters). - Turning a repo on never writes in bulk unseen (#598): the app shows the adoption preview first and
stores the backlog choice (
newdefault,ready,ask) withadopted_at. Withnew, items opened beforeadopted_atare not touched (pull requests: not updated since). The intake posts at most five comments per repo and run and reports the rest as pending. Questions address the repo'shuman, else the connected account, never the repo owner (may be an organisation). - Trust comes from the author's real permission on the forge, looked up once per repo and login:
GitHub and Forgejo/Gitea
collaborators/{login}/permission(owner/admin, maintain, write trusted; triage, read, none not), GitLab the project member level incl. inherited access (Maintainer 40 and up trusted; Developer 30 counts as write, below that not). A failed lookup, an unknown role or a missing user is untrusted. - Only a trusted commenter can approve; the approval question's "yes" makes the issue
ready. The classifier closes a refused issue with a comment and the marker<!-- gitoodo:intake-rejected -->; a "no" followed by that marker is stale, so an issue reopened by anyone gets the question again (new block id). Limitation: the forge does not tell who reopened, so a trusted person approves by answering "yes" on the new question. - Incomplete issue of a trusted author (fewer than 20 non-whitespace body characters, deterministic):
clarification question (kind
clarification) to the author, who may answer it; once answered the issue isready. Re-runs write nothing when the question or its answer is already there. - Every decision carries a reason in the read model (
IssueModel.reason:trusted_author,approved,untrusted_author,incomplete). - The legacy label
einordnung:fehltis no longer set or read; a missing description is the clarification question. - Untrusted PRs never get auto-merge; they get an approval question.
- This rule is security-critical (workers run without permission prompts, section 8) and needs tests.
5.3.1 Orchestrator account (#764)#
- Per forge host (origin, case and trailing slash ignored)
orchestration.jsonmay name the account the orchestrator acts as:orchestrator_accountsmaps the host to an account id. One resolution (orchestration::acting::write_account) picks the account for every write: the host's orchestrator account when it exists with the same forge kind and origin, else the repo's own account. The dispatcher (push, pull requests, merge, comments, leases), the classifier, workers (gitoodo ask) and satellite delivery all write through it; reads may stay on the repo account. - Choosing an account adds its login to
trusted_authorsonce (clearing the choice keeps it), so the bot's own issues and PRs stay trusted. While a bot writes, questions still address the person: the repo'shuman, else the login of the repo's own account. - An account chosen for a host and the account of no repo rule is a pure worker account: the app does not sync it as a source of repos and leaves it out of the account list; the settings section "Orchestrator-Konto" shows, checks and renews it.
- The onboarding asks per host before the services start (step "Worker-Konto", orchestrator mode
only). A separate bot account is recommended: clear history, separate rights, revocable on its own,
the human's notifications stay clean, and branch protection can require a human review. The own
account stays possible and works: Gitoodo tells its comments from the human's by the machine
markers (
docs/question-format.md, "Gitoodo comments"), never by login alone; the history then shows the human's name and the forge does not notify about these actions. - The check of a worker account (
check_worker_account) names its login, the token scopes it lacks and every activated repo on the host it cannot see or lacks a right in (the orchestrator's rights without repository settings), each with a link to grant access. - Existing installs keep their behaviour until the user chooses; the app shows a one-time hint that
recommends the switch (
orchestrator_hint_doneends it; any choice ends it too). - Lease audit comments count only from Gitoodo's own write logins of the host
(
acting::known_writers): the acting login, the repo account's login and the earlier orchestrator logins. A switch records the logins before and after it inorchestrator_writers(per host, newest last, at most 8), so a lease written before the switch still completes after it. A lease comment by any other user is never read (the fence against forged leases stays). - Items a separate orchestrator account opened do not wait for the user (#709): the adapters read the
author of every open pull request, the sync flags pulls by
acting::orchestrator_logins(current and earlier bot logins, never the user's own), and "Wartet auf dich" skips their failing checks. Issues the bot opened stay in the questions list only while they carry an open question card. While the orchestrator writes as the user, nothing is told apart.
5.4 Question format v2#
- Machine-read parts are fixed and English:
<!-- gitoodo:questions v2 id="…" kind="worker|approval|clarification" -->…<!-- /gitoodo:questions -->. Human-read parts follow the app language. - 1 to 4 questions per block, each with options and a recommendation; optional deadline.
- Answers are understood in every supported language (
yes/no,ja/nein,1b, …). - Answered = the last comment after the question was written by the asked human. No
answeredlabel. - Update
docs/question-format.md, its parsers, tests and the skill accordingly (v1 support is dropped).
5.4.1 Routing and forwarding (#704)#
- Routing rules per repo in
orchestration.json(routes: [{label, to}], at most 50, edited in the repo's rules in the settings):gitoodo askaddresses a worker's question to the first rule whose label the issue carries (any case), else to the repo'shuman, else the worker's own choice stays. - The asked person can forward a worker question addressed to them to another trusted person (5.3)
from the app ("Forward to …"). The app posts, from the asked person's account, one comment with a
forward marker and a new block per card (format:
docs/question-format.md, "Forwarding"), assigns the issue to the new person and removes the forwarding person. The old card counts as answered; the new one waits for the new person. - Nobody receives a forward while holding 10 or more open cards in that repo; the app says so.
- Answer detection follows the addressed logins: while a card addressed to someone is open the issue
keeps
needs-humanand stays assigned to them; the answer may come from the repo'shumanor from any login a card of the issue names. "Asked of me" only lists items with an open card for me (or without an addressee). - The team chat mentions the person asked through the login-to-handle mapping
(
docs/chat-notification.md).
5.5 Dependencies#
- Text lines
Depends on #12/Blocked by #12(alsorepo#12,owner/repo#12), plus the forge's native dependencies where the adapter supports them. The classifier keeps both consistent; contradictions and cycles →needs-clarification. The dispatcher only reads the cleaned result.
5.6 Activating a repository#
Activation shows a preview: labels mapped to the catalog, labels to be created, remaining labels. Remaining labels are never deleted automatically, only after explicit confirmation.
Label migration (#464): the preview can be re-opened for an already active repo (app: "Migrate old
labels…" in the repo detail; CLI: gitoodo labels migrate <account> <owner/repo> [--yes], preview only
without --yes). Only after confirmation are legacy labels (aliases.tsv) renamed on the forge, so
issues keep them; a rename whose catalog name already exists is skipped (no merge, no duplicate) and
missing catalog labels are created. aliases.tsv feeds the preview only: the classifier no longer
recognises legacy names and recomputes all issues on its next run. Since #467 the queue, the overview
and the default views recognise catalog names only as well; a repo that still holds legacy labels
shows a hint (settings-repo-detail-migrate-pending) pointing to the activation preview.
Legacy groups (#567): status (status:bereit/blockiert/in-arbeit/review, an:mensch), priority
(prio:N) and release (release:muss, release:now, release:blocker → release:next) are
renamed. Without a catalog label and therefore kept as remaining labels (no information lost, never
deleted automatically): type (typ:*), severity (schwere:*), release:später/later/backlog,
and the retired markers status:neu and einordnung:fehlt (no status = waits for the intake; a
missing description is a clarification question). The system neither sets nor reads them.
5.7 Human control (#568)#
The maintainer can stop, hold and veto anything the orchestrator does, and see what it did. The app reads and writes the same state files the services read (no extra RPC), so control works while a service is busy or restarting.
- Global switch (
control.jsonin the state dir,paused): while on, the classifier writes nothing (reconcileis empty, theWriterhands out no assignment) and the dispatcher starts nothing and merges nothing. It survives restarts; resuming continues where it stopped. The tray itemcontrol-pauseand the commandscontrol_get/control_set_pausedtoggle it. Pausing also stops every running worker (the lease is released, thein-progresslabel removed, the issue is not flaggedneeds-human), so it returns to the queue on resume. - Repo pause or off stops the repo's running workers the same way (the dispatcher enforces it
on every push tick, also for remote workers) and releases leases and
in-progresslabels (Flag::Releaseover the classifier RPC removes onlyin-progress). - Merge gate per PR (
control_set_merge_gate:open,held,vetoed, keyed<account>/<owner/repo>#<n>): a held PR is not merged and keeps waiting; a vetoed PR is never auto-merged and its issue getsneeds-human. A global pause holds every merge. Limit: auto-merge that was already enabled at the forge cannot be cancelled by Gitoodo. - Activity log (
activity/forge-writes.jsonl): every forge write of the classifier, dispatcher and worker tools (labels, comments, milestones, merges, closes) with time, repo, item, action, detail, reason and result. Append-only, mode 0600, texts redacted (never a token), bounded to 512 KiB (past that the newest half is kept). Read withactivity_forge_writes. - Alerts (
activity/alerts.jsonl): the dispatcher emitsquestion,stalled,merge_failed(with acausecategory, deduplicated per pull) andmerge_vetoedevents; the app pollscontrol_alertsand shows them throughnotify::show. Eventcontrol-changedcarries the new control state.
6. Classifier#
- Polls (or receives events for) all repos in
observed(read only),pausedandactive; writes only inpausedandactive. Serves the read model to the app. - Recomputes groups 1 (defaults), 2, 5 and 6 per run; recreates missing catalog labels. Adds the marker
gitoodo(group 7) to every open issue and open PR on GitHub, Forgejo/Gitea and GitLab when it is missing;observedrepos stay untouched. - PR hygiene: a PR is linked when its commits reference exactly one issue → the classifier adds the
link itself. Zero or several → failing status check +
needs-issue-link+ comment +needs-clarification. Lifted automatically once the link is recognised (re-run the status check). - Intake (5.3): a new open issue (no status label, no
prd/stalled/extern/blocked) becomesreadywhen its author is trusted and the body is complete; otherwise the approval or clarification question is asked. A worker's follow-up (8.3) always gets the approval question, although the bot wrote it. Nobody labelsreadyby hand. Block idsintake-approval-N,intake-clarify-N. - Answer detection → removes
needs-human, setsready(worker questions: the issue continues on its branch, section 8.3). It runs in every repo: without a repohumanor routing rule the asked human is the login in the card's header (docs/question-format.md, "Detecting an answered question"). A no to an approval card the intake no longer reads is no go-ahead; the issue keeps waiting.
| What can happen | Effect | Handling |
|---|---|---|
| classifier crashed | answers not detected, blocks not lifted | system service restarts it; app shows error; dispatcher keeps assigning ready issues |
| forge unreachable | nothing updates | retry with growing backoff, visible; full reconcile afterwards |
| forge API limit | requests rejected | wait until the reset the forge reports; active repos first |
| catalog label deleted/renamed on the forge | labels missing | recreated next run |
| contradictory labels | unclear readiness | recompute own group from facts; never touch other groups |
in-progress without valid lease | issue reserved forever | dispatcher's group; it removes it after the lease check |
| human "answers" with a non-answer | worker starts without answer | worker asks again; bounded because each question needs the human |
| question stays unanswered | issue and dependents wait | visible, sorted first, reminder |
7. Dispatcher#
7.1 Loop (push model)#
The dispatcher starts one session per issue; next/done of today's daemon are absorbed.
- Triggers: a slot frees up (worker done, question asked, worker ended), a forge change, an interval.
- Candidates: see 5.1.
- Host: reachable, matching
os:/host:, below its own limit and the global limit, enough free memory, Claude login not locked. Prefer the host that already has the branch's worktree, then the least loaded one. If no host fits, skip the issue (never stall the queue). The host is chosen per issue, best score first: itsos:(macos,linux,windows;darwin/winaccepted) andhost:<name>labels form the constraint. Ahost:name is a configured satellite name or one of the names of the machine running the dispatcher (#750): its own name (orchestration.json›local_host.name, default the sanitised short host name, e.g.macforMac.local, written once into the file on the first start), its aliases (local_host.aliases, e.g. added by "Is this machine" in Settings › Worker machines or by "Call this Mac “x”" in the status window) and alwayslocal. The UI calls every machine that runs workers a worker machine ("Worker-Rechner"); this one is always one of them, with at least one slot, wherever the dispatcher runs. Names compare without case; one matcher (dispatch::host::names_host) serves the dispatcher and the daemon'snext. Internally the machine stays the host idlocal, so leases and worker lists do not change when it is renamed. A satellite may not take one of these names (local_nameerror), and a rename may not take a satellite's name. An issue no host can take waits without blocking other issues, with one concrete reason (dispatch::host::WaitReason, checked in this order):unknown_host(thehost:label names no host),os_mismatch(no host has theos:),offline,agent_missing(coding agent missing or signed out),usage_gate,low_memory,at_capacityorglobal_limit. The reason is written tohost-wait.jsonand the read model (host_wait.reason), logged once per new wait or changed reason asdispatch.host_wait issue=<repo#n> host=<name|-> reason=<reason>: …, shown on the board, and notified once per issue and reason for the first four (only the user can end those). The dispatcher status counts the waits by reason (host_wait_reasons) and the unknownhost:names with their issues (unknown_hosts); only the first four reasons make the status window and the switch card say "needs you", with the concrete fix in place: one unknown name as "98 issues are marked for the machine “mac” (label host:mac) … This Mac is called “local”" with [Call this Mac “mac”] (adds the alias) and [Show labels], several names grouped with their counts and one button each. Settings › Worker machines listshost:labels on the open issues of the paused and active repos that name no machine, with counts, and offers: set it up as another machine, treat it as this machine (adds an alias), or remove the label from those issues (forge write after a confirmation with the count). The onboarding's workers step (orchestrator mode, after accounts, repos and the setup) sets the workers at once (max_workers), this machine's name, explainshost:labels and offers the alias for each unknown label once the read model has them. - Order: score = priority weight + age factor + manual boost + release bonus. Age grows steadily so
nothing starves. Impact and effort are not part of it. _(proposal for defaults: p0 1000, p1 300,
p2 100, p3 30; +1 per hour of age; manual boost +500; release bonus +200). A repo may carry its
own
scoreweights in itsreposentry (#569); without one the globalscoreapplies. Editable in the repo detail (Settings › Repos). - Assign: set
in-progress, write the lease audit comment, create or continue branch and worktree, start the session (section 8). - Watch: liveness, hangs, leases, limits, PR state.
Limits: per host 1 worker per 2 CPU cores (default), global 8 (default), set in Gitoodo.
7.2 Branches and worktrees#
- Branch
<prefix>/<issue-number>-<short-title>, prefix defaultgitoodo(e.g.gitoodo/42-login-fix). - Worktree under a root per host, default
~/gitoodo/worktrees/<repo>/<issue-number>. Base is always dev. - A restart (hang, dead worker, after a question) continues branch and worktree with a new session
(issue + Q&A + handoff +
git log+ diff as start; no--continue). - Only a new attempt after the old branch was merged (issue reopened) gets
-2,-3.
7.3 Session environment#
- Claude Code is started with
--dangerously-skip-permissions(maintainer decision; accepted risk) unless the repo'sworker_permissionsisguarded(--permission-mode auto). Only the issue and trusted people's comments reach the worker (docs/security.md). - The dispatcher passes settings with a managed statusLine command and
Stop/StopFailurehooks that callgitoodo(usage limits, section 7.7), the app language, and build-parallelism limits:CARGO_BUILD_JOBS,MAKEFLAGS=-jN, test thread counts = cores / workers on that host. - Optional shared compiler cache (e.g. sccache) across worktrees.
- No worker starts below 1.5 GB free memory (default); under memory pressure nothing new starts there.
7.4 Hang detection (v1)#
- Active = terminal output or git changes in the worktree. Both silent for 10 min (proposal; the
board had 5 min before the screenshot stage, which is postponed) → before acting, re-read the issue:
needs-humanopen or Claude login locked → not a hang. Otherwise restart. - 3 restarts (default, per issue configurable) →
stalled.
7.5 Questions (gitoodo ask)#
gitoodo ask reports "done with question"; the dispatcher ends the session and frees the slot
immediately (in-progress → needs-human). When the classifier sets ready after the answer, the
issue is assigned like any other (preferring the host with the worktree).
7.6 Leases and dead workers#
- Lease expired and the worker provably dead (no process, no output, session gone) → release the issue; counts as a restart.
- Not checkable (host offline) → release after a 30 min grace period (default).
- After the main host wakes: check liveness before releasing anything.
7.7 Claude usage limits#
- Tracked per host / Claude login: 5-hour and weekly window (percent, reset time), plus per-model weekly limits where reported.
- Sources: (1) statusLine JSON of running sessions (
rate_limits.five_hour/seven_day, Claude Code ≥ 2.1.80) – primary while sessions run; (2) the OAuth usage endpoint of the login (api.anthropic.com/api/oauth/usage) when no session runs, with a minimum interval, backoff andRetry-After; (3) theStopFailurehook (≥ 2.1.78) for "limit reached". If (2) breaks, fall back to (1)/(3) and the known reset time; show values as stale. - At ≥ 90 % (default) in any window: no new workers on that login.
- Limit reached: login locked until the reset; the session stays open; at reset the dispatcher types "continue". Not counted as hang or restart. Other hosts with other logins keep working.
- Satellites deliver the values through a small state file the dispatcher reads over SSH.
7.8 Pull requests and merge#
- The worker opens a PR (
Closes #N, normal description) and ends. No extra review in v1; the condition is the complete green CI (dev is protected: merge only with green status checks). - The dispatcher enables auto-merge to dev (squash) and sets
in-review. Auto-merge is only a real gate with branch protection requiring status checks; without it, or where the forge has no usable auto-merge API, the dispatcher merges itself once all checks reported on the reviewed head SHA are green, and a head without any check only after a grace period (checked against the forges' sources; seedispatcher.md). - Required checks per repo (#569):
repos[].required_checkslists check names that must be green on top of the forge's required checks (default: empty, i.e. exactly the forge's required checks as before). A listed check counts with the worst state its head commit reported and as pending while nobody reported it; failing ones count as red CI. With such a list the dispatcher merges itself instead of enabling forge auto-merge, because the forge does not know the extra checks. Editable in the repo detail. - CI red or merge conflict → new session on the same branch with the failure output; counts as a restart.
- After the merge the dispatcher closes the issue itself (
Closes #Nacts only on the default branch on GitHub; Forgejo behaviour differs; closing explicitly is idempotent) and triggers the sweeper. - Workers never merge to main.
- A worker holds no forge credential. It delivers with
gitoodo worker pr(push, then open the PR;--title,--body) orgitoodo worker push(push only), which use the account connected in Gitoodo (keychain token, existing write adapters). Design and limits:dispatcher.md"Worker delivery".
7.9 Blockade table (proposal)#
| What can happen | Handling |
|---|---|
| dispatcher crashed | system service restart; on start reconcile leases from forge audit comments |
| satellite unreachable | its issues: lease grace period, then release; no new work there; notify |
| worktree corrupt / git lock left over | recreate the worktree from the pushed branch; never delete unmerged commits |
| session fails to start (auth, missing tool) | mark host unhealthy, notify, try another host; issue not counted as restart |
| auto-merge not available on a forge | dispatcher merges itself when CI is green |
| issue edited while in progress | worker continues; new facts are read at the next session start |
8. Workers#
8.1 Contract#
One issue, one worktree, good commit messages, a PR with Closes #N into dev. No labels, no control of
other workers, never merge to main. Asks via gitoodo ask when a decision is missing.
8.2 Prompt template (proposal)#
Issue title/body/comments (incl. Q&A and handoff), repo conventions (CLAUDE.md), branch, base dev,
definition of done (green CI, PR), how to ask (gitoodo ask --help), language for human-facing text.
A clarification worker gets the contradiction and resolves it or asks.
8.3 gitoodo ask#
Required: --question (1–4, each with options and a recommendation), --next (what to do after the
answer, per option if they differ). Optional: --notes (rejected approaches, pitfalls). Added
automatically: issue and branch (from the worktree), commit messages since dev, changed files, worker,
host. The tool refuses calls with missing fields and limits the handoff to about 15 lines.
Behaviour: commit and push the work in progress → write the question block (question on top, handoff
collapsed below) → set needs-human, assign the human → tell the dispatcher (session ends, slot freed).
It writes directly to the forge, so questions arrive even when the dispatcher is down.
gitoodo ask --help is the worker's manual; the skill only points to it. No handoff on normal
completion – the PR description is enough.
Follow-up work found by a worker (#337): work outside the worker's issue (a bug elsewhere, a missing
test, outdated docs) is proposed, not done. gitoodo worker follow-up --title <t> --body-file <path|-> [--label <kind>] sends the proposal to the dispatcher with the worker's capability; the worker never
creates issues itself. The dispatcher checks, in this order: the capability and the issue path (as
for every worker action), title and body (title one line, at most 200 characters; body a complete
description, at most 16 KiB), the repo setting worker_follow_ups (default on, Settings → repo
options), a live lease of this worker on its issue, at most dispatch.max_follow_ups_per_run per run
(default 3, 0–20; restarts of the same run count together) and at most 10 per repo and hour. Then it
creates the issue with the account's token:
- the worker's title and body, with
<!--defused so the text cannot forge Gitoodo markers, and a footer "Follow-up from #N (worker W)" plus the marker<!-- gitoodo:follow-up parent=N worker=W -->; - the intake label
gitoodo(if the repo has it), so the classifier triages the issue, and the optional--labelwhen the repo has that label and it is no workflow, priority, host or release label; - never
ready: an open issue with the same normalised title (case, whitespace and punctuation ignored) refuses the proposal instead.
A short note on the parent issue lists the follow-up. Refusals reach the worker as one line naming
the reason (setting off, cap reached, duplicate #M, unknown label, rate limit); forge errors only say
that nothing was created. Although the bot account wrote it, the intake treats a follow-up like a
contribution from outside (5.3): it asks the repo's human for approval ("yes" makes it ready, "no"
closes it) and the read model never counts it ready on its own. Satellite workers cannot propose
follow-ups yet; they mention findings in the PR description. Red CI never creates a new issue.
9. Sweeper#
- Triggers: event from the dispatcher (PR merged to dev, issue closed; on satellites over SSH), an interval (default hourly), and workers clean their own worktree regularly.
- Deletes worktree, local and remote branch after the merge to dev.
- Never deletes branches with unmerged commits or worktrees of running workers; reports them with a
comment and
needs-human. Offline hosts catch up on the next run. - Crashes, resets and leftovers: the reconcile round, remote branch cleanup, disk guard and temp root of the repo hygiene (#771).
10. Release planning (optional per repo)#
- Uses forge milestones (Forgejo and GitHub both call them milestones).
- An issue enters the next release only through: (1)
release:nextby the human or chat, (2) being a dependency of a release issue (recursive), (3)priority:p0. Everything else is backlog. - Next milestone = earliest due date; default length 3 weeks.
- The due date is a decision point, not a cut: all done → question "release now?"; open items at the due date → question with the list (move, remove, extend). Nothing is cut automatically.
- No open milestone → question "create the next milestone?" (block
intake-milestone-N, anchored on the lowest-numbered open issue, no planning issue). Yes → the classifier creates the next title (last digit run of the highest known version bumped, elsev0.1.0) and writes<!-- gitoodo:intake-milestone-created -->; No → asked again after 28 days. - All questions and findings of release planning name the scope label
release:next(never the legacyrelease:muss). - The app shows the milestone planning works on (or none, or several without a clear next one) in the release view next to each repo and in the repo detail (#569).
- Release issues get a score bonus. The actual release (dev → main, tag) comes after v1.
11. Satellites#
gitoodo host add <host>(also from the app): copygitoodoover SSH/SFTP into a versioned directory, verify the checksum, startgitoodo satellite. On every connect compare versions, update, roll back if the new version does not start.- Service per OS: Windows with a visible desktop session → task at logon (windows optionally visible);
Linux without desktop → systemd user service with lingering; macOS → LaunchAgent in the GUI session
(keychain access for the Claude login). If no session is logged in, the dispatcher starts the
satellite detached over SSH (
setsid/nohup; on Windows break away from the OpenSSH job object) without windows, and the app says so clearly. - The satellite owns one PTY per worker (Unix PTY / ConPTY via
portable-pty), keeps a bounded scrollback, feeds output to hang and limit detection, accepts input, streams to the app, and letsgitoodo attach <issue>(local orssh host gitoodo attach 42) attach; the most recently active viewer sets the terminal size. Workers keep running when SSH drops or the main host sleeps. - Delivery from a satellite (#582):
gitoodo worker push|prthere sends the assigned branch as a git bundle (commits beyondorigin/<base>, at most 16 MiB) over the satellite's subscribe connection (DeliverForward/DeliverDone, like questions). The main host checks that the satellite holds the issue's lease for exactly that branch, replays the bundle into a temporary bare repo, then pushes and opens the PR (Closes #n) with its own token through the same code as local workers, so gate and merge are identical. The token never leaves the main host. Failures (main host offline, no subscriber, push refused, no lease) are returned to the worker, logged and recorded as a refused activity entry; the lease and the worker stay, so the issue waits and delivery can be retried. - The main host runs the same PTY host locally.
- Auth: per forge one bot account with its own token, shared by all hosts; rights: issues, labels, comments, branches, PRs, merge to dev. No rotation inside the system.
12. Orchestrator chat#
- Claude Code headless in structured mode (
claude -pwithstream-jsoninput and output), rendered as a native chat in Gitoodo. Uses the user's existing Claude login. - Tools only through
gitoodo mcp; no file access, no shell (enforced via allowed tools). Its tools only read; every change below is a proposal the human applies with an OK in the app. - Can: create and sharpen issues (priority, OS, dependencies, several at once), query status, change priorities and boost, focus or pause projects, answer approvals and questions, stop or restart workers, set human labels. Cannot: write code, change repos, set service labels, merge.
- Lean context: reset at 10 % used context (default) with a handoff of fixed fields (goal, decisions, open points), stored locally in Gitoodo; the next session starts from the handoff.
13. Configuration (proposal)#
Shared settings.json (accounts, app mode, language, repo states) plus an orchestration file:
trusted authors, the orchestrator account per forge host (section 5.3.1), hosts (name, SSH target,
OS, worker limit, show windows, worktree root), global
limit, branch prefix, score weights, timers (hang 10 min, lease grace 30 min, reminder 2 h, sweeper
interval 1 h, polling 5 min), thresholds (Claude 90 %, free memory 1.5 GB), label name mapping,
release planning on/off per repo. Reloaded without restart, as today.
14. Quality requirements#
- Terminal fidelity: Claude Code must work in the PTYs as it does in a normal terminal. Acceptance tests on Linux, macOS and Windows: true colour, resize, full-screen UI, large paste (bracketed paste), Esc, Ctrl+C, Shift+Enter, Unicode/emoji width, scrollback, attach/detach without the session noticing.
- Resources: event-driven, near-zero idle CPU. Budgets as acceptance criteria:
gitoodo satelliteidle < 15 MB RSS, classifier and dispatcher < 30 MB each, scrollback 2 MB per session.crates/cli/tests/rss_budget.rschecks the resident set and, tighter, the private memory (LinuxRssAnon, macOS physical footprint) of debug builds in an empty home (#769). - Robustness: section 2.1 and the blockade tables.
- Single writer: classifier and dispatcher each hold an OS-level lock (lock file with
flock/LockFileEx) so that a second instance on the same host never writes to the forge. - Tests: table-driven tests for labels, trust (including reopening and foreign PRs), dependencies and cycles, score, host selection, leases and release scope; contract tests against recorded Forgejo and GitHub responses; terminal acceptance tests (above); RSS budgets as tests; end-to-end tests only against a dedicated Forgejo test repository, never a real project.
15. Migration plan (proposal; each step mergeable, the system stays usable in between)#
- Rename
gitoodo-cli→gitoodo, app binary →gitoodo-app. - English label catalog, question format v2, non-destructive activation preview, repo states.
- Split the daemon: classifier (+ read model on the socket); app direct/orchestrator mode.
- Dispatcher with local PTY host: push loop, worktrees, leases,
gitoodo ask, hang detection, auto-merge, sweeper. The former integration of the external orchestrator (doc, modules, UI, settings) was removed afterwards (done, #306). - Claude usage limits and status bar.
- Satellites:
host add, satellite service, SSH bridge, attach, optional windows. - Orchestrator chat (
gitoodo mcp, stream-json UI). - Release planning.
16. To verify during implementation#
- Forgejo: does
Closes #Nclose issues on merges into a non-default branch? Auto-merge API. - Native dependency APIs of Forgejo and GitHub.
- Claude Code: statusLine
rate_limitsfields,StopFailurehook,--settingsinjection, stream-json. - Stability of the OAuth usage endpoint; behaviour without a subscription (API key).
- ConPTY attach behaviour and resize on Windows; keychain access of a detached satellite on macOS.