Skip to content
CommandChain CommandChain CommandChain Docs

Runs and attempts

A run is one execution of a task. An attempt is one try inside that run. The distinction matters because agents are not expected to be right the first time, and the platform is built around that rather than around hoping.

A run holds attempts

Section titled “A run holds attempts”

When a task is ready to execute, the platform creates a run and dispatches it to an execution backend. The run is the durable record: it belongs to the task, it carries a budget, and it ends once, with an outcome.

Inside it, attempts alternate between two phases:

  • Implement. Do the work, or revise it after feedback.
  • Review. Score the work against the task’s acceptance criteria and write down what is still wrong.

A failing review feeds its notes into the next implement attempt. That cycle repeats until the review passes or the run hits a limit, which is why a run can hold one attempt or twelve and still be a single run.

The number of iterations is not unlimited. The run’s budget sets a maximum, along with a time limit, a spend limit, and the score a review has to reach.

Where a run can stop

Section titled “Where a run can stop”

A run is pending while it waits for a backend, in progress while an attempt is working, review while an attempt is being scored, and finalized when it is over. Two states are not failures, they are the platform waiting for you.

Paused for approval. Some tasks require a person to clear the work before an agent starts. Such a run is created already paused, and it goes nowhere until you approve or deny it. The decision is recorded on the run.

Paused for budget. When a run reaches its soft spend limit it stops rather than quietly continuing. You can raise the limit, and that raise is itself an approved, recorded action rather than a setting an agent can change.

Cancellation is the third way out. A cancelled run is terminal and leaves its record behind.

What a run leaves behind

Section titled “What a run leaves behind”

A finished run is not just a status. It leaves:

  • A timeline. Attempt by attempt, what the agent did, what it read, what it changed, and what the review said.
  • Artifacts. The things produced along the way: decks, pages, diagrams, images, and documents, each attached where it was created.
  • Code, on a branch. Coding work is committed and pushed to a task branch by the runner, never by the agent directly. See workspaces and git.
  • Cost and usage. What the run spent, which is what budgets are enforced against.

Outcome, and what happens next

Section titled “Outcome, and what happens next”

A run finalizes as accepted, rejected, or inconclusive. Accepted means the review passed and the work is ready for you. Rejected means it did not pass within its limits. Inconclusive means the run ended without a verdict, for instance because it was cut short.

None of those outcomes ship anything on their own. What a run produces waits for your review, and accepting is what moves the work forward.

Next steps

Section titled “Next steps”