For developers · Interfaces
Classifier daemon and command line
On this page
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]statusprints one line per open issue and pull request of the covered repos, grouped like thelagepicture: 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].--jsonprints the whole reply (picture,changed,digest,polled_at,errors).--changedprints nothing (unless--json) and exits 0 when the waking lines changed since the last--ackor an issue lacks status labels, 1 otherwise.--ackstores 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.
classifierruns the classifier daemon in the foreground; the service runs exactly this.daemonis 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", ...}withpolled_atand per repositoryaccount_id,full_name,stateand 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_atthen isnullandreposempty). The app always asksimmediateand gives up after 15 s asbusy, so a long first poll never keeps its views loading (read_model_now); - per issue:
number,title,html_url,labels, computedreadiness(ready,blocked,needs-clarification,needs-approval,needs-human,in-progress,in-review,stalled,held),dependencies(owner/repo#n),cycle,scoreand theleaseholder 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
scoresection 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 classifieritself with its process id inGITOODO_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 logstook over the classifier lockwhen 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-humanandexternremain 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-syncmarker and honor its 28-day snooze after closing.releases: falsedisables 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.
| Config | State 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:
- systemd credential
gitoodo-token-<id>in$CREDENTIALS_DIRECTORY(read-only, set by the service manager throughLoadCredential=orSetCredentialEncrypted=), - environment variable
GITOODO_TOKEN_<ID>of the service environment (no systemd, or a different supervisor), - a token kept in memory (set while no system store is usable; lost on restart),
- 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#
| Definition | Restart | After reboot | |
|---|---|---|---|
| Linux | ~/.config/systemd/user/gitoodo.service | Restart=always | WantedBy=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 SMAppService | KeepAlive | RunAtLoad at login |
| macOS 11/12, dev | ~/Library/LaunchAgents/de.gitoodo.app.daemon.plist | KeepAlive | RunAtLoad at login |
| Windows | scheduled task Gitoodo\Daemon | RestartOnFailure | logon 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:
| Platform | Stop until the next app start | Back at the next app start |
|---|---|---|
| macOS | launchctl disable gui/<uid>/<label>, then bootout | enable, bootstrap gui/<uid> <plist>, kickstart; a login item: enable, SMAppService.register() |
| Linux | systemctl --user disable --now <unit> | systemctl --user enable --now <unit> |
| Windows | schtasks /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_DIRpointing there. - PR labels are not part of the forge's pull status yet, so PR lines show checks and merge state
only. The
lagesections 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).