roark-coding-agent

Roark is a small CLI workflow runner around the Pi coding-agent SDK. It turns GitHub issues into isolated agent runs, review artifacts, verification gates, and pull requests.

What Roark does

• Runs an issue workflow: fetch, triage, plan, implement, review, fix, and readiness.
• Supports label-gated one-shot automation with roark auto.
• Uses managed clone workspaces so agent work is isolated from the control checkout.
• Publishes PRs only after readiness and verification pass.
• Recovers failed attempts with roark continue.
• Revises existing PRs from PR-scoped feedback with roark revise-pr.
• Writes durable run artifacts under .roark/runs.

Roark does not merge PRs, close issues, or run as a daemon. Humans remain responsible for final review and merge decisions.

Install

Prerequisites:

• Bun
• Git
• GitHub CLI authenticated with gh auth status
• push and pull request permissions for the target repository

git clone https://github.com/marcellocurto/roark-coding-agent.git
cd roark-coding-agent
bun install
bun install -g "$PWD"
roark --help
roark --version

For servers, pin a tag or commit before installing globally.

Quick start

For the complete first-run path, see Quickstart.

Initialize Roark config in a target repository:

roark init

Run one issue manually:

roark do https://github.com/owner/repo/issues/123
# or, from a checkout
roark do 123 --repo owner/repo

Preview autorun selection:

roark auto --repo owner/repo --limit 1 --dry-run

Run one label-gated autorun attempt:

roark auto --repo owner/repo --limit 1

Recover a failed attempt:

roark continue 123 --repo owner/repo --attempt 1

Revise an existing PR from review feedback:

roark revise-pr 123 --repo owner/repo

Choose your path

• First successful run: Quickstart
• Command selection: Usage
• Mental model: Concepts
• Scheduled operation: Operations runbook
• Failed run recovery: Troubleshooting

Local development

bun run roark.ts --help
bun run roark.ts do 123 --repo owner/repo
bun test
bun run typecheck

Documentation

Start with the docs index.

Common topics:

• Quickstart - first-run path.
• Concepts - workflow mental model.
• Usage - common commands and when to use them.
• Configuration — .roark/config.json, defaults, and precedence.
• Managed workspaces — clone workspaces and workspace.copyToWorktree for ignored local files such as .secrets/env.
• Autorun — label-gated automation and PR publishing.
• Recovery — failed attempts and roark continue.
• PR revisions — responding to feedback on an existing PR.
• Issue curation — creating follow-up issues from reviewer findings.
• Verification — readiness and verification gates.
• Troubleshooting — common failure symptoms and recovery.
• Operations runbook — scheduled or shared-host operation.
• Lifecycle hooks — setup commands such as dependency installation.
• Artifacts — .roark/runs layout and phase outputs.
• CLI reference — commands and options.
• Scheduling — cron, launchd, and GitHub Actions examples.
• Security and secrets — secret handling and untrusted input boundaries.
• Labels — GitHub label roles and defaults.
• Architecture — contributor-level internals.
• Versioning — SemVer policy, changelog expectations, and release checklist.
• Glossary — term definitions.

Inspiration

• symphony
• OpenAI Symphony announcement
• OpenAI harness engineering
• sandcastle