roark

Search documentation

Search across all Roark documentation pages.

Type to search across the docs.

CLI agent for GitHub issues

From GitHub issue to pull request.

Label an issue ready-for-agent. Roark implements the change in a separate checkout, reviews it, runs your verification command, and opens a PR. It never merges or closes the issue.

install Roarkread the docs

Workflow

  1. 01

    Fetch

    Load the issue, comments, and dependency information.

  2. 02

    Triage

    Stop before coding if the issue is blocked or unsuitable.

  3. 03

    Plan

    Work out the changes needed in the repository.

  4. 04

    Implement

    Edit the code in a separate managed checkout.

  5. 05

    Review

    Run separate correctness and maintainability reviews.

  6. 06

    Repair

    Fix problems found during review.

  7. 07

    Readiness

    Check that the change is ready to publish.

  8. 08

    Verify

    Run the repository's configured verification command.

  9. 09

    Publish

    Push the branch and open the pull request.

  10. 10

    Review PR

    Post correctness and maintainability comments on the PR.

Install

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

Requires Bun, Git, and GitHub CLI. Sign in with gh auth login first.

Terminal commands

  • initializeroark init

    Add Roark's configuration and ignore rules to a repository.

  • local runroark do 123 --repo owner/repo

    Work on one issue without publishing a pull request.

  • autorunroark auto --repo owner/repo --limit 1

    Pick an eligible issue and run the publishing workflow.

  • recoverroark continue 123 --repo owner/repo --attempt 1

    Resume a stopped run.

  • review prroark review-pr 456 --repo owner/repo

    Review a pull request without changing it.

  • revise prroark revise-pr 456 --repo owner/repo

    Apply requested changes, verify them, and push the update.

  • statusroark status --all --repo owner/repo

    Show previous runs and recovery details.

Run files

Each run writes its files under .roark/runs/.

.roark/runs/issue/123/attempts/1
  • issue.mdwritten
  • triage.jsonwritten
  • implementation-plan.jsonwritten
  • implementation-log.jsonwritten
  • refinement-log-0.jsonwritten
  • review-a-0.jsonwritten
  • review-b-0.jsonwritten
  • fix-log-1.jsonwritten
  • readiness.jsonwritten
  • verification.mdwritten
  • pr-draft.jsonwritten
  • summary.jsonwritten

Recovery

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

A stopped run keeps its branch, checkout, run files, and recovery command.

Pull requests

$ roark review-pr 456 --repo owner/repo$ roark revise-pr 456 --repo owner/repo

review-pr reviews without editing. revise-pr applies requested changes, verifies them, and pushes the update.

PR revision documentation