Valkyrie

Valkyrie is a Rust CLI that watches GitHub repositories for pull requests and posts pull request reviews generated by Anvil.

The crate is published as brokk-valkryie; the installed binary is vk.

Install

cargo install brokk-valkryie

Requirements

• GitHub authentication from gh auth login, or GH_TOKEN/GITHUB_TOKEN set to a token that can read pull requests and write pull request reviews
• anvil on PATH
• uvx on PATH for the default Brokk MCP server command (uvx brokk mcp)

Valkyrie does not use webhooks. It polls the repositories passed at startup.

Usage

Watch one or more repositories:

vk watch BrokkAi/example BrokkAi/another-example

Equivalent flag form:

vk watch --repo BrokkAi/example --repo BrokkAi/another-example

Useful options:

vk watch BrokkAi/example --interval-seconds 120
vk watch BrokkAi/example --once
vk watch BrokkAi/example --dry-run
vk watch BrokkAi/example --state-dir /var/lib/valkyrie
vk watch BrokkAi/example --anvil-binary /usr/local/bin/anvil --default-model codex::gpt-5
vk watch BrokkAi/example --brokk-mcp-command /opt/homebrew/bin/uvx --brokk-mcp-arg brokk --brokk-mcp-arg mcp
vk watch BrokkAi/example --no-brokk-mcp
vk watch BrokkAi/example --auto-fix-status
vk watch BrokkAi/example --auto-fix-review-findings
vk watch BrokkAi/example --auto-fix-review-findings --max-review-fix-attempts 2
vk watch BrokkAi/example --show-anvil-logs
vk watch BrokkAi/example --verbose

Run local checks:

vk doctor

Review Behavior

For each poll, Valkyrie:

1. Uses the token from gh auth token when gh is available, otherwise GH_TOKEN or GITHUB_TOKEN.
2. Calls the GitHub REST API directly for the configured repositories.
3. Finds open pull requests.
4. Skips pull requests already recorded in local state.
5. Skips pull requests that already contain a Valkyrie review marker from the authenticated GitHub user.
6. Sends pull request metadata and patches to Anvil over ACP with the Brokk MCP server attached by default.
7. Asks Anvil to apply the Brokk brokk-review-pr workflow using Brokk/Bifrost MCP code intelligence.
8. Posts a GitHub pull request review with a Brokk-style Markdown summary and inline comments.
9. Records the pull request in .valkyrie/reviews.json.

Anvil manages its canonical Bifrost MCP setup during session startup. Valkyrie adds the Brokk MCP server to review sessions by default with uvx brokk mcp; use --brokk-mcp-command and repeated --brokk-mcp-arg flags to customize that command, or --no-brokk-mcp to run without the extra Brokk MCP server.

Automatic Status Fixes

vk watch --auto-fix-status opts in to automatic fix attempts for failing pull request status contexts. For each open pull request, Valkyrie reads the head commit's commit statuses and check runs. If any context has failed, Valkyrie asks Anvil to diagnose the failure, make the smallest correct change, and run relevant validation. Anvil is asked to leave changes uncommitted and unpushed.

Before Anvil runs, Valkyrie verifies that the current local worktree is clean, fetches the pull request head branch, and checks out the expected head SHA in a detached state. After Anvil returns, Valkyrie stages any changes, commits them with a status-fix message, pushes HEAD to the pull request head repository and branch, and restores the original local checkout. The local Git credentials must be able to fetch from and push to the pull request head repository. Pull requests whose head repository is unavailable, such as deleted forks, are skipped for automatic status fixes.

To avoid repeated attempts against the same failing commit, fix attempts are recorded by repository, pull request number, and head SHA in .valkyrie/reviews.json. A new push creates a new head SHA and can be attempted on a later poll if status still fails.

This mode is intentionally opt-in because it may modify code and push to remote pull request branches.

Automatic Review Finding Fixes

vk watch --auto-fix-review-findings opts in to automatic fix attempts for actionable findings generated by Valkyrie's own pull request review. If the generated review contains inline comments or a blocking/change-request verdict, Valkyrie checks out the pull request head SHA, asks Anvil to make the smallest correct fix, commits any resulting changes, and pushes them back to the pull request branch. Valkyrie skips posting the stale review after it pushes a fix; a later poll can review the new head commit.

To avoid repeated attempts against the same findings, attempts are recorded by repository, pull request number, and head SHA in .valkyrie/reviews.json. Valkyrie also caps automatic review-finding fixes by pull request number, regardless of head SHA. The default is one attempt per pull request; use --max-review-fix-attempts to raise or lower that limit.

This mode is intentionally opt-in because it may modify code and push to remote pull request branches. If --auto-fix-status is also enabled, both automatic fix modes may push commits to the same pull request branch across poll cycles.

Valkyrie is intentionally polling-based in v0.2.0. It does not run a webhook server.