Skip to content

Run your first task ​

Run one task by hand, to see a run from the task file to its pull request before you set up a backlog.

Before you begin ​

  • Bun, at the version .bun-version pins.
  • Git 2.48 or later, and Node.
  • Pi, the @earendil-works/pi-coding-agent npm package, logged in to a model provider.
  • no-mistakes, installed as Installing no-mistakes says.
  • A project in a git checkout with a remote that no-mistakes can open a pull request on, such as GitHub.

Install orc ​

To put the orc command on your PATH:

  1. Run git clone https://github.com/avi2d/orc.git to clone the repository.
  2. Run cd orc && bun install --frozen-lockfile to install the pinned dependencies.
  3. Run cd packages/run && bun link to link the command.
  4. Run orc --version to check it.

Orc prints orc and its version.

Name a provider and its models ​

To tell orc which models it may run:

  1. Save ~/.orc/config.json with one provider and the models for each role.
json
{
  "providers": [{ "id": "opencode-go", "credential": "pi-login", "nono": { "upstream": "https://opencode.ai/zen/go/v1" } }],
  "models": { "implementer": "opencode-go/kimi-k3", "fixer": "opencode-go/kimi-k3", "orchestrator": "opencode-go/kimi-k3" }
}

Configuring providers shows every credential kind.

Name the project's checks ​

To give the run something to pass:

  1. In the project, add a .no-mistakes.yaml file with at least one named check under commands.
  2. Commit that file.
yaml
commands:
  test: bun test

Run the task ​

To run it:

  1. Write the task in Markdown outside the project, such as ~/task.md, with a # title and what you want done.
  2. Enter a clean checkout of the project.
  3. Run orc run ~/task.md --sandbox none.
  4. Read the report orc prints when the run ends.

Orc prints the branch, its commits, the checks, the review and the pull request link. --sandbox none runs the agent on the host as your user. With nono from https://nono.sh installed, drop the flag and the run works inside the nono sandbox.

See what happened ​

To read the run afterwards:

  1. Run orc runs to list recent runs with their status and pull request.
  2. Run orc show <run-id> to see one run step by step.
  3. Run orc log <run-id> <step-id> to print one step's output.

Troubleshooting &ZeroWidthSpace;

Orc refuses a checkout with uncommitted changes &ZeroWidthSpace;

The run copies the project from its last commit, so uncommitted work would be left out. Commit or stash the changes and run the command again.

Orc refuses the no-mistakes release &ZeroWidthSpace;

Upstream's install script fetches a release older than the one orc needs. Install the release Installing no-mistakes names.