Configuration

Detent has two configuration layers:

• global.yaml selects projects and controls host-wide runtime settings.
• Each project has a checked-in detent.yaml machine contract, with optional machine-local overrides in detent.local.yaml. The project contract can also live in legacy WORKFLOW.md YAML frontmatter.

This page is the single reference for both configuration layers. Project configuration is documented below after the host-wide settings.

Host configuration

At startup, Detent resolves global.yaml in this order. The first matching rule wins.

os.UserConfigDir() maps to %AppData%\detent\global.yaml on Windows, ~/Library/Application Support/detent/global.yaml on macOS, and ~/.config/detent/global.yaml on Linux while honoring XDG_CONFIG_HOME.

DETENT_CONFIG and DETENT_HOME remain deprecated fallbacks for one release. Detent uses CONFIG_HOME instead of HOME because HOME is standard process state, not Detent configuration.

If no global config is found, Detent keeps the single-project fallback and looks for WORKFLOW.md in the current working directory. Use detent config path to print the resolved config path and the rule that selected it.

Runtime settings resolve in this order: explicit flag, environment variable, global.yaml, then built-in default.

The web host resolves from --host, then the first registered workflow's server.host, then the built-in 127.0.0.1 default. It is not a top-level global.yaml key.

Use github_token: gh in global.yaml to resolve the token from gh auth token at startup. Literal token values also work but should not be committed. github_token: gh-auth, ${gh auth token}, and $(gh auth token) are accepted aliases. If neither GITHUB_TOKEN nor github_token is set, Detent falls back to existing per-workflow tracker.api_key handling.

Set trust_loopback_peer_read: true to grant tokenless read-scope API access to direct loopback TCP peers even when Detent binds a non-loopback address or has an api_token. The setting hot-reloads and applies only to GET routes; admin routes and mutations still require credentials. Authentication uses only the request's direct peer address and never trusts forwarded-client headers. Do not enable this setting when a reverse proxy runs on the same host: every request relayed by that proxy has a loopback direct peer, including requests that originally came from remote clients.

Use instance_name to distinguish browser tabs and the dashboard navbar when several Detent instances are open at once. Detent resolves the display name from the first non-empty value in this order: top-level instance_name in global.yaml, global.identity.name, the short hostname, then empty. In single-project fallback mode without global.yaml, workflow top-level identity.name is used before the short hostname. Names are trimmed, must be a single line, and are capped at 40 characters in the web UI.

Automatic update checks are host-specific and disabled by default. When enabled, Detent persists the last check and schedules the next jittered check from that timestamp, so restarts preserve the remaining delay and overdue checks run promptly. The six-hour default keeps release uptake within the same day while using about four GitHub requests per host per day. Detent reports the last check, available or applied version, and next check on /health and the Health dashboard. detent doctor surfaces the last and next check times, reports whether the host is opted in, and suggests enabling checks when it is not. Automatic apply remains off unless explicitly enabled and only replaces release-installer binaries; other install sources remain notification-only. When work attempts are active, Detent shows the pending version in the web and terminal dashboards and waits for the next fleet-wide idle window before applying it. An operator can instead confirm immediate apply from the web notification. A successful apply uses the normal graceful drain path, then re-executes the replaced binary on POSIX systems or exits cleanly for an external supervisor to restart it on other platforms.

detent doctor prints the resolved runtime values and their sources, with the GitHub token redacted.

Choose a starting point

• config.example.yaml is the smallest working project config.
• config.annotated.yaml is a realistic GitHub setup with explanations beside each deliberate choice.
• config.reference.yaml contains every supported project key. It is fully commented so you can copy only what you need.

Keep detent.yaml portable and checked in. Put machine-specific paths or secrets in detent.local.yaml, a credential reference, or host configuration. The local file overlays the shared file recursively and is not a second, independent configuration.

How the subsystems fit together

Identity, tracker, and polling

identity names the Detent persona that owns work. tracker connects that persona to GitHub, Linear, an embedded SQLite board, or the in-memory tracker. The tracker declares active, observed, and terminal workflow states; state maps, transition automation, admission, planning, stop behavior, and routing all refer back to those names. polling controls how often Detent refreshes the tracker when no event gives it a fresher signal.

Choose exactly one GitHub status source: ProjectV2, the repository issue Status field, or repository labels. dependency_auto_unblock, blocked_recovery, and blocker_auto_promote are opt-in tracker automations: the first advances work whose dependencies cleared, the second revives agent-recoverable PR maintenance, and the third promotes blockers when they enter configured states.

Workspace, deliverable, and worker placement

workspace controls isolation, source and output roots, branch creation, cache sharing, and cleanup. deliverable selects pull requests or file artifacts and their review destination. worker distributes sessions across optional SSH hosts; per-state and global concurrency limits remain under agent.

workpad.structured_only requires machine-readable workpad status instead of accepting legacy narrative signals. dependencies.source chooses whether native tracker dependencies, merged pull requests, or both determine readiness.

Agents, backends, and routing

agent is the orchestration policy: concurrency, turn and session limits, retry brakes, spend limits, shutdown, dispatch priority, automatic promotion, state-specific instructions, learned context, skill drafts, and follow-up work. agents.backends defines pluggable Codex or Claude Code processes, while agents.routes selects a backend and model by role or issue selector.

