Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Orchestrator

Gitoodo Orchestrator – Specification (v1)

On this page
  1. 1. Goal and scope
  2. 2. Principles
  3. 2.1 The system never blocks itself
  4. 2.2 Facts and labels
  5. 3. Architecture
  6. 3.1 Components
  7. 3.2 Communication
  8. 4. The app
  9. 5. Ledger: labels, questions, trust
  10. 5.1 Label catalog
  11. 5.2 Manually set labels (not by the bot account)
  12. 5.3 Trust and approval
  13. 5.3.1 Orchestrator account (#764)
  14. 5.4 Question format v2
  15. 5.4.1 Routing and forwarding (#704)
  16. 5.5 Dependencies
  17. 5.6 Activating a repository
  18. 5.7 Human control (#568)
  19. 6. Classifier
  20. 7. Dispatcher
  21. 7.1 Loop (push model)
  22. 7.2 Branches and worktrees
  23. 7.3 Session environment
  24. 7.4 Hang detection (v1)
  25. 7.5 Questions (gitoodo ask)
  26. 7.6 Leases and dead workers
  27. 7.7 Claude usage limits
  28. 7.8 Pull requests and merge
  29. 7.9 Blockade table (proposal)
  30. 8. Workers
  31. 8.1 Contract
  32. 8.2 Prompt template (proposal)
  33. 8.3 gitoodo ask
  34. 9. Sweeper
  35. 10. Release planning (optional per repo)
  36. 11. Satellites
  37. 12. Orchestrator chat
  38. 13. Configuration (proposal)
  39. 14. Quality requirements
  40. 15. Migration plan (proposal; each step mergeable, the system stays usable in between)
  41. 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#

  1. 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.
  2. 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.
  3. 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).
  4. Failures stay small: a problem affects one issue or one host, never the whole queue.
  5. 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#

NameBinary / commandJobNot responsible for
Gitoodo (app)Gitoodo.app (binary renamed internally to gitoodo-app)GUI, orchestrator chat, questions, statushosting services, writing service labels
Classifiergitoodo classifierreadiness, dependencies, PR links, answer detection, release planningstarting workers, merging
Dispatchergitoodo dispatcherassigning issues, starting/stopping sessions, limits, hang detection, PR auto-mergeclassification labels, writing code
Sweepergitoodo sweeperremoving merged branches and worktreesdeleting unmerged work
Askgitoodo aska worker's question to the humanwaiting for the answer
Satellitegitoodo satellitehosts worker PTYs and the sweeper on a remote hostscheduling
MCP servergitoodo mcpthe chat's toolsfile or shell access
Attachgitoodo attach <issue>view/interact with a running session in any terminal–
Workera Claude Code session (no own binary)one issue, one worktree, PRlabels, other workers, merging to main
Forge adapterlibrary in gitoodo-coreuniform API for Forgejo and GitHubbusiness logic
LedgerForgejo or GitHub (exactly one forge per project, configured per repo)issues, labels, PRs, milestones, branch protectionrunning services
  • One program gitoodo with subcommands; each service runs as its own process and system service, started and stopped independently. Today's gitoodo-cli becomes gitoodo.
  • Shipping (#355): the direct-distribution app bundles the CLI as a Tauri sidecar (bundle.externalBin, overlay src-tauri/tauri.sidecar.conf.json, built by scripts/build-sidecar.sh). Installing copies it to a stable per-user folder (paths::bin_dir, GITOODO_BIN_DIR overrides) and registers classifier and dispatcher there as system services with automatic restart (launchd KeepAlive, systemd Restart=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 (store feature) 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: observed reads as off, paused as on + paused, active as 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 of AGENTS.md in 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)LabelOwnerMeaningSelf-healing
1 Placement: where and how urgent?priority:p0…p3classifier, humandispatcher order. p0 now, p1 next, p2 normal, p3 some daymissing → p2
os:windows / os:macos / os:linuxclassifier, humanOS the worker must run onmissing → any host; no matching host online → waits visibly, notify
host:<name>human (optional)pins an issue to one hosthost offline long → notify
2 Readiness: may it start?needs-clarificationclassifiercontradiction (dependencies, PR link); starts a clarification workerclarification fails → needs-human
blockedclassifieran open dependencylifted when all dependencies are closed; cycle → needs-clarification
readyclassifiermay be worked on (see 5.3)unanswered approval blocks this issue and its dependents, visibly
3 Workflow: what is happening?in-progressdispatcherreserved, prevents double assignment, shows who works on itsee 7.6
in-reviewdispatcherPR open, auto-merge to dev enabled, waiting for green CICI red / conflict → new session; no movement → notify
stalleddispatcherstill failing after 3 restartsblocks this issue and its dependents, waits for the human
4 Human: is something waiting for you?needs-humanquestion mechanism: whoever asks via gitoodo ask sets it; answer detection (classifier) removes itworker question, approval or clarification; the kind is in the question blockdeadline in the block, reminder (section 4)
5 Pull requests: is the PR clean?needs-issue-linkclassifierPR without issue; merge blocked by a failing status checklifted once the link is unambiguous
6 Release (optional)release:nexthuman (also via chat)scope of the next releasesee section 10
7 Marker (no question)gitoodoclassifierteal #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 groupmissing → 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.

  • ready by hand = approval; dependencies still win.
  • blocked by hand without a dependency fact = deliberate hold until the human removes it; the classifier comments once.
  • needs-clarification by 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's human, the logins in trusted_authors (own bot accounts), everyone with write access and the members of the organisation owning the repo (Forgejo/Gitea and GitHub orgs/{org}/members/{login}; GitLab's inherited group members already count through the member level). The settings show this list next to the editable trusted_authors.
  • Others get an approval question (needs-human, kind approval). 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 through answer_question in 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) the needs-human label 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 (new default, ready, ask) with adopted_at. With new, items opened before adopted_at are 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's human, 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 is ready. 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:fehlt is 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.json may name the account the orchestrator acts as: orchestrator_accounts maps 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_authors once (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's human, 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_done ends 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 in orchestrator_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 answered label.
  • 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 ask addresses a worker's question to the first rule whose label the issue carries (any case), else to the repo's human, 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-human and stays assigned to them; the answer may come from the repo's human or 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 (also repo#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.json in the state dir, paused): while on, the classifier writes nothing (reconcile is empty, the Writer hands out no assignment) and the dispatcher starts nothing and merges nothing. It survives restarts; resuming continues where it stopped. The tray item control-pause and the commands control_get / control_set_paused toggle it. Pausing also stops every running worker (the lease is released, the in-progress label removed, the issue is not flagged needs-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-progress labels (Flag::Release over the classifier RPC removes only in-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 gets needs-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 with activity_forge_writes.
  • Alerts (activity/alerts.jsonl): the dispatcher emits question, stalled, merge_failed (with a cause category, deduplicated per pull) and merge_vetoed events; the app polls control_alerts and shows them through notify::show. Event control-changed carries the new control state.

6. Classifier#

  • Polls (or receives events for) all repos in observed (read only), paused and active; writes only in paused and active. 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; observed repos 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) becomes ready when 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 labels ready by hand. Block ids intake-approval-N, intake-clarify-N.
  • Answer detection → removes needs-human, sets ready (worker questions: the issue continues on its branch, section 8.3). It runs in every repo: without a repo human or 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 happenEffectHandling
