Status-driven agentic orchestration · one Go binary

Manage work, not agents.

You mark an issue Todo. Detent claims it, runs it against the contract you checked in, and moves it between the states your workflow defines, holding it wherever you put a gate. Every issue it manages sits at a named state on the board.

You are not steering an agent; you are running your own engineering process at scale.

brew install digitaldrywood/tap/detent

View on GitHub Other platforms

No signup. No hosted plan. v0.114.50 · MIT · you bring the model cost.

composed snapshot 2 working 1 held at gate 785 merged, all time tokens · budget · rate limit — all on the dashboard

Todo 2

#1626 detent

feat(admission): surface pending proposals

#1619 detent

feat(health): surface stranded active work

In Progress 2

#1614 detent

chore(safety): guard dispatch capacity paths

agent working

#1611 detent

fix(scheduler): clean orphan cycle state

make check running

Human Review 1

#1585 detent

fix(orchestrator): add token progress brake

held at the gate

the detent —
released only by you

Rework 1

#1593 detent

fix(board): collapse staleness warnings

2 threads unresolved

Merging 1

#1628 detent

docs(cli): refresh version output example

rebased, CI watch

Done 785

#1624 detent

test(project): relax watcher deadlock guard

merged, green

The six lanes shown come from Detent's own production configuration, not a fixed product state model; each workflow defines its own states. This is not a live board: the issue numbers and titles come from real merged work in digitaldrywood/detent, composed across the path for this illustration. The counts describe the illustration; 785 is the all-time landed pull requests on that repository. Non-code workflow example →

02 · Lineage

Symphony named the thesis. Detent shipped the system.

"Manage work, not agents" is OpenAI Symphony's phrase. Detent grew out of that open spec and took the idea from spec to a shipped system.

What Symphony opened

Symphony is an Apache-2.0 SPEC.md plus an Elixir reference implementation that polls a Linear board.

openai/symphony ↗

What Detent built from it

One binary. One CGO-free Go binary for macOS, Linux, and Windows, with no BEAM service to stand up.
GitHub-native state. ProjectV2, boardless issue-field mode, boardless label mode, or the github_local hybrid mode keep the work in GitHub's issue and pull request ID space.
Fleet scheduling. Multiple projects from one host, with weights, priority, pause, and fair scheduling.
Configurable gates. Configurable gates plus a serialized merge train that validates the exact commit about to land.
Operator surface. A dashboard, terminal UI, detent doctor, cross-platform config discovery, and a GoReleaser pipeline.

Detent began as an Elixir/OTP implementation adapted from Symphony's Linear target to GitHub Projects v2. It is now a ground-up Go rewrite; that earlier implementation is archived.

03 · Definite states

A detent makes position definite.

A detent is the catch that holds a moving part at a defined position until it is deliberately released: the click-stop on a dial, the notch on a ratchet. It does two things at once. It resists movement out of a position, and it makes the set of positions definite. Detent is named for the second one.

Where is it?

Autonomy-first: You steer a session and course-correct when it drifts.
Detent: At a state your workflow defines, on the board, in GitHub.

What is it waiting on?

Autonomy-first: Whatever you tell it next.
Detent: The promotion condition you configured. That can require a linked open PR, green CI on the current head, an automated review, a quiet period, or a human approval label.

Who moves it?

Autonomy-first: You, by talking to the agent.
Detent: The runtime when the condition is met, or you by changing the state.

The board above and the lane rail below are the visible form of the claim: managed work sits at a state the workflow defines, rather than somewhere inside a session you have to read to locate.

Why the name ↗ Promotion conditions →

04 · The inversion

A system, not an agent.

Autonomy-first tools put the intelligence in the agent and ask you to supervise it. Detent puts the intelligence in your spec and supplies the discipline. Same task, two interaction models.

“add OAuth token rotation” — autonomy-first assistant

It starts as a prompt. The agent picks a plan.
You read the plan and inspect partial edits.
It misses the migration. You redirect.
It skips the tests. You redirect again.
You are the supervision loop.

“add OAuth token rotation” — Detent

It starts as an issue naming the storage change, CLI behavior, migration, rollback, and tests.
A worker executes that contract in an isolated worktree.
It produces a reviewable pull request.
It does not merge until your gates are green.
Your process runs. You read one PR.

The goal is not to replace engineers or hide work behind opaque behavior. It is to scale the judgment of engineers who already have a high bar. The system does not try to be smarter than you; it tries to be as disciplined as you would be, every time, in parallel.

05 · How it works

Your lanes. Your gates between them.

Configured GitHub status is the state machine. A ProjectV2 board, a boardless issue Status field, or repository status labels all drive it.

Todo—— In Progress—◂— Human Review—◂— Merging—◂— Done

Rework

The notch marks a gate you defined. Lanes are workflow-defined: this is the delivery path. Detent's own board also configures Backlog, Blocked, and Cancelled.

1 — You write the contracts

Each project has a checked-in detent.yaml machine contract — tracker bindings, states, lifecycle policy, scheduling, retries, leases, gates — plus a checked-in, portable WORKFLOW.md agent instruction contract.

