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

For developers · Interfaces

Classifier daemon and command line

On this page
  1. Commands
  2. Classifier role and read model
  3. Queue writer and leases
  4. Label template and hygiene
  5. Shared configuration
  6. Tokens
  7. State
  8. Local access only
  9. Services
  10. Quitting the app and the services (#737)
  11. Open points
  12. Repository states and trust

gitoodo is the headless side of Gitoodo: the classifier daemon that polls the forges of the configured accounts and a command line that asks it for the queue picture. The app does not need it and works unchanged without it.

Commands#

gitoodo status [--changed] [--json] [--ack]
gitoodo service install|uninstall
gitoodo classifier
gitoodo next --worker session-1 --host win [--repo owner/repo] [--account id] [--json]
gitoodo done --worker session-1 --lease <id> [--result "PR ready"] [--json]
  • status prints one line per open issue and pull request of the covered repos, grouped like the lage picture: repo, issue#N / pr#N, status labels, age bucket, warnings, title, and a summary line at the end. Issues without status labels show [ohne Einordnung].
  • --json prints the whole reply (picture, changed, digest, polled_at, errors).
  • --changed prints nothing (unless --json) and exits 0 when the waking lines changed since the last --ack or an issue lacks status labels, 1 otherwise. --ack stores the current state as seen. Typical wake check: gitoodo status --changed && gitoodo status --ack.
  • Exit code 2: the daemon is not reachable. 64: wrong usage.
  • classifier runs the classifier daemon in the foreground; the service runs exactly this. daemon is a deprecated alias that runs the same thing and prints a note.

Classifier role and read model#

The classifier (spec section 6) polls every repository in state observed (read only), paused and active; repositories in state off are listed but never read. After each poll it builds a read model in memory and serves it to the app and the CLI over the local socket:

  • request {"cmd":"read_model"}, reply {"reply":"read_model", ...} with polled_at and per repository account_id, full_name, state and the open issues, highest score first. After a start the request waits up to two minutes for the first poll; {"cmd":"read_model", "immediate":true} answers at once instead (polled_at then is null and repos empty). The app always asks immediate and gives up after 15 s as busy, so a long first poll never keeps its views loading (read_model_now);
  • per issue: number, title, html_url, labels, computed readiness (ready, blocked, needs-clarification, needs-approval, needs-human, in-progress, in-review, stalled, held), dependencies (owner/repo#n), cycle, score and the lease holder if any;
  • readiness uses the dependency graph (open dependencies block, cycles and self-dependencies need clarification, unknown dependencies fail closed), the trust decision of section 5.3 and the label catalog; the score is the dispatcher order of section 7.1 with the weights of the score section of the orchestration config.

Request {"cmd":"poll"} (reply {"reply":"poll_scheduled"}) ends the wait between two polls; the app sends it after the user unlocked or granted a keychain token, so an account that waited for approval is read again at once. Each poll writes its errors to the activity file right before its poll record; rule notes such as "… more questions pending" go to the record's notes, never to labels_set.

The types and the client (ping, read_model, poll_now, request_at) live in gitoodo_core::service_rpc. The classifier idles at a few MB; an integration test keeps it under 30 MB RSS without accounts.

Queue writer and leases#

The daemon is the only Gitoodo process that writes status labels. next, done and label maintenance share one asynchronous lock, including their fresh forge reads. Run **one writer daemon per repository**; a second host must use that daemon, not start another writer for the same repository. An OS-held daemon.lock in the configuration folder prevents simultaneous writers for the same configuration, even during startup; the OS releases it after a crash.

Exactly one classifier runs per configuration (#593, #600):

  • While no service is registered, the app starts gitoodo classifier itself with its process id in GITOODO_PARENT_PID. That classifier (and a dispatcher the app starts) stops within two seconds once the app is gone (quit, crash, update), so the app leaves no orphan.
  • Once the classifier service is registered, the app starts only the service, and a classifier the app started stops by itself and hands over.
  • The service definitions set GITOODO_SERVICE=1. A classifier service whose lock is still held waits for it instead of exiting, so launchd or systemd do not restart it in a loop; it logs took over the classifier lock when it does.
  • Windows: the parent watch is Unix-only for now; the app's exit stops its children there. Worker identities live inside the local OS-user trust boundary; the dispatcher ([orchestrator/dispatcher.md](orchestrator/dispatcher.md)) is the only component that starts workers.

Enable repositories explicitly in <config>/orchestration.json (Gitoodo's own configuration):

{
  "repos": [
    {
      "account_id": "nas",
      "full_name": "owner/repo",
      "human": "maintainer-login",
      "releases": true
    }
  ],
  "lease_seconds": 14400,
  "profile": {
    "names": {},
    "extra_labels": []
  }
}

Missing configuration keeps the daemon read-only. Invalid configuration blocks mutations. Accounts must exist in settings.json; disabled repositories cannot be assigned. Maintenance runs during polling for enabled repositories, including those outside the dashboard view. next --repo selects an enabled, non-disabled repository. The daemon never edits the config.

next returns JSON with an assignment (or null when no work is eligible). An assignment contains the full issue and its lease: id, worker, host, account, repository, issue number, expiry and completion flag. Candidates must be open, carry only ready (legacy status:bereit), have no prd, needs-human (the legacy name an:mensch is not recognised), stalled or extern, and either have no host restriction or a matching host: label. For --host local a host: label matches this machine's name (orchestration.json › local_host.name, default the sanitised short host name), any of its local_host.aliases and local, without case — the same matcher as the dispatcher (docs/orchestrator/spec.md, 7.1 item 3). Satellites match only their own configured name. Lower priority numbers win, then earlier creation time, then configured account/repository order and issue number. Priorities are priority:p0..p3 (legacy prio:1..3); an issue without one counts as priority:p2.

Dependencies are issue references on lines containing Wartet auf, Blockiert bis, Abhängigkeit, noch offen, Depends on or Blocked by, in the body or comments. #12, repo#12, and owner/repo#12 are supported, including nested GitLab namespaces. Every referenced issue must be verifiably closed; inaccessible dependencies block assignment. Ordinary mentions and closing references are not dependencies.

Assignment adds in-progress before removing ready, assigns the forge account's authenticated login, then writes a gitoodo:lease v1 audit comment naming the worker and lease. Worker ids identify sessions, not forge logins. A partial or ambiguous failure leaves the reservation in place. done verifies the latest audit from the authenticated account, changes the status to in-review, removes the worker account's assignee and records the result. Repeating an already completed report has no further effects. Leases are reconstructed from forge comments after a restart; they do not depend on the volatile SQLite cache.

Rejected reports return JSON reply: "rejected" with a stable code and a human-readable message, exit status 1: foreign_lease, expired_lease, stale_lease, status_changed, invalid_worker, configuration_error or forge_error. Expiry is inclusive and never releases the issue automatically. Recovery of expired or partially assigned work is done by the dispatcher's sweeper or by an explicit human decision. A timed-out next may have taken effect; inspect the issue/audit before requesting more work.

Label template and hygiene#

The default profile embeds the English label catalog (priority:p0..p3, os:*, host:*, needs-clarification, blocked, ready, in-progress, in-review, stalled, needs-human, needs-issue-link, release:next). Legacy German or older English names (status:bereit, prio:1, an:mensch, ready-for-human) are no longer recognised (#464, #467); they only feed the activation preview, which renames them on the forge. profile.names keys are canonical catalog names. profile.names maps canonical names to your own names, for example {"ready":"Ready", "host:win":"Windows"}. All rules use those mappings, including classification, host filtering, status transitions and milestone allocation. Extra catalog labels use name, six-digit hex color, and description. Names must be unique; descriptions are limited to 100 characters for portability. Config is reloaded on every poll and work request. The API contracts follow the GitHub label schema, GitLab label ownership/filtering, and GitLab milestone states.

Enabling a repository transfers its label catalog to Gitoodo: missing labels are created, colors/descriptions corrected. Labels outside the catalog are never deleted automatically. Stop the former label-sync job for these repositories so there is only one writer.

The daemon performs the label and milestone rules of label-sync:

  • No classification labels (typ:*, schwere:*, release:muss/später, einordnung:fehlt, status:neu) are set or read any more (#567); existing ones are left alone.
  • Keep the most advanced status (review, in progress, blocked, ready; none = waits for the intake); parents (prd) carry no status. Closed issues lose status and human-question labels.
  • Assign pending human questions, detect an answer in the last human-authored comment, set no label is set (the last comment is the answer), and release the human assignee. Active worker assignments are preserved.
  • Lift blockades when all named dependencies are closed. An unexplained blockade returns to ready, or new when classification is missing. needs-human and extern remain blocked.
  • Allocation goes to one open milestone: with several open, the earliest due date wins, else the lowest version in the title (numeric), else the oldest. A tie on due date and version skips the allocation with a logged reason; the multiple-milestones finding is reported either way. Allocate required release items and follow-ups of items already in it (unless deferred). Existing open milestone assignments stay.
  • Remove closed milestones from open issues with an audit comment, returning them to backlog.
  • With no open milestone, create one release-planning issue; keep the old label-sync marker and honor its 28-day snooze after closing. releases: false disables this planning rule.

Only explicitly enabled repositories are maintained. The former Forgejo-admin notification cleanup and impersonated unsubscribe operations are not label/milestone rules and are not performed; Gitoodo does not need an administrator token.

Shared configuration#

App and CLI use the same folder (gitoodo_core::paths::config_dir) and the same settings.json: accounts, poll interval, disabled repos and the first "agent dashboard" view (its accounts and repos; without one, every repo of every account). The daemon reads the settings again before every poll, so changes in the app apply without a restart. The poll interval is valid from 30 to 900 seconds; a stored value outside that range (only possible by editing settings.json by hand) is clamped silently to the nearest bound, and the app shows the effective value.

ConfigState and socket
Linux$XDG_CONFIG_HOME/de.gitoodo.app$XDG_STATE_HOME/de.gitoodo.app, socket $XDG_RUNTIME_DIR/gitoodo/daemon.sock
macOS~/Library/Application Support/de.gitoodo.app~/Library/Caches/de.gitoodo.app, socket in it
Windows%APPDATA%\de.gitoodo.app%LOCALAPPDATA%\de.gitoodo.app, pipe \\.\pipe\gitoodo-<user>

GITOODO_CONFIG_DIR and GITOODO_STATE_DIR override both folders (tests, several setups on one machine). A Unix socket path must stay below about 100 bytes.

Tokens#

Tokens are never written to a file by Gitoodo. The daemon asks these sources in order, per account:

  1. systemd credential gitoodo-token-<id> in $CREDENTIALS_DIRECTORY (read-only, set by the service manager through LoadCredential= or SetCredentialEncrypted=),
  2. environment variable GITOODO_TOKEN_<ID> of the service environment (no systemd, or a different supervisor),
  3. a token kept in memory (set while no system store is usable; lost on restart),
  4. the system keyring the app uses (macOS Keychain, Windows Credential Manager, Secret Service).

Names derive from the account id: the credential is gitoodo-token- plus the id in lower case, the variable GITOODO_TOKEN_ plus the id in upper case; every character other than a letter or digit becomes - (credential) or _ (variable). Account gitea-nas.1 reads credential gitoodo-token-gitea-nas-1 or variable GITOODO_TOKEN_GITEA_NAS_1. Surrounding whitespace in the value is ignored.

On Linux the Secret Service is used only when it answers without a dialog: a locked or missing keyring (no unlock prompt, 2 s limit, rechecked every minute) is skipped, never blocks startup, and tokens set meanwhile stay in memory. macOS and Windows always use their keychain.

Headless setup with encrypted credentials, as a drop-in (systemctl --user edit gitoodo):

[Service]
LoadCredential=gitoodo-token-nas:%h/.config/gitoodo-credentials/nas
# or encrypted: SetCredentialEncrypted=gitoodo-token-nas: <output of systemd-creds encrypt>

The credential file belongs to you (mode 0600), not to Gitoodo, which never creates it. A user unit needs systemd 250 or newer for LoadCredential=. Without systemd, set the variable in the manager's memory, for example systemctl --user set-environment GITOODO_TOKEN_NAS=….

gitoodo doctor prints the active sources, for example secret backend (daemon): systemd credentials; system keyring locked, skipped or memory only (no system store, tokens are lost on restart). It asks the running daemon, because only its service environment holds the credentials directory; without a daemon it reports what the calling process sees.

State#

The daemon keeps the last snapshot per repo and the acknowledged digest in <state>/daemon.sqlite. It is not a source of truth: a missing, corrupt or older file is deleted and created empty, and the next poll fills it from the forge. Deleting it while the daemon runs is noticed at the next poll. Only --ack is lost then, so the next --changed reports a change.

Local access only#

The CLI talks to the daemon over one JSON line each way, never over TCP:

  • Unix: socket with mode 0600 in a folder with mode 0700, owned by the user.
  • Windows: named pipe with the default security of the creating user, remote clients refused.

Services#

DefinitionRestartAfter reboot
Linux~/.config/systemd/user/gitoodo.serviceRestart=alwaysWantedBy=default.target and lingering (loginctl enable-linger)
macOS 13+login item of the app: Gitoodo.app/Contents/Library/LaunchAgents/de.gitoodo.app.daemon.plist, registered with SMAppServiceKeepAliveRunAtLoad at login
macOS 11/12, dev~/Library/LaunchAgents/de.gitoodo.app.daemon.plistKeepAliveRunAtLoad at login
Windowsscheduled task Gitoodo\DaemonRestartOnFailurelogon trigger

As a login item the service runs the program inside the app bundle (the service helper when the build has it); an app update is a service update, and the app restarts the running services on the new program at its next start. Login items appear under System Settings › General › Login Items; when macOS waits for approval there, the setup and /doctor open that pane. Elsewhere the service starts the binary at the path from which service install ran (the stable copy, #355); install again after moving it. Older plist agents move to login items once at app start (permissions, "Login items"). The service writes classifier.jsonl in the log folder (logging); stderr goes to the journal (journalctl --user -u gitoodo), on macOS to classifier.stderr.log there. gitoodo doctor prints how each service is registered.

Quitting the app and the services (#737)#

"Quit" in the tray or the app menu (Cmd+Q) asks while a service runs or is about to be restarted: quit the app and keep the services working, quit everything, or cancel. "Don't ask again" stores the answer as quit_services (ask, keep_running, stop_all), changeable under Settings › General › When quitting. Signing out or shutting down never asks. The decision and the service control live in crates/core/src/service_control.rs.

"Quit everything" stops each service for real, so neither the restart rule nor the next sign-in brings it back, and checks afterwards that it no longer runs:

PlatformStop until the next app startBack at the next app start
macOSlaunchctl disable gui/<uid>/<label>, then bootoutenable, bootstrap gui/<uid> <plist>, kickstart; a login item: enable, SMAppService.register()
Linuxsystemctl --user disable --now <unit>systemctl --user enable --now <unit>
Windowsschtasks /Change /TN <task> /DISABLE, then /End/Change … /ENABLE, then /Run

At start the app brings stopped services back in orchestrator mode (service_control::services_wanted) and never stops a running one. Whether the orchestrator dispatches is its on/off switch, paused in the control state (#735): the dispatcher reads it before every round, so with the switch off the services keep running, answer the status and dispatch and notify nothing. The quit dialog and the status window read that through the one run-state rule (runStateOf), the tray through human_control::is_paused: "Services running in the background" (or "Services running, orchestrator off") with "Stop services", and the status window lists each service as running, restarting, stopped or off until the next start. Store builds have no services and quit without asking.

Open points#

  • macOS and Windows services are implemented but not yet proven on a device.
  • Windows runs a per-user scheduled task, not a service of the service control manager (that would run without the user's keychain); the pipe uses the default DACL, not a dedicated one.
  • The sandboxed Mac App Store build keeps its config in the container; a CLI outside it needs GITOODO_CONFIG_DIR pointing there.
  • PR labels are not part of the forge's pull status yet, so PR lines show checks and merge state only. The lage sections on hosts and workers are not part of the picture.

Repository states and trust#

RepoState per repository: off (not polled), observed (read only: no labels, comments or other forge writes), paused (writes, no dispatch) and active (writes and dispatch). A repo listed in orchestration.json without state is active (the behaviour before the field existed), an unlisted repo is observed, and settings.json disabled_repos means off.

orchestration::trust::decide implements the trust rule (spec 5.3) as a pure function: maintainers (admin/maintain/write), the own bot and trusted_authors are trusted; a reopen by a trusted actor is an approval, a reopen by anyone else asks again; untrusted pull requests never auto-merge. The classifier applies it when it computes readiness. orchestration::activation::activation_preview lists which existing labels are mapped, which catalog labels would be created and which stay untouched. Nothing is deleted automatically. label_cleanup lets the user delete leftover labels (no catalog entry) from the preview, one or all at once: access checks the right to manage labels (the role in the repo and the token's missing scopes), usage counts the issues and pull requests per label for the confirmation, and delete makes one forge call per label after re-reading the repo's labels, refuses catalog names and reports an error per label while the others continue (Forgejo/Gitea, GitHub, GitLab).

Docs version: dev