oxagenDocs
Work

Work

Give an agent a bounded piece of work, follow it until a runtime claims it, and accept the pull request it opens.

Work is where you give an existing agent a bounded piece of engineering work and review what it produced. Each work item ends in a GitHub pull request. A person approves what the work must do, sends it to one agent, and accepts the result. Oxagen merges nothing. It writes to GitHub only what a collector's switches allow. Write a work item says what.

Open it from Work in the sidebar. The address is /<organization>/<workspace>/work.

Setup

Work needs four things before an item can reach an agent. Work setup shows each one.

  1. A GitHub connection. Connect GitHub on the Repositories page. Install the Oxagen GitHub App on each repository you want Work to read.
  2. A collector. In Workspace settings, open the Work tab and its Collectors tab, then choose Add collector. Give it a name and choose the repositories linked to the workspace. To link another repository, use the Repositories page first. You can skip this step and add every item by hand.
  3. A priorities record. Triage ranks items by the workspace's priorities steering record. On the Priorities tab, choose Edit priorities to open a steering pull request for it. Until one is merged, triage records a failure on each item. Once it is merged, triage runs again on those items on its own.
  4. An agent that can take work. The Runtimes tab says whether each agent can take a send now. An agent needs a runtime, a host enrolled for it on a build of oxagen that takes work orders, and you as its operator.

Where work comes from

  • GitHub Issues. A collector reads issues from the linked repositories you pick. Add one on the Collectors tab. Webhooks arrive locked with a shared secret, so a changed delivery shows, and each delivery counts once. A reconcile every 15 minutes picks up what a webhook missed.
  • Other trackers. Linear, Jira, and GitLab collectors are not available yet. See Collectors for how they work once Oxagen turns them on.
  • People. Choose Add work item and describe the work. Stella drafts the fields and you confirm them. See Write a work item. When the repository has a collector that creates issues, Oxagen also makes the GitHub issue.

Each item gets a number in the workspace, such as WI-12. Text that comes from an issue is treated as data. Oxagen shows it as text and never follows it as an instruction.

The path of one item

  1. Triage. Triage suggests a priority, labels, an estimate, and a first draft of the Done Checklist, citing a rule of your priorities record. You can correct any of it. Your correction stays in force when triage runs again. While triage runs, a spinning mark sits beside the item's status, and the page shows the result when triage finishes, with no reload. If triage fails, the item says why, and you can set the priority yourself or retry triage. When the cause passes on its own, such as a busy service, Oxagen runs triage again by itself. After you change the priorities record, choose Re-triage open work on the Priorities tab of Work setup to rank every open item by the new rules. The items go as one batch at about half the real-time price, and results arrive within 24 hours. Only an organization Owner or Admin or a workspace Owner can send open work to triage, because each item is a model call.
  2. Done Checklist. The Done Checklist is the short list of items a reviewer checks. Each item is one sentence a reviewer can check, and keeps its key, such as c3, through every edit. While you edit it, press Enter in an item to move to the next one. Enter in the last item adds a new one. Approving a Done Checklist records who approved it, when, and its hash. A hash is a short code made from the content, and any change gives a different code. To approve many at once, tick them under Pending review and choose Review items, then Approve the Done Checklists. The confirmation lists every checklist it approves, triage's drafts included, and each is approved as listed. When triage still holds an item with a question, the approval records your outcome as triaged and approves it. When someone changed an item after the confirmation listed it, that item stays ticked and unapproved, so you can read it first.
  3. Send. You choose one agent you operate. The send names the approved Done Checklist and a key fixed before it leaves, so pressing Send again after a lost answer returns the same work order. The item reads Waiting for claim until the agent's runtime claims it, and names the oxagen work start command that claims it. Only then does a run start. No answer means the host was offered the work order and did not answer.
  4. Review. When the run ends, the item shows the pull request, its head commit, and the checks the base branch requires on that commit. Optional checks are shown for reference and decide nothing.
  5. Accept or return. Accept records your acceptance of the head commit and merges nothing. Return sends the work back to the agent with your reason, as a new send.
  6. Done. An item is done once a person accepted its head commit and the pull request merged, in either order. A pull request closed without merging is not done.

Runs started outside Oxagen

Many runs start on a person's own machine, with no send. Oxagen links such a run to the work item it worked on. The link can come from a pull request that closes the item's issue, from the issue named in the branch, a commit, or the first prompt, or from a match on what the run did. Once the link is confirmed, the run becomes the item's send, when the item has no send open:

  • The item reads In Progress while the run works and Pending Acceptance once the run ends. You accept or return the work there, as you would for any send.
  • When the item has no approved Done Checklist, Oxagen approves the latest one. When there is none, Oxagen writes one and approves it. It uses triage's draft first, then the checklist in the issue, then the issue's title.
  • The person who started the run must operate its agent and hold the roles to approve and send work in the workspace. In a regulated workspace, Oxagen approves nothing: the run becomes the send only once another person approved the Done Checklist.
  • When triage failed or never ran, the item still moves, and triage runs again in the background.
  • Oxagen didn't start the run, so it sends nothing to the machine. It never stops the run, and it never sends the work again after you return it.
  • When you reject or remove the run's link, Oxagen withdraws the send that came from it. That takes the role to control work.
  • To end the send and keep the link, choose Withdraw the send in the item's menu. Your run keeps going. Oxagen won't make that run the item's send again.

