The backlog and the beat ​
Orc keeps one backlog of tasks in ~/.orc/backlog, one Markdown file per task with its facts in YAML frontmatter. ORC_HOME moves the backlog elsewhere when set. The backlog lives only on the machine that runs orc beat. On a machine with no backlog folder, orc backlog without --json prints no backlog at <path> and says where the backlog lives. With --json it prints an empty backlog instead. Every other orc backlog command except add refuses with the same words. orc merge refuses the same way. A task file sits in new, taken or closed, and the folder it sits in is its state. Two files beside the folders tell the beat where tasks may go. dispatch.json names each machine, its slots, its start command and its renew command, and the quota. A machine's slots cap the tasks the beat starts there. They also set the parallel limit of the pueue group orc on that machine each time orc runner start queues a task there. The quota names the provider its accounts belong to, the command that reads their room, and each account's credential kind. An account of kind token-file names a tokenFile and needs only a start command on each machine. An account of kind token-command names a tokenCommand, for a token that lives on the dispatching machine and rolls over, and every machine names a renew command beside its start command. An account of kind none names no token source, for a provider or Pi package that logs in on its own. An account of kind claude-config names a Claude config directory on each machine. An account written with only a tokenFile or only a tokenCommand keeps working, and reads as the matching kind. The optional floorPercent sets the least room an account must have. Without it, the beat applies no floor, but an account at 0% still has no room:
{
"machines": [
{ "name": "mac", "slots": 2, "start": ["orc", "runner", "start"] },
{ "name": "linux-box", "slots": 4, "start": ["orc", "runner", "start", "--", "ssh", "linux-box", "orc"] }
],
"quota": {
"provider": "anthropic",
"command": ["my-quota-reader", "--json"],
"accounts": [
{ "name": "main", "tokenFile": "/Users/me/.secrets/main-token" },
{ "name": "second", "tokenFile": "/Users/me/.secrets/second-token" }
]
}
}A machine may add "loadLimit", a number above 0, and the beat starts nothing there while orc runner load reads its five-minute load above it. An unread load holds starts there too. On a machine whose start command runs orc runner start, the beat also starts nothing while orc runner load reads 3 or more calls queued in its heavy queue. An unread heavy queue does not hold starts. Orc refuses a load limit that is not a number above 0. Orc refuses a load limit on a machine whose start command does not run orc runner start, because the beat reads the load through that command.
The provider named here is one config.json on each machine that runs the tasks defines. Each token file path in dispatch.json holds on those machines. A token command account keeps its token in the runner token folder on each machine instead. Orc runs the quota command with no input and reads its standard output as this document:
{
"schema": "orc.quota.v1",
"accounts": [
{ "name": "main", "remainingPercent": 40 },
{ "name": "second", "unusable": "the login expired" }
]
}Each entry gives the percent of room left, from 0 to 100, or the reason the account cannot run. An account the document does not name cannot run. A Claude quota read through claude-bridge prints this document.
The quota command may instead print the document of quota-axi --full --json --provider <id>, such as ["quota-axi", "--full", "--json", "--provider", "codex"]. Orc reads a document with a providers key this way. An account named in dispatch.json reads the provider entry whose accountKey or accountKeys names it. The account's room is the effectivePercentRemaining of the entry's all_models scope under quotaSemantics, so a Codex code review window does not count. The account's reset time is the resetsAt of the scope's limiting window, the latest one when several tie, and the beat line prints it after the room. When no limiting window names a reset time, the account reads usable with no reset time. An entry with no window or no all_models percent cannot run, and the reason names its quota-axi state when that state is not fresh, with the error after a colon when the state carries one. A quota-axi document that names no window at all, or names one account key twice, leaves the quota unread.
A command that exits non-zero, runs past 15 seconds or prints any other document leaves the quota unread, and the beat starts nothing.
A quota with a token command account then looks like this:
{
"machines": [
{
"name": "linux-box",
"slots": 4,
"start": ["orc", "runner", "start", "--", "ssh", "linux-box", "orc"],
"renew": ["orc", "runner", "renew", "--", "ssh", "linux-box", "orc"]
}
],
"quota": {
"provider": "anthropic",
"command": ["my-quota-reader", "--json"],
"accounts": [{ "name": "main", "tokenCommand": ["orc", "runner", "token", "/Users/me/claude-credentials/main.json"] }]
}
}Orc runs the token command with no input and reads its standard output as this document:
{ "schema": "orc.token.v1", "token": "<the token>", "expiresAt": "2027-01-01T00:00:00.000Z" }The token is printable ASCII with no space, since Pi reads it with cat and trims it. A token running out within five minutes counts as lapsed. A command that exits non-zero, runs past 15 seconds or prints any other document or a lapsed token leaves the account waiting. The beat then starts nothing on it. A later beat that reads a live token starts the task. A refusal names only the command and what it missed, never the token.
orc runner token <claude-credentials.json> is a token command for a file in Claude Code's credentials shape, { "claudeAiOauth": { "accessToken": ..., "expiresAt": <epoch milliseconds> } }. It prints the file's access token and expiry as orc.token.v1, and writes only into a pipe, never onto a terminal. It refuses a file that still holds a refresh token, since that login would then leave the machine. Whatever keeps the file fresh is yours to run, and orc only reads it. With no such file, take a token-file account, whose file holds only the token, or a kind none account as shown below.
An account of kind none holds no token: the beat mints nothing, sends nothing, renews nothing and never waits on a token for it. A Pi package that logs in on its own takes this kind, as in a claude-bridge package that drives the Claude Code SDK while the dispatched run still goes through the main account named here:
{
"machines": [
{ "name": "mac", "slots": 2, "start": ["orc", "runner", "start"] }
],
"quota": {
"provider": "claude-bridge",
"command": ["my-quota-reader", "--json"],
"accounts": [{ "name": "main", "kind": "none" }]
}
}Its config.json provider names the package with credential package, and its env points at the login the runs take, such as a CLAUDE_CONFIG_DIR. With no CLAUDE_CONFIG_DIR the runs take your ordinary Claude login under ~/.claude. A quota that names more than one account when any of them is kind none is refused, and so is a kind none account beside a machine renew command.
To select between Claude logins, give each account a configDirs entry for every machine:
{
"accounts": [
{ "name": "main", "kind": "claude-config", "configDirs": { "mac": "/Users/me/claude/main", "linux-box": "/home/me/claude/main" } },
{ "name": "second", "kind": "claude-config", "configDirs": { "mac": "/Users/me/claude/second", "linux-box": "/home/me/claude/second" } }
]
}The provider must use credential: "package". The runner sets CLAUDE_CONFIG_DIR to the picked account's directory for the machine, overriding the provider's configured value. Orc sends paths, not credentials, to the runner.
With one login and no tool that reads its room, name one account of kind none and a quota command that always reports room:
{
"machines": [{ "name": "laptop", "slots": 1, "start": ["orc", "runner", "start"] }],
"quota": {
"provider": "opencode-go",
"command": ["sh", "-c", "echo '{\"schema\":\"orc.quota.v1\",\"accounts\":[{\"name\":\"main\",\"remainingPercent\":100}]}'"],
"accounts": [{ "name": "main", "kind": "none" }],
"floorPercent": 0
}
}The runs then take the login the provider already holds, such as Pi's own login for a pi-login provider.
projects.json names each project and its checkout on each machine:
{ "projects": [{ "name": "orc", "checkouts": { "mac": "/Users/me/code/orc", "linux-box": "/home/me/code/orc" } }] }A project may add "mode", as Delivery modes shows, and "yolo", as Merging a task's PR shows.
A project may also add "instructions", the path of a Markdown file with that project's own rules for its runs and the chat. The path is absolute, or relative to the folder that holds projects.json. Each run of the project's tasks gets the file through orc run --instructions, and orc chat reads it at start. A project instructions file replaces a discovered APPEND_SYSTEM.md. Orc refuses an instructions value that is not a file path, and a project list naming an instructions file that does not exist. A project with no instructions hands its runs and the chat no instructions.
A project may also add "upstream", a list of GitHub issue or pull request URLs on other people's repositories that the project's work filed. Only orc beat reads it, through gh api graphql under the gh login of the machine that runs the beat, and it only reads. Each beat reads each contribution's state: open, closed or merged, its comment count, and for a pull request its review count and head commit. It keeps the last state it read in ~/.orc/backlog/upstream/<project>/<owner>.<repo>.<number>.json, with the owner and repository in lower case, never in projects.json. The first beat to read a contribution records it, prints watching <url> for <project>: <state> and adds no task. A later beat that reads another state adds one scout task for the project, titled Follow up on <owner>/<repo>#<number>: <changes>, records the change as a chat event and prints added <task-id> for <project> as a scout: <url> changed: <changes>. The scout task has no priority, so it waits until you plan it with orc backlog priority. The event's key names the change, so of two beats reading one change only one adds the task, and a repeat beat on the same state adds none. A contribution gh cannot read within 30 seconds, through no network, no login or a deleted issue, prints upstream of <project>: cannot read <url>: <reason>, adds no task and keeps the recorded state. A recorded state orc cannot read prints upstream of <project>: with the file and adds no task until you remove the file, and the next beat then records the contribution afresh. Orc refuses an upstream that is not a list, an entry that is not a https://github.com/<owner>/<repo>/issues/<number> or /pull/<number> URL, and a contribution named twice, even in another case or once as its /issues/ and once as its /pull/ URL. A project with no upstream makes the beat read nothing upstream.
To add a task, run orc backlog add <project> <task-file>. Orc names the new task <project>-<n>, as in orc-9, with <n> one more than the highest number among that project's ids. A project name may hold dashes, so orc reads an id up to its last dash as the project, as in orc-tui-3. An old task-<n> id counts for the project its task file names, and it still works everywhere orc takes a task id. Orc reserves each id by creating its file in ~/.orc/backlog/ids only when no file has that name. So two adds at once never get the same id. To pipe the task in instead, give - as the task file, as in printf '# Fix the login page\n' | orc backlog add orc -. It reads stdin to its end and refuses a terminal. Add --machine <name> to run the task on that machine only, and --depends-on <task-id> once per task it waits for. To change what a new or held task waits for later, run orc backlog depend <task-id> --on <task-id>,<task-id>, which replaces its whole list, or orc backlog depend <task-id> --clear to empty it. Orc refuses a task the backlog does not hold, a task that is taken, started or closed, a task parked for the captain's answer, and a dependency on itself or one that would make two tasks wait on each other. A hold stays as it was when the dependencies change. To change the text of a new task, run orc backlog edit <task-id> <task-file>, or give - to pipe the text in as orc backlog add takes it. It replaces the title and the body and keeps the id, kind, machine, parent, split mark, dependencies, priority, hold with its history and parked questions. It works on a held, parked or parent task, and the final check of a parent reads the ## Done when list of the new text. Orc refuses a text with no title, a task the backlog does not hold, and a task that is taken, started or closed, since a run has already read its text. It never asks the planner and never splits the task. The edit takes the task file by rename the way orc backlog hold does, so an edit and a beat taking the task at the same moment never both win. To take a new task you no longer want out of the backlog, run orc backlog drop <task-id> <reason>. It closes the task with the outcome dropped and your reason, and moves its file to closed, where it is kept. orc backlog lists it under CLOSED as dropped: <reason>, and orc backlog --json carries it with outcome dropped and claim null. A drop withdraws every attention item of the task, as a close does, and the chat posts it as it posts a close. It works on a held or parked task and drops an unanswered hold with it. Orc refuses a task the backlog does not hold, a task that is taken or started, which orc backlog stop ends, and a task already closed. It refuses a child, which leaves through orc backlog plan <parent> --drop <child>, and a parent with an open child. It refuses a task another open task waits on, until orc backlog depend changes that wait. The drop takes the task file by rename, so a drop and a beat taking the task at the same moment never both win. To record the machine and run of a task parked before orc recorded them, run orc backlog origin <task-id> <machine> <run-id>, as Parked runs shows. To send a closed task's open PR back for another pass, run orc backlog send-back <task-id> <words>, as in orc backlog send-back orc-9 rename the flag. It moves the task to new, parked on its branch orc/<task-id> with your words as the answer to the question send-back, and records the machine and run that closed it and its PR as the origin in parked_origin. A sent-back run that closes before its push still names that PR, so orc merge and another send-back find it. The next beat resumes that run on the same machine and branch. The implementer resumes the session it worked in with your words as the review, the checks run again, and the push updates the same PR. Orc refuses a task that is neither closed nor sent back, a task that names no PR, and a PR that is merged or closed. It also refuses when the runner holds no run of the task, since no session is left to resume. To add more words before the next beat starts it, run orc backlog send-back again on the new task, and the run gets every set of words in order. Orc refuses those words once the PR is merged or closed. The Agents tab offers the same as Send back beside a PR that awaits your approval. Add --kind scout or --kind task for a task that ends in a report instead of a PR, as Task kinds shows. To split a large task, add it with --kind parent, then add each part with --parent <task-id>, as Parent tasks shows, or name a planner model so orc splits an over-budget request itself, as Splitting at intake shows. Add --internal to mark a ship task internal-only, which only a no-mistakes-prod-only project reads. To see the backlog, run orc backlog. It prints the new, taken and closed tasks side by side with the project list and each machine's busy slots beside them. To print the same facts as JSON, run orc backlog --json, whose document names its version first as orc.backlog.v1. orc backlog --json gives every new task a wait, either null or the reason the beat will not start it. The reason is a decision for the captain, a missing priority, the hold, or the parked questions. It is also the open children or the dependency the task waits on. That dependency includes a ship prerequisite whose PR has not merged. Taken, started and closed tasks carry null for wait. Every task also carries waiting, which is null for a taken, started or closed task and { kind, detail } for a new one, plus at for a room wait. The kind is decision, no-priority, held, parked or depends for the reasons above, and detail is the same words as wait. A new task with none of those reasons has the kind room, for what only a beat sees: no free slot, no account with room, the machines' load or the token. Each beat replaces ~/.orc/backlog/waits.json with the reasons it gave those tasks. A room wait carries the last beat's reason as detail and that beat's time as at, or null for both when the last beat gave the task no reason. To start what can start, run orc beat, from launchd or cron every few minutes. Each beat runs the quota command and reads the room on each machine before it takes any task. A decision never starts, and each beat prints waits <task-id>: decision for the captain for it. Any other task starts only once five things hold:
- It has a priority. A task with no priority never starts, and each beat prints
waits <task-id>: no priorityfor it. - No hold or parked question for the captain waits on it unanswered.
- Every task it depends on closed done, and a decision closes done when the captain answers it. A ship task also waits for each ship prerequisite with a PR to merge, whether or not they share a parent. A parent task also waits for every scout and task child closed done and every ship child with a PR merged.
- Its project has a checkout on a machine with a free slot.
- An account has room above 0% and at or above the floor, and the runs take the account with the most room.
Each beat considers the new tasks in priority order, so when slots run short the first in that order start. A task with priority 0 goes first and one with priority 4 goes after the other priorities. Among tasks of the same priority the oldest by created goes first, and of two created at the same time the lower id goes first. To give a new task a priority, add --priority <0-4> to orc backlog add. To change it later, run orc backlog priority <task-id> <0-4>, or orc backlog priority <task-id> none to clear it and keep the task from starting. Orc refuses a task that is taken, started or closed, and it leaves a held or parked task's hold and questions as they were. The task file keeps the priority as priority, and a file with no priority key has no priority. A split keeps the priority on the parent and each child, as Splitting at intake and A worker split proposal show. orc backlog shows a priority as P<n> beside the task id, as in orc-9 P0 orc, and orc backlog --json gives every task a priority, either a number from 0 to 4 or null.
To keep a new task back for a decision of yours, run orc backlog hold <task-id> --reason <text> [--until <YYYY-MM-DD>]. The task file keeps the time you placed the hold as held_at. A hold written before orc recorded that time has no held_at, and orc reads its time as null. Each beat then prints waits <task-id>: held for the captain: <reason>, with the date when the hold names one, and never starts it. The date says when you mean to answer, and a past date releases nothing: the task stays held until you answer it, and its wait opens an item in the attention queue. To answer, run orc backlog answer <task-id> <words>. The task file keeps your words as answer and the time as answered_at, and the next beat may start the task. The released run reads the task body with each hold's reason and your answers added after it, oldest first. Orc refuses to hold a task that is taken, started, closed or parked. It refuses to answer a task with no open question for you. Holding a held task again keeps the first reason. After you answer a hold, you can place a new hold on the task before it starts. The task keeps the earlier reason, date, questions, answers and held_at time in hold_history, where each entry names that time as at. orc backlog --json exposes them as hold.history. To hold a task on several decisions at once, add one --question <text> for each, and orc names them question-1 onward. Answer each one with orc backlog answer <task-id> <question-id>=<words>, and the task stays held until every question has an answer. The last answer also writes each question with its answer into answer, which the released run reads. Holding the task again with the same questions keeps the hold, and orc refuses other questions until you answer the open ones. orc backlog shows a held task as held (<reason>), and orc backlog --json gives every task a hold, either null or the reason, the date, the questions with their answers, the answer and the time it was placed as at.
To leave a note on a task, run orc backlog note <task-id> <words>. Orc appends the note as one JSON line with at, who and text to ~/.orc/backlog/notes/<task-id>.jsonl, and who is captain for this command. Each note goes out in one append write with a byte count check, so two notes written at once never mix their lines. A short write fails the note instead of writing the rest. A note takes any task the backlog holds, a closed one too, and orc refuses a task id the backlog does not hold. A note holds nothing and answers nothing, so it never changes when the beat starts the task.
To read a task's conversation in order, run orc backlog thread <task-id>. Orc builds the thread on each read from the task file, the task's items in the attention queue and its notes. It stores no copy. The task file gives each hold and the holds in hold_history, their questions and answers, and each parked question with its answer. Whether a question is open is still read from the task file. Each entry has at, who, kind, id and text. who is user, decider, worker or beat. kind is hold, question, decision, answer, delivered, withdrawn or note. id names the attention item id for every entry built from an attention item. For a hold question it names the hold question id qualified by its hold generation. It is null for a hold, a note and the answer to a hold with no questions.
- A hold and its questions name
user, and a parked question namesworker, the run that asked it. - A
decisionentry is the decider'sanswered,duplicate,asked-backorescalatedwith its text, as The decider shows. - An answer the decider gave names
decider, a closure the beat wrote on apr-readyitem namesbeat, and any other answer namesuser. - An answer that replaces the decider's names
userand notes the words it replaces, after the decider's own answer entry. - A
deliveredentry namesbeatand comes from the answer'srelayed_to, so it shows only for the current asking. - A
withdrawnentry namesbeatand gives the item's reason. - A run event item, such as
run-died, is aquestionfrombeat. - Every entry of one parked review question names the same attention item id, before and after a later park replaces the question.
- A note names
userforcaptain, and keepsdecider,workerorbeatas written.
Orc lists the entries oldest first. An entry with no time sorts directly before the next timed entry of its exchange. Such an entry is a hold placed before orc kept held_at or a delivered entry. Such a hold sits directly before its answer, or after the last one when none follows. At the same time a hold comes first, then a question, a decision, an answer, a delivered, a withdrawn and a note. With nothing said on the task it prints nothing is said on <task-id> yet. The thread works on a closed task, and orc refuses a task id the backlog does not hold. To print it as JSON, run orc backlog thread <task-id> --json, whose document names its version first as orc.thread.v1:
{
"schema": "orc.thread.v1",
"task": "orc-1",
"entries": [
{ "at": "2026-11-02T09:00:00.000Z", "who": "user", "kind": "hold", "id": null, "text": "Choose the format" },
{ "at": "2026-11-02T09:00:00.000Z", "who": "user", "kind": "question", "id": "hold-1/question-1", "text": "Which format?" },
{ "at": "2026-11-02T09:10:00.000Z", "who": "user", "kind": "answer", "id": "hold-1/question-1", "text": "JSON" },
{ "at": "2026-11-02T09:20:00.000Z", "who": "user", "kind": "note", "id": null, "text": "the merge waits on review" }
]
}The beat moves the task file from new to taken before it runs the start command, so of two beats only one takes a task. After the claim survives a recount, the beat writes the task started before it runs the start command. A task marked for a machine waits for a slot on that machine and never starts on another. The start command reads the task from ORC_TASK_ID, ORC_TASK_FILE, ORC_TASK_PROJECT, ORC_TASK_CHECKOUT, ORC_TASK_DELIVERY, ORC_TASK_MACHINE, ORC_TASK_PROVIDER, ORC_TASK_ACCOUNT, ORC_TASK_TOKEN_FILE, ORC_TASK_CLAUDE_CONFIG_DIR and ORC_TASK_INSTRUCTIONS. ORC_TASK_INSTRUCTIONS is empty when the project names no instructions file. The beat also sets ORC_RUN_MACHINE to the machine's name, and orc run records that name as the run's machine. orc runner start passes it on to the queued orc run. ORC_TASK_TOKEN_FILE is the account's token file path, never the token. On a token command account it is empty, and the start command reads the token as orc.token.v1 on standard input instead. On a kind none account it is empty, and the beat sends nothing on standard input, so a custom start command must not feed it input. ORC_TASK_CLAUDE_CONFIG_DIR holds the picked claude-config account's directory for that machine, and is empty for every other kind. The beat starts it detached in its own session, never waits for it and never kills it. So the start command and what it leaves running outlive the beat, even when launchd or cron ends the beat's process group. Its output goes to ~/.orc/backlog/logs/<task-id>.log, which ORC_TASK_LOG names. From then on, each beat ends the finished runs on a machine whose start runs orc runner start. It reads orc runner result on that machine and closes the task done, failed or stopped, or parks it on your open questions. It also applies a worker split proposal, as A worker split proposal shows. A run marked stopped closes its task stopped with the run's end reason. A run still waiting at its gate for your answer stays started, and the beat relays your answers to it, as Parked runs shows. Either way the task frees its slot in the same beat. A start older than 10 minutes with neither a pueue record nor a stopped run closes failed with the runner holds no record of this task. A close read that stays unread for 10 minutes closes the task failed with the read's reason. A first unread beat only reports the read failure and starts the wait. To stop a task yourself, run orc backlog stop <task-id> where the backlog lives. It kills the run through the machine that started it and closes the task stopped. A stop for a task on a machine whose start runs any other program refuses, so close that task by hand with orc backlog close <task-id> failed. The closed task file keeps the PR link of the orc run on orc/<task-id> as pr, and orc backlog --json carries it as pr, or null when the run opened none. Every task in orc backlog --json carries prState as open, closed, merged, or null. prState is null when the task has no PR, or when the beat has not read its PR yet. A recorded <task-id>.merged event makes it merged, and a recorded <task-id>.pr-closed event makes it closed. Without either event it is the last state the beat read for the PR. orc backlog --json reads those records without contacting the forge. The beat prints closed <task-id> <done|failed|stopped> on <machine> with the reason and the PR when the run opened one, or close failed <task-id> on <machine> with the reason when the read fails or runs past 30 seconds, until it stays unread for 10 minutes. A machine whose start runs any other program keeps owning its tasks, which the beat closes once their logs go quiet rather than stalls. To close one of those by hand, run orc backlog close <task-id> <done|failed> [reason]. A start older than 30 minutes whose log has not grown for 30 minutes closes failed with the machine keeps its own log, and its log has not grown for 30 minutes. The quiet log closes the task before the 30 minute stall flag can fire. A started run whose output has not grown for 30 minutes prints stalled <task-id> on <machine>: no output since <time> once, and again after new output stalls anew. A PR the beat cannot read for the chat prints cannot read the PR of <task-id> for the chat: <reason>. A missing start command exits 127 into its log, and the task stays started until the 10 minute no-record grace or the 30 minute quiet-log grace closes it. Only a failure to spawn the log wrapper closes the task as start-failed. To print the beat as JSON, run orc beat --json, whose document names its version first as orc.beat.v1. It carries the endings as closed, close-failed, parked and split actions, and a run waiting for your answer as asking, answered or answer-failed. An asking action names only the questions the attention queue owns for you. A parked action names those in questions and the ones the decider owns in decider. It carries a stall as stalled, a PR the beat cannot read as pr-unread, and an upstream contribution as upstream-seen, upstream-changed or upstream-unread. It carries each open queue item as an attention action, as The attention queue shows. On a token command account, each beat first sends every started task its account's current token through its machine's renew command, as JSON on standard input.