codex is the legacy/default Codex backend configuration and remains the fallback when agents.backends is empty. A Codex backend inherits omitted values from it. Claude Code backend options are interpreted only when the backend kind is claude_code.

agent.auto_promote and gate work together. Auto-promotion decides when an item may leave its source state; the gate decides whether CI, automated review, human approval, a validator, or an artifact status is sufficient. plan optionally inserts a plan-review stop before implementation.

Operations, budgets, and observability

server controls the project dashboard bind and Kanban mutation policy. active_hours optionally limits new agent dispatches to recurring weekday and wall-clock spans in a required IANA timezone. Use window values such as Mon-Fri 22:00-06:00; ranges that end before their start wrap past midnight, and 00:00-24:00 covers a full day. A project entry in global.yaml overrides global.active_hours, and either host-local value overrides the project's checked-in setting. Window close drains existing agents instead of stopping them.

Detent evaluates membership on each scheduler tick, preserving local wall-clock hours through daylight-saving changes and restarts. Spring forward can shorten a wrapping window by one hour, while fall back can lengthen it by one hour. detent doctor previews opening and closing times in both the named timezone and UTC. A temporary detent resume <id> --for <duration> override admits work outside the window until its persisted expiry; manual pause remains the stronger, independent gate.

observability controls dashboard refresh, efficiency anomaly thresholds, and optional OTLP export. budget is the project-wide spend policy; agent.budget can further constrain agent sessions. release enables release-readiness automation after merged work accumulates.

observability.stranded_active_threshold_seconds controls when Health and detent doctor report an issue that remains in In Progress without a live worker while project capacity is available. The default is 600 seconds, which tolerates normal gaps between a completed session and prompt re-dispatch.

hooks run lifecycle commands around worktree creation, agent execution, and cleanup. Treat them as trusted code: they run with the Detent process permissions and should be short, deterministic, and safe to retry.

Intake, retrospectives, routines, and admission

intake.sources turns webhook or scheduled external signals into tracker items. retro periodically mines completed work for recurring operational lessons. routines schedules arbitrary agent prompts against supported trackers.

backlog_admission is an opt-in scheduled pass that evaluates items from configured source states against a named criteria section in WORKFLOW.md, then proposes a bounded number for a target state. Its five-field cron, source-state membership, distinct target state, tracker support, and positive run limits are enforced by the same validators that feed the generated table below. When require_effort is enabled, effort_section names a separate project-owned WORKFLOW.md rubric whose bold or code-formatted list items define the allowed recommendations. Detent writes a recommended detent-agent block before the admission transition only when the issue has no existing block; the default remains disabled for compatibility.

When enabled, admission defaults to */15 * * * *, which limits normal candidate wait time to 15 minutes. An every-30-minute schedule implies up to 30 minutes of latency, an hourly schedule up to one hour, and a daily schedule up to 24 hours. Restricting a daily schedule to weekdays creates a 72-hour weekend gap. A slow schedule is valid, but it can make admission look broken because issues accumulate in the source state while Detent is simply waiting for the next run.

On the host used to establish the default, 20 admission runs and 18 admission agent sessions averaged about 25 seconds of wall time per run and 36,000 tokens per candidate-bearing run, with 655,368 tokens total. Runs with no eligible candidates are cheaper because they do not start an admission agent. At the 15-minute default, there are at most 96 runs per day; use detent doctor to compare your schedule with recent candidate-bearing runs and the runtime and token cost observed on your own host. Choose a slower explicit schedule when that latency/cost tradeoff is intentional.

Fleet staleness warnings

observability.staleness detects work items that exceed lane-specific aging thresholds, non-empty dispatch or merge queues that stop advancing, and repeated identical scheduler decisions. Human-gate lanes remain warnings rather than failures, so they provide a single durable reminder without treating a deliberate review wait as an unattended stall.

The repeated-decision detector considers only current, non-terminal items. Closed and merged items and items in a configured terminal state are excluded. observability.staleness.repeated_decision_benign_reasons lists scheduler reasons that represent healthy waits rather than operator-actionable stalls. Its defaults cover active workers, dependency waits, global-capacity waits, and GitHub REST pacing. Set the list explicitly to replace those defaults for a project.

The detector evaluates decisions inside observability.staleness.repeated_window_hours, but the orchestrator retains only the 500 most recent scheduler decisions. Its effective history is therefore whichever is smaller: the configured time window or the retained 500-decision sample.

Warnings appear in the dashboard, /health, and detent doctor. Configure observability.staleness.webhook.url to push each newly active warning as a detent.staleness.warning JSON event. The payload includes a stable warning ID, the affected project or item, the reason, and age and threshold values in seconds. A delivered warning is not sent again on every scheduler tick.

Generated field reference

The generated block reflects the YAML-tagged Go structs reachable from the project config. It reads effective defaults through the real normalization path and derives validation text by exercising boundary values through the real loader and validators. “None” means no field-level rule was surfaced; subsystem interactions can still constrain a value.

Run go generate ./... after changing the config structs, defaults, or validators. make check compares the committed generated artifacts with fresh rendering and fails on drift.