Send from stella

You can ask stella to send a work item, such as "send WI-12 to the review agent". Stella lists the agents that can take the send now. An agent on a sandbox runtime works in a cloud sandbox. An agent with an enrolled host works on that machine. When more than one agent can take it, stella asks you to pick one, with the agent it recommends first.

Stella's send waits for you. The thread shows it as a card with Approve and Deny, and nothing is sent until you approve. The card names the work item, the agent, the runtime and whether it's a cloud sandbox, your steering, and any model it asks for. Check them before you approve, because stella may have read text from outside your workspace in the item. The approved send runs as you, so it meets the same checks as the Send button: you must operate the agent, and in a regulated workspace the person who approved the Done Checklist can't send it.

On the agent's machine

A send reaches the agent's host the next time the host polls Oxagen. The person at that machine starts the work:

bash
oxagen work list
oxagen work start <work order>

oxagen work list shows each work order waiting on the machine. Run oxagen work start in a checkout of the repository the Done Checklist names. It claims the work order, then starts the agent's harness with the Done Checklist as its first prompt. The item reads Running once the run links to the send. When Oxagen refuses the claim, nothing starts, and the message says why. See oxagen work.

The first prompt also gives the agent the work item's fields: its priority, its kind, its workflow status and that status's stage, and the labels it shows on the Work page. A field with no value is left out. Status names and labels are text people and trackers wrote, so the prompt marks them as data, not as instructions.

Inside the run, the agent goes through every item of the Done Checklist after it pushes a commit to the pull request. For each item it met, it runs oxagen work claim <criterion> --text "<how the commit meets it>" and points at the proof: --run runs a command in the checkout and sends its exit code and the end of its output, --check names a CI check, --file names a file the pull request changes, and --link names a page. For each item it could not meet, it runs the same command with --unmet and says why.

The work item shows each claim beside its item, with the commit it names and each piece of evidence. Oxagen reads a CI check's result on that commit from GitHub, and whether the pull request changes a named file, and marks each one Checked, Waiting, or Failed. A command shows its exit code. A link is the agent's word, and so is the claim itself. You still check every item and decide, and accepting still ticks every item.

Before the agent ends its turn, Oxagen reads the checklist. While an item has no claim on the latest commit, Oxagen sends the agent back to it, at most three times on one commit. When the agent stops before it pushed anything, or Oxagen cannot answer in time, the turn ends as it would have. oxagen work checklist shows the agent the same list.

You can tick an item of the Done Checklist yourself at any time, whatever the item's status, if your role lets you control work. A tick is your own mark on the item. It changes no revision, asks for no new approval, and does not accept the work. The item's history shows each tick. Triage's draft items take a tick once someone saves the checklist.

After each step of its plan, the agent posts a progress update with oxagen work progress. An update says which step it finished, what changed, what passed, and what comes next. You read it on the run without opening the transcript. An update can also ask you a question, which waits for your answer with the run's other questions. A run posts at most one update a minute.

bash
oxagen work progress --step 2 --of 5 --changed "The invite page shows the expiry message." --passed "pnpm test:invites" --next "Write the copy for the expired link."

Both commands run in any shell, so they work the same in Claude Code, Codex, Cursor, and Stella. Each one uses the key of the machine that claimed the work order, and Oxagen refuses one from any other machine. Each one also sends a token that belongs to its own run, so one run cannot write to another run's work order on the same machine. A batch's run can write to any work order of its batch.

A session can lose its first prompt when it resumes, clears, or compacts its context. So every time a work order's session starts, Oxagen adds a short note of its own ahead of your workspace's steering. The note names the work order, the claim and checklist commands, and the progress command. In Claude Code and Stella, it also says to read the work item again with the get_work_item tool. A session that runs no work order gets no note.

Stop and withdraw

  • Cancel the send ends a send that no runtime has claimed. It ends at once.
  • Stop the run asks the runtime to stop the run at its next safe point. The send reads Stopping until the runtime confirms, then Stopped. If the host stays offline, Oxagen closes the run after twelve hours with no report, and the item moves to Review.
  • Withdraw the send ends a send that a runtime claimed but never started a run for, after a stop that no run confirmed. A run that starts for it later is stopped. It also ends a send that came from a run started outside Oxagen, and that run keeps going.
  • A second start of the same send is refused, and a second run that names the send is stopped. One send has one run.

What blocks Accept

Your team decides whether to use the Done Checklist and whether to wait for checks. Once a result reaches Pending acceptance, you can accept it. The acceptance covers every item of the Done Checklist and names the commit you accepted. Oxagen reads the required checks from GitHub again when you press Accept and records them beside the acceptance, and a failing or unread check does not block it.

Accept is blocked only when there is nothing to accept: the send has ended, the pull request closed without merging, the Oxagen GitHub App merged it, or Oxagen has not read the pull request's head commit yet. A new commit on the pull request voids an earlier acceptance.