classifier crashedanswers not detected, blocks not liftedsystem service restarts it; app shows error; dispatcher keeps assigning ready issues
forge unreachablenothing updatesretry with growing backoff, visible; full reconcile afterwards
forge API limitrequests rejectedwait until the reset the forge reports; active repos first
catalog label deleted/renamed on the forgelabels missingrecreated next run
contradictory labelsunclear readinessrecompute own group from facts; never touch other groups
in-progress without valid leaseissue reserved foreverdispatcher's group; it removes it after the lease check
human "answers" with a non-answerworker starts without answerworker asks again; bounded because each question needs the human
question stays unansweredissue and dependents waitvisible, 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.

  1. Triggers: a slot frees up (worker done, question asked, worker ended), a forge change, an interval.
  2. Candidates: see 5.1.
  3. 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: its os: (macos, linux, windows; darwin/win accepted) and host:<name> labels form the constraint. A host: 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. mac for Mac.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 always local. 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's next. Internally the machine stays the host id local, so leases and worker lists do not change when it is renamed. A satellite may not take one of these names (local_name error), 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 (the host: label names no host), os_mismatch (no host has the os:), offline, agent_missing (coding agent missing or signed out), usage_gate, low_memory, at_capacity or global_limit. The reason is written to host-wait.json and the read model (host_wait.reason), logged once per new wait or changed reason as dispatch.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 unknown host: 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 lists host: 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, explains host: labels and offers the alias for each unknown label once the read model has them.
  4. 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 score weights in its repos entry (#569); without one the global score applies. Editable in the repo detail (Settings › Repos).
  5. Assign: set in-progress, write the lease audit comment, create or continue branch and worktree, start the session (section 8).
  6. 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 default gitoodo (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's worker_permissions is guarded (--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/StopFailure hooks that call gitoodo (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-human open 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 and Retry-After; (3) the StopFailure hook (≥ 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; see dispatcher.md).
  • Required checks per repo (#569): repos[].required_checks lists 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 #N acts 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) or gitoodo 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 happenHandling
dispatcher crashedsystem service restart; on start reconcile leases from forge audit comments
satellite unreachableits issues: lease grace period, then release; no new work there; notify
worktree corrupt / git lock left overrecreate 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 forgedispatcher merges itself when CI is green
issue edited while in progressworker 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 --label when 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:next by 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, else v0.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 legacy release: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): copy gitoodo over SSH/SFTP into a versioned directory, verify the checksum, start gitoodo 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 lets gitoodo attach <issue> (local or ssh 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|pr there sends the assigned branch as a git bundle (commits beyond origin/<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 -p with stream-json input 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 satellite idle < 15 MB RSS, classifier and dispatcher < 30 MB each, scrollback 2 MB per session. crates/cli/tests/rss_budget.rs checks the resident set and, tighter, the private memory (Linux RssAnon, 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)#

  1. Rename gitoodo-cli → gitoodo, app binary → gitoodo-app.
  2. English label catalog, question format v2, non-destructive activation preview, repo states.
  3. Split the daemon: classifier (+ read model on the socket); app direct/orchestrator mode.
  4. 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).
  5. Claude usage limits and status bar.
  6. Satellites: host add, satellite service, SSH bridge, attach, optional windows.
  7. Orchestrator chat (gitoodo mcp, stream-json UI).
  8. Release planning.

16. To verify during implementation#

  • Forgejo: does Closes #N close issues on merges into a non-default branch? Auto-merge API.
  • Native dependency APIs of Forgejo and GitHub.
  • Claude Code: statusLine rate_limits fields, StopFailure hook, --settings injection, 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.
Docs version: dev