gh-issues

What it does

Orchestrates automated handling of GitHub issues by fetching issues from a repository, then spawning sub-agents to implement fixes and open PRs, and finally monitoring PR reviews. Supports optional fork mode, various filters (labels, milestone, assignee), and modes for watch polling, cron execution, and dry-run. Uses curl with the GitHub REST API and requires a GH_TOKEN for authentication. Stores derived values such as SOURCE_REPO, PUSH_REPO, and FORK_MODE for later phases.

How it works

• Phase 1: Parses the /gh-issues arguments to identify SOURCE_REPO, PUSH_REPO, FORK_MODE, and filters like --label, --limit, --milestone, --assignee, --state, and --watch. Determines PUSH_REPO and FORK_MODE based on --fork. Respects --reviews-only and --cron to adjust flow.
• Phase 2: Fetches issues via the GitHub REST API using curl with Authorization: Bearer $GH_TOKEN and Accept: application/vnd.github+json. Applies filters (labels, milestone, assignee). Excludes pull requests from results. In watch mode, excludes already processed issues. Handles authentication errors and empty results with explicit messages.
• Phase 3: Presents a markdown table of the fetched issues and, if in fork mode, notes fork behavior. Honors --dry-run (display only) and --yes (auto-process). Otherwise prompts user for confirmation to process all, specific numbers, or cancel.
• Phase 4: Pre-flight checks including dirty tree warning, current base branch, remote reachability, GH_TOKEN validity, PR existence checks for issues, in-progress branch checks on the push/fork repo, and claim-based in-progress tracking. Reports and halts on failures or skip conditions with explicit messages.
• Phase 5: Spawns sub-agents in parallel (normal mode) or sequentially (cron mode). In cron, uses a cursor and claims-file-based in-progress tracking to avoid duplicates. On spawning, records claims and reports immediate status like "Spawned fix agent for #{N} — will create PR when complete" and exits.
• Sub-agent task prompt: Constructs a detailed, templated prompt containing repository details, issue data, and configuration (base branch, notification channel) for each issue. Emphasizes not to use the gh CLI and to rely solely on curl for GitHub operations.

When to use it

• When you want automated triage and fixing of GitHub issues with optional fork-based PR workflows.
• When you need repeated polling (watch) or scheduled cron-based processing with concurrency limits.
• When you require explicit authentication handling and clear user-facing error messages for authentication or remote issues.

What it can touch

• GitHub via REST API calls using curl with a Bearer token (GH_TOKEN).
• Repositories (SOURCE_REPO, PUSH_REPO) for fetching issues, creating PRs, and checking branches/PRs.
• Local git state for pre-flight checks (dirty work tree, current branch, remotes).
• Local files for claims and cursor tracking: /data/.clawdbot/gh-issues-claims.json, /data/.clawdbot/gh-issues-cursor-<SOURCE_REPO_SLUG>.json.
• Optional notification channel (Telegram) for final PR summaries.

Caveats

• Requires GitHub authentication via GH_TOKEN and access to the GitHub REST API; errors are surfaced explicitly (401/403 handling).
• Excludes pull requests from issue results; only issues are processed unless a PR is created by sub-agents.
• Cron mode and watch mode introduce stateful behavior via claims and cursor files; misconfiguration may lead to skipped items or duplicates.
• No gh CLI usage is allowed; all actions are performed through curl-based API calls.
• Behavior depends on correct interpretation of milestone titles (requires an additional API lookup if a title is provided).