Accepting ticks every item of the Done Checklist in your name, and the item's history shows each tick. Once every item is ticked, the checklist's header turns green.

The figures over the tabs

The top of the Work page shows how the work went over a period you choose: 7 days, 30 days, or 90 days. The period stays in the page's address, so a shared link opens on it.

FigureWhat it counts
AcceptedItems a person accepted and whose pull request merged in the period
Median lead timeThe middle lead time of those items, from the first reading of the item to its finish. The 90th percentile shows under it
Returned for reworkResults a person returned in the period. An item returned twice counts twice
Cost per accepted itemThe run cost Oxagen knows, divided by the accepted items. When some runs have no known cost, the figure says how many do

For 7 and 30 days, each figure that adds up shows its change against the period before. Lead time shows none, because a median does not add up. Each figure but cost shows its weekly trend as a small line.

Waiting on a person counts the open items that wait on someone, by the reason they wait:

  • Results to review: a result is ready to accept or return. A result that can't merge as it stands counts here too, such as one that conflicts with the base branch or whose pull request closed without merging. You return the work or close the item.
  • Done Checklists to write or approve: a Done Checklist waits for approval, first or again after a change. An item whose triage wrote no Done Checklist counts here too, until you write one.
  • Questions to answer: triage asked a question, or asks whether the item repeats another or is out of scope.
  • Checks failing: a required check failed on the result.
  • Sends refused: the runtime refused the send.
  • Triage to retry: triage failed. You retry it or set the priority yourself.

When nothing waits on a person, the panel doesn't show.

Choose a count to list only those items on the Incomplete tab. Choose it again, or remove the filter above the table, to list every item on the tab you're on. When no item on that tab waits for the reason, the table says so.

What each Work tab holds

TabWhat it holds
IncompleteEvery open item. Show all adds done and closed items
NextUp to five ready items Oxagen suggests you send next
ReadyItems whose Done Checklist is approved, ready to send to an agent
InboxItems in triage, waiting for a Done Checklist, changed since approval, or ready to send
RunningSends waiting for a runtime to claim them, and runs in progress
ReviewItems whose run ended, with the required checks on the head commit
AcceptedItems a person accepted in Oxagen
RoadmapWhat the open items will likely cost to finish with agents

Roadmap

Roadmap forecasts what the open work will cost. It prices each item from its agent minutes estimate and what an agent minute costs in your workspace.

The cost of an agent minute comes from your workspace's runs in the last 90 days that ended with a final cost. Oxagen prices the roadmap 2,000 times, each time at the cost per minute of one past run picked at random. The likely range, P10 to P90, holds 8 in 10 of those prices. The same records give the same figures each time you open the tab.

The tab shows:

  • The figures. The roadmap's median cost and likely range, the agent minutes the estimates add up to, the open items, and the cost of one agent minute.
  • Cost range per item. A bar from P10 to P90 for each item, with a tick at the median, grouped by workstream. Choose Show as table to read the same figures by item.
  • Running total. The total after each item, in the same order, with its range.
  • Workstreams. The median, range and agent minutes of each workstream.

An item with no estimate shows no price and adds nothing to the totals. Triage drafts an estimate for each item, and you can correct it on the item's page. Until 5 runs have ended with a final cost, the tab shows no prices. The forecast covers the oldest 200 open items.

The forecast_work_cost API returns the same figures.

Who can act

Anyone who can read the workspace's runs can read Work. Approving a Done Checklist and accepting work need the workspace Owner or Member role, or the organization Owner or Admin role. Every other action needs the same roles. Each action is checked on the server, whatever the page shows. Sending also requires that you operate the agent. In a regulated workspace, the person who approved a Done Checklist cannot send it.

Budget and cost

Nothing is reserved when you press Send. On a gateway or contained runtime, the gateway checks the agent's per-run budget before each model call. On other runtimes, Oxagen records spend after the run. A run that reported no usage shows its cost as unknown, and the item says how many of its runs have a known cost.

Outcomes

Outcomes counts the work that finished in the last 30 days: accepted and merged, returned, and closed, each on its own. It shows lead time from the first reading of the item to its finish, with its median, its 90th percentile, and its sample. It counts review touches per accepted item and the share of run cost Oxagen knows. Reopens count only items that finished 30 or more days ago. Reverts count over the same items.

A revert counts when GitHub merges a pull request with the line Reverts owner/repo#123, where 123 is the pull request that finished the item. GitHub's Revert button writes that line. A revert made by hand without that line is not counted. A revert leaves the item done. It shows in the item's history, and you decide whether to reopen the item.

In-app triage spend is on Billing, outside these figures.

The get_work_outcomes API also reports how sends reach a runtime and how the workspace uses Work each week. Outcomes does not draw these figures yet.

  • Delivery puts each send of the window in one group: claimed by a runtime, rejected, withdrawn before a claim, or still waiting. It also gives the minutes from send to claim, with the median, the 90th percentile, and the sample.
  • Each week counts the items that came into Work and the sends people made. It also says whether at least one item was accepted and merged that week.

These figures describe how work moves through the workspace. None of them names or rates a person.

On this page