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-versionpins. - Git 2.48 or later, and Node.
- Pi, the
@earendil-works/pi-coding-agentnpm 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:
- Run
git clone https://github.com/avi2d/orc.gitto clone the repository. - Run
cd orc && bun install --frozen-lockfileto install the pinned dependencies. - Run
cd packages/run && bun linkto link the command. - Run
orc --versionto check it.
Orc prints orc and its version.
Name a provider and its models ​
To tell orc which models it may run:
- Save
~/.orc/config.jsonwith one provider and the models for each role.
{
"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:
- In the project, add a
.no-mistakes.yamlfile with at least one named check undercommands. - Commit that file.
commands:
test: bun testRun the task ​
To run it:
- Write the task in Markdown outside the project, such as
~/task.md, with a#title and what you want done. - Enter a clean checkout of the project.
- Run
orc run ~/task.md --sandbox none. - 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:
- Run
orc runsto list recent runs with their status and pull request. - Run
orc show <run-id>to see one run step by step. - Run
orc log <run-id> <step-id>to print one step's output.
Troubleshooting ​
Orc refuses a checkout with uncommitted changes ​
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 ​
Upstream's install script fetches a release older than the one orc needs. Install the release Installing no-mistakes names.