2 — You mark an issue Todo

Detent claims it, creates an isolated Git worktree from your source checkout, and dispatches a Codex agent with the contract — moving the issue to In Progress.

3 — The agent works

In its own branch. It runs your validation gate and opens or updates a pull request.

4 — Gates decide

The workflow decides whether promotion to Merging waits in Human Review, waits in the active lane, requires a current-head automated PR review, or only needs linked PR + green CI + quiet time.

5 — The merge train is serialized

One rebase, CI-watch, and merge at a time, so concurrent candidates never invalidate each other's CI. Then the issue is Done.

6 — One host, many repos

A global.yaml runs multiple projects with weights, priority, pause, and fair scheduling.

The mechanism in full, with the gate model and worktree isolation →

06 · The merge train

What lands is always green.

Serialized: one rebase, one CI watch, one merge at a time. Ten agents working in parallel never invalidate each other's CI, because only one candidate is ever being tested against the head that will receive it.

queued candidates wait→ rebase onto main→ CI watch→ merge→ main stays green

Train width is configuration, not doctrine — Detent runs its own board at one candidate at a time. The guarantee that follows is narrow and worth stating plainly: a merge only happens after CI passed on the exact commit that is about to land. Merge train configuration →

07 · The operator surface

The board stays honest.

Live counts, running agents, token / budget / rate-limit state, board flow, timelines. "In progress" means an agent is actually working right now.

The Detent dashboard: a sidebar of nine projects, a live board with Backlog, Blocked, Human Review, and Review lanes, and a header row showing running, queued, waiting, blocked, and completed counts.

$ detent tui

detent  ·  9 projects  ·  running  ·  held  ·  budget and rate limit in the header
 ▸ In Progress   agent working, make check …
 ▸ Human Review  held: approval label
 ▸ Merging       train: rebased, CI watch

And a terminal UI for people who live in tmux — the same lanes, the same counts, no browser.

Tour the operator surface →

08 · Contracts, shown

Config you can read beats adjectives.

Two files, checked into your repository: the machine contract and the agent contract. Both are excerpted here from Detent's own production config.

detent.yaml digitaldrywood/detent-orchestration

tracker:
     kind: github
     github_status_source: label
     repository: digitaldrywood/detent
     status_label_prefix: "detent:"
     active_states:
         - Todo
        - In Progress
        - Rework
        - Merging
     terminal_states:
         - Done
        - Cancelled
     dependency_auto_unblock:
         enabled: true
         target_state: Todo
         readiness: terminal_or_merged

WORKFLOW.md the agent contract, checked in and portable

You are working on **Detent** — a Go agent-orchestrator
delivered as a single binary — on GitHub issue
{{ issue.identifier }}.

 ## Detent Protocol

 Keep one persistent ## Codex Workpad issue comment
updated with the plan, validation evidence, blockers,
and final handoff. Every update must contain one
detent-status signal.

 Follow CLAUDE.md and AGENTS.md; they are the project
authority for layout, formatting, validation, and
review conventions.

Gitignored detent.local.yaml and WORKFLOW.local.md apply machine-specific overrides without touching the shared contracts. You can keep reading by hand too; nobody will revoke your keyboard.

09 · Proof

It ships itself.

digitaldrywood/detent-orchestration is Detent's own production config. It dispatches the agents that build Detent, and the merged pull requests shown on this site were written by agents it dispatched.

It is copyable as a template for your first project.

Copy the template ↗

2026-07-02 · 2:20 · Detent v0.20.1

I Opened Seven Issues for One Feature (On Purpose)

One feature. Seven real issues. Four hours. Zero babysitting.

Demonstrates

A seven-issue dependency graph completed in merge order.
Detent returned dependent work to Todo after its prerequisite merged.

Watch on YouTube ↗ Transcript →

10 · One host, many repos

Fleet scheduling from a single binary.

A global.yaml runs many projects with weights, priority, pause, and fair scheduling. Below is the projects block of Detent's own.

ProjectWeightPriority

detent 1 0

gopher-ai 1 3

gopher-corp 1 3

detent.build 1 3

The projects block of Detent's own global.yaml. That file also sets max_concurrent_agents: 10, strict scheduling, and a 1h fair-share half-life. Budget caps and rate-limit state live on the dashboard. Multi-project operation →

11 · Install

One CGO-free binary. No service to stand up.

macOS, Linux, and Windows. Install it, run the preflight check, and point it at a repository.

Homebrew — recommended when you already manage CLI tools with brew

brew install digitaldrywood/tap/detent

Or build from source with Go

go install github.com/digitaldrywood/detent/cmd/detent@latest

Upgrade with brew upgrade digitaldrywood/tap/detent.

Requirements

OpenAI Codex CLI, signed in
A GitHub token scoped to your tracker mode
Go 1.26+ for source builds only

Full requirements and first run →

first run

$ detent doctor         # preflight: gh, codex, token scope, config discovery
 $ detent version        # binary version, commit, and build date
 $ detent update --check # checksum-verified self-update