Brokk Issue Bot

Walk GitHub issues, give a coding agent a focused attempt at each one, and open pull requests for review. A Go daemon with the same no-config startup as release-bot. Both use the shared acp-go protocol client and process runner.

Install and run

npm install -g @brokkai/issue-bot
cd /path/to/your-repo
bib

For a single invocation, use npx --yes @brokkai/issue-bot from your repository. The npm package requires Node.js 18+ and includes the native binary for Linux/macOS on x64 or arm64 through optional dependencies. Keep optional dependencies enabled; installing and running the package does not require Go.

Or install a prebuilt Linux/macOS binary (amd64 or arm64):

curl -fsSL https://raw.githubusercontent.com/BrokkAi/issue-bot/master/install.sh | sh

The installer checks the archive's SHA-256 and installs bib to ~/.local/bin. Set INSTALL_DIR to use another directory. From source, make build produces bin/bib. Source builds require Go 1.27.1. You can also install from Go:

go install github.com/BrokkAi/issue-bot/cmd/bib@latest

Runtime requirements: Git, authenticated gh with repository read/push/PR access, and an authenticated ACP agent. The default is codex-acp; if it is missing, bib uses npx --yes @agentclientprotocol/codex-acp (requires Node.js and may download the adapter). Explicit agent commands are used exactly as supplied.

No configuration file is needed. The bot discovers origin (or the only remote) and the repository's default branch. New workspaces use a private bare Git repository and a separate persistent worktree for each issue. Your source checkout and uncommitted edits are left alone. Starting it authorizes unattended edits, command execution, commits, branch pushes, claim/status comments and PR creation for the configured repository.

bib /path/to/repo
bib https://github.com/OWNER/REPO.git
bib --label bug --label ready
bib once --issue 123
bib --model YOUR_MODEL_ID --effort low
bib --agent your-acp-agent --agent-arg=--stdio
bib --claim-timeout 15m
bib --draft=false
bib status
bib version
bib retry --issue 123 --once

Flags may appear before or after the repository argument. --once attempts at most one eligible issue (or reconciles one completed job), then exits. status prints saved JSON without starting an agent. retry resets pending/blocked attempt budgets and resumes work; --issue restricts it to that issue. Run bib --help for all flags.

bib version prints the embedded release tag. Local builds report dev; binaries installed with go install ...@version report the module version.

Terminal dashboard

Interactive runs show the same live dashboard as bug-bot. It fits the current terminal or tmux pane and adjusts when resized. Each pane runs one repository.

bib /path/to/repo           # live dashboard
bib /path/to/repo --plain   # scrolling logs and agent transcript
bib /path/to/repo --json    # structured logs

The overview shows the repository, branch and active base commit, issue task, active tool, uptime, attempt budget, and next poll countdown. Larger panes also show the selected model and reasoning effort. Saved counts cover all recorded jobs: issues, submitted PRs, existing PRs, pending, blocked, and skipped. A PR is counted as submitted only after confirmation; restored jobs remain in the totals.

The issue browser shows up to 200 saved jobs ordered by issue number, including the active issue. Details include the issue, branch, result, test evidence, failure, retry eligibility, and PR link. Run counters track PRs completed during this invocation, attempts, agent starts, tools, and error log events.

• 1, 2, 3 or Tab: switch overview, issues, and activity.
• ↑ / ↓ or k / j: browse results or scroll activity.
• Enter: inspect the selected result. Esc: return to the list.
• Page Up / Page Down: scroll details. g / G: jump to start/end; G resumes following live activity.
• q or Ctrl+C: stop the bot and its agent, save progress, and restore the terminal.

Activity keeps recent output; full agent transcripts remain in the state directory. On exit, a summary and changed result links stay in the terminal. once exits when its check or attempt finishes.

Piped input, redirected stderr, and TERM=dumb automatically use scrolling output. --plain and --json disable the dashboard and are mutually exclusive. NO_COLOR disables colors. status, version, and help retain their existing output and never open the dashboard.

How it works

1. Walk all open, unlocked issues, oldest first, with pagination. No label filter is required. Optional repeated --label flags require all labels; exclude_labels can opt out particular labels.
2. Skip issues that already have a linked or cross-referenced PR, including PRs created by people or other bots, on other branches or forks. Open, draft, merged and closed PRs all count. GitHub's issue links and timeline are checked; a PR with no reference to the issue cannot be associated automatically.
3. Post an “I'm starting work on this issue” comment with a unique claim and expiry time. Other instances skip issues with an active claim and continue walking the queue. Recheck competing claims before launching the agent.
4. Create a persistent issue-bot/<base-branch-hash>/<issue-number> branch and isolated worktree. The agent reads repository instructions, inspects the issue and discussion, implements a focused fix, runs checks, and commits locally.
5. Require a completion receipt with the explanation and validation evidence. Independently check the branch, clean worktree, starting commit and real diff. An optional operator verify command must also pass. Recheck claim ownership and existing PRs before pushing and again before creating the PR.
6. Push without force and create a draft PR with the explanation, check results and Fixes #N. Confirm its repository, branches, issue marker and head commit. Update the starting comment to “Done — pull request: URL”, then continue to the next available issue. --draft=false creates regular PRs. The bot does not merge PRs or close issues itself.

A PR is recorded as submitted, not as proof that the issue is solved. Agent validation evidence is a report; the bot does not infer test correctness from prose or wait for remote CI. Use repository branch protections and review, and configure verify when you need an independent local gate.

Ambiguous, already-fixed, unsupported or oversized issues can be marked blocked with an explanation on the issue. They do not prevent attempts on later issues. Failed or interrupted attempts mark the claim released; detailed diagnostics stay in local logs. Transient work failures retry after 15 minutes, up to three attempts; exhausted jobs require retry. Failed work and the previous failure are preserved. Agent setup failures (login, executable, model or effort) stop the daemon without consuming an issue attempt.

The daemon polls every five minutes when no issue is ready; while work is available it proceeds sequentially. Each attempt has a two-hour budget. Saved pending jobs are checked for an existing PR before further agent work, including at the attempt limit or after the issue closes. A lost PR-creation response is reconciled by the persistent branch and issue marker. A closed, unmerged bot PR blocks the job for inspection. Work is not automatically deleted or reset.

Coordination between instances

The claim timeout defaults to 15 minutes, configurable with --claim-timeout 30m or "claim_timeout": "30m" (minimum 30 seconds). While working, the bot renews the same comment every third of that duration. The per-attempt timeout is separate and still defaults to two hours. A crashed instance stops renewing; another instance can take over after its claim expires. A renewal error cancels the active agent, and publication requires a fresh ownership check. Keep participating machines' clocks synchronized.

Claims cover the repository and issue number across base branches and machines. Each installation keeps its own managed workspace; local locks still protect against two processes sharing the same checkout/state. Simultaneous claimants wait two seconds after posting and elect the lowest active GitHub comment ID; losers release their comment and move on. GitHub comments provide advisory coordination, not an atomic distributed lock: delayed visibility can briefly allow duplicate local effort. Rechecking ownership and PR links before publication reduces duplicate PRs, but GitHub offers no atomic comment-claim/PR transaction. All participating instances need this version's claim protocol; older versions do not honor it.

Starting comments and completion updates are idempotent across retries: the random token is saved before the initial POST, and a failed completion update is retried without running the agent or creating a PR again. The same comment is updated throughout the attempt so heartbeats do not produce comment spam. If an attempt cannot continue, its comment is marked released. An uneditable or deleted comment stops renewal; a previously saved completion can be posted again if its comment was deleted. Issues/PR read access, issue-comment write access, and the existing push/PR-creation rights are required.

Optional configuration

bib --config issue-bot.json reads a strict JSON object. There is no implicitly loaded or generated config. Paths are relative to that file. See issue-bot.example.json.

{
  "remote": "https://github.com/OWNER/REPO.git",
  "branch": "main",
  "directory": "var/checkout",
  "state_directory": "var/state",
  "labels": ["bug"],
  "exclude_labels": ["wontfix", "duplicate", "invalid"],
  "draft": true,
  "poll": "5m",
  "claim_timeout": "15m",
  "timeout": "2h",
  "retry_delay": "15m",
  "attempts": 3,
  "agent": {"command": ["codex-acp"], "model": "YOUR_MODEL_ID", "effort": "low"},
  "verify": ["/opt/checks/verify-issue"]
}

agent also accepts environment, auth_method and mode. Model and effort choices are selected and confirmed before work; unavailable choices fail explicitly. github.host supports Enterprise; github.repo (OWNER/REPO) identifies a repository when using a local mirror. instruction_files defaults to AGENTS.md, CONTRIBUTING.md, and README.md. issue can pin one issue number.

The verifier runs as an argument array, without shell expansion, in the issue worktree with ISSUE_NUMBER set. Keep it outside the agent's writable worktree.

State and diagnostics

Default state lives below $XDG_STATE_HOME/issue-bot or ~/.local/state/issue-bot, keyed by remote and base branch. Startup logs the paths. State writes use atomic replacement and fsync. Private JSONL transcripts live in state/sessions; readable live output goes to stderr. Use --json for structured logs. Retain the managed workspace, issue worktrees and state together across restarts.

New workspaces keep Git storage in state/repository.git, a detached management worktree in checkout, and each issue's worktree in checkout-issues/<number>. The management and issue worktrees share only this bot's private repository; your checkout, release-bot and other bots have independent Git metadata. Existing managed clones and their unfinished issue worktrees continue in place. A manually configured checkout must be a standalone clone or this bot's private worktree; a linked worktree sharing another repository's Git metadata is rejected.

Each attempt fetches the watched branch. The agent merges current remote changes into its assigned issue branch, resolves conflicts, and reruns affected checks before returning a fix. Retries retain the same branch, staged/unstaged edits, and unfinished merges. Other issue worktrees and the local master/main branch are left alone. Overlapping code changes can still need conflict resolution or review; worktree isolation prevents local interference. Existing claim comments coordinate separate issue-bot instances, and local locks prevent duplicate daemons from using the same workspace.

ACP permission requests are automatically approved. Client filesystem callbacks are confined by os.Root; agents and terminal commands inherit the bot account's OS rights. This is not a sandbox. Use an account/container appropriate for the repository and its credentials. Transcripts may include code and command output; manage their retention externally. Issue text is treated as untrusted problem data in the agent instructions, not as permission to broaden the task.

Publishing npm packages

Pushing a v* version tag automatically runs CI, publishes the native GitHub release, and uploads the four npm platform packages followed by the launcher. Follow the Publish packages workflow for the complete pipeline; it keeps all artifacts tied to the same tag and commit. No separate manual dispatch is needed.

The manual workflow remains available for recovery: dispatch from the existing tag with its tag input and publish=true, or use publish=false for validation only. Existing package bytes are checked for conflicts before uploading. Successful uploads do not wait for npm's public version index or run immediate public-install checks. Use the explicit registry verify command later if needed.

The workflow uses the packages-publish environment. Configure npm trusted publishing for each of the five @brokkai/issue-bot* packages with repository BrokkAi/issue-bot, workflow publish-packages.yml, and environment packages-publish. An environment secret named NPM_TOKEN can be used for bootstrap publication. Only npm is packaged; uv support is pending.

For a local installer check from a clean commit (requires Go, Node.js 24 and npm):

node --test --test-isolation=none npm/bib.test.cjs
python3 -m unittest discover -s scripts -p '*_test.py'
python3 scripts/smoke_installers.py

The smoke check builds native archives and all five npm tarballs, then installs and launches the local platform package offline with lifecycle scripts disabled.

Development

make check build
./bin/bib --help

Tests use temporary Git remotes and simulated GitHub responses. They cover walking multiple issues, existing human/fork PR detection, competing claims, claim expiry and renewal failure, idempotent starting/completion comments, PR reconciliation after a lost response, blocked-job fairness, retries preserving edits, setup failures, independent verification, configuration, discovery and locks. They do not run a paid agent or create PRs in live repositories. The shared ACP library and release-bot additionally test protocol and subprocess interoperability, model/effort selection and cancellation.

Protocol/API references: ACP v1, GitHub issues, GitHub pull requests.

Repository discovery and CLI/runner patterns originate in BrokkAi/release-bot; common ACP code is maintained in BrokkAi/acp-go.

Contributing

See CONTRIBUTING.md and our Code of Conduct. Report vulnerabilities privately using SECURITY.md.

License

Licensed under Apache-2.0. See NOTICE for project attribution and licenses/README.md for dependency terms, third-party notices, and the license review process.