{"_id":"@aarushpandey/gitagent","name":"@aarushpandey/gitagent","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aarushpandey/gitagent","version":"1.0.0","publishConfig":{"access":"public"},"description":"Autonomous GitHub engineering pipeline: takes an issue, ships a PR, and reviews its own diff before opening it.","main":"src/pipeline.js","bin":{"github-agent":"src/pipeline.js"},"scripts":{"test":"jest","issue":"node src/pipeline.js issue","review":"node src/pipeline.js review","triage":"node src/pipeline.js triage","verify":"node scripts/verify.js","smoke":"node -e \"const p = require('./src/pipeline.js'); if (typeof p.buildAuditTrail !== 'function') process.exit(1); console.log('ok');\"","prepublishOnly":"npm test"},"keywords":["ai","agent","claude","anthropic","github","automation","code-review","pull-request","engineering-agent","autonomous"],"author":{"name":"Hadar01"},"license":"MIT","homepage":"https://github.com/Hadar01/github-agents#readme","repository":{"type":"git","url":"git+https://github.com/Hadar01/github-agents.git"},"bugs":{"url":"https://github.com/Hadar01/github-agents/issues"},"engines":{"node":">=18"},"dependencies":{"@anthropic-ai/sdk":"^0.90.0","@octokit/rest":"^22.0.1","dotenv":"^17.4.2","express":"^5.2.1","simple-git":"^3.36.0"},"devDependencies":{"jest":"^30.3.0"},"jest":{"testPathIgnorePatterns":["/node_modules/","/repos/"],"modulePathIgnorePatterns":["/repos/"]},"gitHead":"7cb2a47e947bf0922b8e4c3a9f65e8e79fa224b0","_id":"@aarushpandey/gitagent@1.0.0","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-ZfOY6IjpMCYNcdH/p7pCYS8oDuuua74z/YGmilzXi05eS5WNtpHkhP4OEjF+WRxK2bDf2/ybUwLuBiXoXX4cvA==","shasum":"7d4251edbc684c0cae7916a37fc65ee4c95c8752","tarball":"https://registry.npmjs.org/@aarushpandey/gitagent/-/gitagent-1.0.0.tgz","fileCount":36,"unpackedSize":238749,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCaLIWAnvEUGgM6iULB0uXRBfYWAP+LbPIF5JHKXQPSZAIhALEGtnJbrp48I7Cn4ygtcW1+WHAGIMaQ+F8T9ZQP7pdv"}]},"_npmUser":{"name":"aarushpandey","email":"aarushpandey820@gmail.com"},"directories":{},"maintainers":[{"name":"aarushpandey","email":"aarushpandey820@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gitagent_1.0.0_1780243618773_0.8872749125183119"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T16:06:58.582Z","1.0.0":"2026-05-31T16:06:58.927Z","modified":"2026-05-31T16:06:59.213Z"},"maintainers":[{"name":"aarushpandey","email":"aarushpandey820@gmail.com"}],"description":"Autonomous GitHub engineering pipeline: takes an issue, ships a PR, and reviews its own diff before opening it.","homepage":"https://github.com/Hadar01/github-agents#readme","keywords":["ai","agent","claude","anthropic","github","automation","code-review","pull-request","engineering-agent","autonomous"],"repository":{"type":"git","url":"git+https://github.com/Hadar01/github-agents.git"},"author":{"name":"Hadar01"},"bugs":{"url":"https://github.com/Hadar01/github-agents/issues"},"license":"MIT","readme":"
\r\n \r\n π€ github-agent\r\n \r\n
\r\n\r\n
An AI that ships pull requests β and reviews its own work before opening them.
\r\n\r\n---\r\n\r\n`github-agent` is an **autonomous engineering pipeline** built on Claude. Give it a GitHub issue URL; it clones the repo, edits the code, runs the tests, **has a second AI instance review the diff**, refuses to ship a PR that fails its own review, and opens a pull request β all in one command.\r\n\r\n```bash\r\nnode src/pipeline.js issue https://github.com/your/repo/issues/42\r\n```\r\n\r\n---\r\n\r\n## β¨ See it in action\r\n\r\n```\r\n$ node src/pipeline.js issue https://github.com/qiskit/qiskit/issues/9421 --fork --comment\r\n\r\n ββββββββββββββββββββββββββββββββββββββββββββββ\r\n β github-agent β autonomous PR engineer β\r\n β engineering β self-review β ship β\r\n ββββββββββββββββββββββββββββββββββββββββββββββ\r\n\r\nβΈ Issue qiskit/qiskit#9421\r\n title: Transpiler drops global phase on conditional gates\r\n default branch: main\r\n\r\nβΈ Cloning + branching\r\n β branch: fix/issue-9421\r\n test command: tox\r\n lint commands: ruff check ., black --check ., mypy .\r\n monorepo sub-packages: terra, aer, ibmq\r\n guessed sub-package for issue: terra\r\n CONTRIBUTING.md found at CONTRIBUTING.md\r\n Project requires DCO Signed-off-by β will auto-sign commits.\r\n 20 file(s) prefiltered as likely relevant\r\n pre-fix HEAD: 3f4a1b2\r\n\r\nβΈ Engineering agent β autonomous fix loop\r\n π [turn 1] Scoring the shortlist β transpiler/passes/optimization looks like the hit.\r\n π§ find_relevant_files(query=\"transpiler global phase conditional gates\")\r\n π§ read_file(qiskit/transpiler/passes/optimization/consolidate_blocks.py)\r\n π [turn 2] Found it β line 142 drops .global_phase on IfElseOp. Patching.\r\n π§ apply_patch(qiskit/transpiler/passes/optimization/consolidate_blocks.py, ...)\r\n π§ run_tests(tox) β PASS\r\n π§ run_lint(ruff check .) β PASS\r\n π§ run_lint(mypy .) β PASS\r\n π§ finish({\"pr_summary\":\"Preserve global_phase through IfElseOp consolidation...\"})\r\n β Agent finished after 6 turn(s)\r\n\r\nβΈ Self-review β auditing the diff\r\n β Review verdict: APPROVE\r\n\r\nToken usage (engineering + revision)\r\n input: 18,204 tok Β· output: 2,131 tok Β· cache_read: 14,067 tok\r\n cost: $0.4912\r\n\r\nβΈ Committing + pushing\r\n β added DCO Signed-off-by trailer\r\n β pushed fix/issue-9421 to Hadar01/qiskit\r\n\r\nβΈ Opening pull request\r\n β PR opened: https://github.com/qiskit/qiskit/pull/11504\r\n β commented on issue: https://github.com/qiskit/qiskit/issues/9421#issuecomment-...\r\n```\r\n\r\n---\r\n\r\n## π What makes this different\r\n\r\nMost AI coding tools **generate code and hand it to a human.** `github-agent` **ships it** β and audits itself first, refuses to ship bad work, and handles OSS repos you don't own.\r\n\r\n| | Copilot / Cursor | Devin / SWE-agent | **github-agent** |\r\n|---|:---:|:---:|:---:|\r\n| Generates code | β | β | β |\r\n| Runs tests autonomously | β | β | β |\r\n| Runs project linters autonomously | β | partial | β |\r\n| Opens the PR for you | β | β | β |\r\n| **Reviews its own diff before shipping** | β | β | β |\r\n| **Refuses to ship on bad self-review** | β | β | β |\r\n| **Revises based on its own review** | β | β | β |\r\n| Knows when to give up | β | β | β |\r\n| Works on repos you don't own (fork + PR) | β | β | β |\r\n| Human-readable audit trail in PR body | β | partial | β |\r\n| Cost estimate + kill switch per run | β | β | β |\r\n\r\n### The self-review loop β the killer feature\r\n\r\nA **second Claude instance**, with a completely fresh context and a different system prompt, audits the diff for:\r\n\r\n- π **Bug risk** β logic errors, off-by-ones, null dereferences, drift from the original issue intent\r\n- π² **Edge cases** β inputs the engineering agent didn't consider\r\n- π§ͺ **Test coverage** β is the change actually tested?\r\n- π― **Scope creep** β did the agent touch things it shouldn't?\r\n\r\nVerdict is one of `APPROVE` / `REQUEST_CHANGES` / `NEEDS_DISCUSSION`. On `REQUEST_CHANGES` the engineering agent does a **revision pass** with the review as input. On anything that isn't `APPROVE`, **the pipeline refuses to open the PR** β you have to pass `--force-pr` to override. No silent bad PRs.\r\n\r\n---\r\n\r\n## π¬ Built for big open-source projects\r\n\r\nWorking on a 50-file toy repo is easy. Working on Qiskit, Cirq, VIO is not. `github-agent` has specific affordances for large scientific-Python-class codebases:\r\n\r\n| Problem on a Qiskit-scale repo | What github-agent does |\r\n|---|---|\r\n| Thousands of files β context blows up | **Keyword relevance prefilter** scores every file against issue text; top-20 injected as starting hint. No embeddings API needed. |\r\n| Narrow language support misses `.pyx`/`.pxd`/`.pyi`/`.rst`/config | Walks all of them, plus `Makefile`, `tox.ini`, `noxfile.py`, `CONTRIBUTING.md`, PR templates. |\r\n| Monorepos with sub-packages (`qiskit-terra`, `qiskit-aer`, β¦) | **Auto-detects sub-packages**, guesses from issue text which one the change belongs to, tells the agent. |\r\n| Test command isn't bare `pytest` β it's `tox`, `nox`, `make test` | Priority-ordered detection: Makefile `test:` target β `make test`. `tox.ini` β `tox`. `noxfile.py` β `nox`. Then Python/Node/Rust. |\r\n| CI gates on `ruff`, `black`, `mypy` β not just tests | **Lint gate**: auto-detects configured linters and the agent must pass them all before `finish()`. |\r\n| Deeply-indented Python makes `apply_patch` brittle | **Whitespace-normalized fallback** + `apply_patch_range` (replace by line numbers) when strings won't disambiguate. |\r\n| DCO sign-off / PR templates / CONTRIBUTING.md rules | All read and honored. `Signed-off-by:` trailer appended automatically. PR template preserved at top of PR body. |\r\n| Scientific deps fail to install (BLAS/CUDA/compiled extensions) | `run_tests` detects `ModuleNotFoundError`/`ImportError` and flags `env_error:true`. The agent **gives up gracefully** instead of thrashing. |\r\n| Complex issues need human judgment | The agent can call `give_up({reason, explanation, blockers})`. With `--comment` it posts the reason on the issue so a human picks up with full context. |\r\n| Duplicate runs open duplicate PRs | **Duplicate-PR guard** β scans open PRs for `Resolves/Fixes/Closes #N` or matching `fix/issue-N` branch before cloning. |\r\n\r\n> π **Honest limitation:** we don't provision test environments. If a repo needs GPU / BLAS / conda, you'll want to run the agent inside a pre-warmed Docker image. That executor is on the roadmap.\r\n\r\n---\r\n\r\n## π§ββοΈ For maintainers wary of AI-generated PR noise\r\n\r\nIf you maintain a repo and you're (rightly) sceptical about AI tools dumping\r\ngeneric *\"consider error handling\"* comments into your PR threads β read this.\r\n\r\n**The `review` subcommand is offline by default.**\r\n\r\n```bash\r\nnode src/pipeline.js review https://github.com/your-repo/pull/123\r\n# β writes review-report.md to disk; never posts anywhere\r\n# β exits 1 on REQUEST_CHANGES, 2 on NEEDS_DISCUSSION/UNKNOWN\r\n# β exits 0 only on APPROVE\r\n```\r\n\r\nPosting to the PR requires an explicit `--post` flag. The default workflow is:\r\n\r\n1. Run `review` offline on a PR you'd otherwise review by hand.\r\n2. Read `review-report.md`. Cut anything speculative.\r\n3. **Manually** decide whether the curated output is worth pasting into the\r\n thread. If not, throw it away β nothing was posted, no noise added.\r\n\r\nBug-risk findings must cite `file:line`. The verdict prompt biases toward\r\n`NEEDS_DISCUSSION` rather than rubber-stamping `APPROVE`. The exit-code-on-\r\nverdict design makes it CI-gateable as a *\"block merge until a human\r\nacknowledges the bot's concerns\"* check, without ever opening a PR comment.\r\n\r\nWhen you *do* post (`--post`), findings land as **inline comments anchored to\r\nthe exact diff line** β not one wall-of-text blob. Each finding's `(file, line)`\r\nis validated against the PR's diff hunks before posting, so a hallucinated line\r\nnumber can never 422 the whole review; anything that won't anchor is folded into\r\nthe review summary with its `file:line` instead of being dropped.\r\n\r\nSee [`examples/`](examples/) for sample artifacts produced by real runs.\r\n\r\n---\r\n\r\n## π€ Contributing to repos you don't own\r\n\r\nYou can run `github-agent` on any public open-source project, even without write access. A `public_repo`-scoped PAT is enough.\r\n\r\n```bash\r\n# Fork-and-PR: pushes to your own fork, opens PR upstream, links back to the issue.\r\nnode src/pipeline.js issue https://github.com/qiskit/qiskit/issues/9421 --fork --comment\r\n\r\n# Review a PR in a project you're not a maintainer of.\r\n# --post submits the review as a PR comment (falls back to issue comment if permissions block).\r\nnode src/pipeline.js review https://github.com/qiskit/qiskit/pull/11504 --post\r\n\r\n# Triage multiple issues in one shot.\r\nnode src/pipeline.js triage https://github.com/qiskit/qiskit --label=bug --max=5 --fork --comment\r\n```\r\n\r\nThe review subcommand **exits non-zero** on `REQUEST_CHANGES` so you can wire it straight into CI as a pre-merge gate.\r\n\r\n---\r\n\r\n## π Quick start\r\n\r\n### Prerequisites\r\n\r\n- Node.js 18+\r\n- An [Anthropic API key](https://console.anthropic.com/)\r\n- A [GitHub Personal Access Token](https://github.com/settings/tokens) β `public_repo` for OSS work, `repo` for private repos\r\n\r\n### Install\r\n\r\n**No clone β just run it** (published on npm as [`@aarushpandey/gitagent`](https://www.npmjs.com/package/@aarushpandey/gitagent)):\r\n\r\n```bash\r\n# one-off, no install:\r\nANTHROPIC_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... \\\r\n npx @aarushpandey/gitagent review https://github.com/your/repo/pull/123\r\n\r\n# or install the `github-agent` command globally:\r\nnpm install -g @aarushpandey/gitagent\r\ngithub-agent review https://github.com/your/repo/pull/123\r\n```\r\n\r\n> The npm package is named `@aarushpandey/gitagent`; the command it installs is `github-agent`.\r\n\r\n**Or clone for development:**\r\n\r\n```bash\r\ngit clone https://github.com/Hadar01/github-agents.git\r\ncd github-agents\r\nnpm install\r\ncp .env.example .env\r\n# edit .env:\r\n# ANTHROPIC_API_KEY=sk-ant-...\r\n# GITHUB_TOKEN=ghp_...\r\n```\r\n\r\n### Your first run\r\n\r\n```bash\r\n# Dry run first β full pipeline, no commits/push/PR\r\nnode src/pipeline.js issue https://github.com/your/repo/issues/42 --dry-run\r\n\r\n# Ship it for real\r\nnode src/pipeline.js issue https://github.com/your/repo/issues/42\r\n\r\n# Review an existing PR (no editing β just the audit)\r\nnode src/pipeline.js review https://github.com/your/repo/pull/123\r\n```\r\n\r\nOr use the npm shorthand scripts:\r\n\r\n```bash\r\nnpm run issue -- https://github.com/your/repo/issues/42\r\nnpm run review -- https://github.com/your/repo/pull/123\r\n```\r\n\r\n---\r\n\r\n## β‘ Run it in CI β the GitHub Action\r\n\r\nThe fastest way to get a whole team using this: don't make anyone install\r\nanything. Drop a workflow into your repo and `github-agent` reviews every PR\r\n(and can auto-fix labeled issues) on GitHub's runners. No clone, no `.env` β\r\njust one secret.\r\n\r\n**Auto-review every PR** (`.github/workflows/pr-review.yml`):\r\n\r\n```yaml\r\nname: PR review (github-agent)\r\non:\r\n pull_request_target:\r\n types: [opened, synchronize, reopened]\r\npermissions:\r\n contents: read\r\n pull-requests: write\r\njobs:\r\n review:\r\n runs-on: ubuntu-latest\r\n steps:\r\n - uses: Hadar01/github-agents@v1\r\n with:\r\n command: review\r\n anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\r\n # Advisory by default β posts findings, never blocks merge.\r\n # Set 'true' to make REQUEST_CHANGES fail the check (a merge gate).\r\n fail-on-request-changes: 'false'\r\n```\r\n\r\n**Auto-fix labeled issues** β apply the `agent-fix` label and it opens a PR\r\n(`.github/workflows/issue-fix.yml`):\r\n\r\n```yaml\r\non:\r\n issues:\r\n types: [labeled]\r\npermissions: { contents: write, issues: write, pull-requests: write }\r\njobs:\r\n fix:\r\n if: github.event.label.name == 'agent-fix'\r\n runs-on: ubuntu-latest\r\n steps:\r\n - uses: Hadar01/github-agents@v1\r\n with:\r\n command: issue\r\n anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\r\n comment: 'true'\r\n```\r\n\r\nAdd one secret (**Settings β Secrets β Actions β `ANTHROPIC_API_KEY`**); the\r\nbuilt-in `GITHUB_TOKEN` handles the rest. Ready-to-copy files live in\r\n[`examples/workflows/`](examples/workflows/).\r\n\r\n| Action input | Default | Effect |\r\n|---|---|---|\r\n| `command` | β | `review`, `issue`, or `triage`. |\r\n| `target` | event URL | PR/issue/repo URL. Auto-derived from the trigger if omitted. |\r\n| `anthropic-api-key` | β | **Required.** Store as a repo/org secret. |\r\n| `github-token` | `${{ github.token }}` | Token for GitHub API calls. |\r\n| `post` | `true` | (review) Post the review back to the PR. |\r\n| `fail-on-request-changes` | `false` | (review) `true` = block merge on a bad verdict; `false` = advisory. |\r\n| `comment` | `false` | (issue) Link the PR back on the source issue. |\r\n| `fork` | `false` | (issue) Push to your fork and PR from there. |\r\n| `max-cost` | project default | USD ceiling for the run. |\r\n\r\nThe job exposes the verdict as an output (`steps..outputs.verdict`) and\r\nrenders it in the job summary, so you can branch on it in later steps.\r\n\r\n> π **Why `pull_request_target`?** Review fetches the PR diff via the GitHub\r\n> API and sends it to Claude β it never checks out or runs the PR's code. That\r\n> makes `pull_request_target` safe here, and it's what lets reviews on\r\n> **fork PRs** read the API-key secret (plain `pull_request` can't).\r\n\r\n---\r\n\r\n## π Commands & flags\r\n\r\n```\r\nnode src/pipeline.js issue [flags]\r\nnode src/pipeline.js review [flags]\r\nnode src/pipeline.js triage [flags]\r\n```\r\n\r\n| Flag | Subcommand | Effect |\r\n|---|---|---|\r\n| `--dry-run` | `issue`, `triage` | Full pipeline β skip commit/push/PR. |\r\n| `--fork` | `issue`, `triage` | Push to your fork; open PR from fork to upstream. |\r\n| `--comment` | `issue`, `triage` | Post a link-back comment on the original issue after PR opens. |\r\n| `--post` | `review` | Submit the review, with bug findings as **inline `file:line` comments** anchored to the diff (issue-comment fallback if blocked). |\r\n| `--advisory` | `review` | Always exit 0 (post findings without failing the run). Powers the Action's non-blocking mode. |\r\n| `--force-pr` | `issue`, `triage` | Override PR safety gate. Ship on `REQUEST_CHANGES` / no passing tests. |\r\n| `--web` | any | Start a **live dashboard** at `http://localhost:3000`. |\r\n| `--port=N` | any | Dashboard port (default `3000`). |\r\n| `--max-cost=2.50` | any | Hard-abort agent if run cost (USD) exceeds this. Default `$5.00`. |\r\n| `--label=bug` | `triage` | Only process issues with this label. |\r\n| `--max=5` | `triage` | Cap batch size. |\r\n\r\n---\r\n\r\n## ποΈ Architecture\r\n\r\n```\r\nβββββββββββββββββββ\r\nβ GitHub Issue β\r\nββββββββββ¬βββββββββ\r\n β\r\n βΌ\r\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\r\nβ Project discovery (zero-cost, local) β\r\nβ Β· detect test command (make/tox/nox/pytest/npm/...) β\r\nβ Β· detect linters (ruff/black/mypy/eslint/...) β\r\nβ Β· detect monorepo sub-packages + guess target β\r\nβ Β· read CONTRIBUTING.md, PR template, DCO requirement β\r\nβ Β· prefilter top-20 relevant files by keyword score β\r\nβ Β· check for duplicate open PR β\r\nββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββ\r\n β\r\n βΌ\r\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\r\nβ Engineering Agent (Claude + tool use, cost-capped) β\r\nβ β\r\nβ Tools: read_file list_files find_relevant_files β\r\nβ write_file apply_patch apply_patch_range β\r\nβ run_tests run_lint git_diff β\r\nβ git_status finish give_up β\r\nβ β\r\nβ Loop: explore β patch β test β lint β repeat β\r\nββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββ\r\n β diff\r\n βΌ\r\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\r\nβ Self-Review (Claude, fresh context + issue text) β\r\nβ β\r\nβ Audits: bug risk Β· edge cases β\r\nβ test coverage Β· scope creep β\r\nβ drift from original issue intent β\r\nβ β\r\nβ Verdict: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION β\r\nββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββ\r\n β\r\n βββββββ΄ββββββββββββββββββββββββββ\r\n β APPROVE β REQUEST_CHANGES\r\n β βΌ\r\n β βββββββββββββββββββββββββ\r\n β β Revision Pass β\r\n β β (engineering agent β\r\n β β + review feedback) β\r\n β ββββββββββββ¬βββββββββββββ\r\n β β\r\n βΌ βΌ\r\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\r\nβ Safety gate: require passing tests + clean verdict β\r\nβ On pass β commit (with DCO) β push (fork or upstream) β\r\nβ β open PR (honors PR template) β\r\nβ β optional: comment on source issue β\r\nβ On fail β audit-trail.md written, PR blocked β\r\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\r\n```\r\n\r\n---\r\n\r\n## π‘οΈ Safety guardrails\r\n\r\nThe agent has real write access to files on disk, real API tokens, and real cost. We've put real fences around it:\r\n\r\n| Guardrail | Detail |\r\n|---|---|\r\n| **Path traversal blocked** | `read_file`, `write_file`, `apply_patch*` reject any path escaping the repo root |\r\n| **No shell interpretation** | `run_tests` / `run_lint` tokenize the command, reject shell metacharacters (`;`, `&&`, backticks, `$(β¦)`), and spawn with `shell: false` |\r\n| **PR gate on bad self-review** | `REQUEST_CHANGES`, `NEEDS_DISCUSSION`, unparseable verdict, or no passing tests β PR is **blocked**. `--force-pr` to override |\r\n| **Review exits non-zero for CI** | `pipeline.js review` exits `1` on `REQUEST_CHANGES`, `2` on `NEEDS_DISCUSSION`/`UNKNOWN` |\r\n| **Iteration cap** | Hard stop at 18 agent turns per pass |\r\n| **Cost kill-switch** | Configurable per-run USD ceiling (default $5.00) β aborts before overspending |\r\n| **Token leak prevention** | GitHub PAT used for clone + push but never written to `.git/config` (remote URL stripped after clone) |\r\n| **Patch uniqueness** | `apply_patch` requires a unique match; fallback to whitespace-normalized match; errors include closest-line hints |\r\n| **No accidental file wipes** | `write_file` refuses to overwrite an existing file unless `overwrite:true` is explicitly passed |\r\n| **Pre-fix HEAD in audit** | Every run records the starting SHA with a ready-to-paste `git reset --hard ` revert |\r\n| **Flaky-test tolerance** | `run_tests` retries 3Γ on failure; passes on retry are flagged `flaky:true`, not treated as clean |\r\n| **Graceful give-up** | Agent can abort with `give_up({reason, explanation, blockers})` β no half-fixes shipped |\r\n| **API retries** | Anthropic calls retry with exponential backoff on 429/529/network errors |\r\n| **`--dry-run` mode** | Full pipeline simulation without committing, pushing, or opening anything |\r\n\r\n---\r\n\r\n## π° Cost transparency\r\n\r\nEvery run prints a token breakdown and a USD estimate. The same numbers land in the audit trail and the PR body.\r\n\r\n**Typical cost per issue:** $0.20 β $1.50, depending on repo size and whether the self-review triggers a revision pass. Bigger repos (Qiskit-scale) trend toward the upper end.\r\n\r\n```\r\nToken usage (engineering + revision)\r\n input: 18,204 tok Β· output: 2,131 tok\r\n cache_read: 14,067 tok Β· cache_create: 0 tok\r\n βββββββββββββββββββββββββββββββββββββββββββββββ\r\n cost: $0.4912 (in $0.2731 + out $0.1598 + cache_r $0.0211 + cache_c $0.0000)\r\n```\r\n\r\n> Rates live in `src/config.js` (`COST_INPUT_PER_MTOK`, `COST_OUTPUT_PER_MTOK`, `COST_CACHE_READ_PER_MTOK`, `COST_CACHE_CREATION_PER_MTOK`). Update them if Anthropic pricing changes.\r\n\r\n---\r\n\r\n## π Audit trail\r\n\r\nEvery run writes `audit-trail.md` (gitignored). Designed to be skimmable by a human reviewer in under a minute:\r\n\r\n```\r\n# Audit trail β issue #9421: Transpiler drops global phase on conditional gates\r\n\r\n**Issue:** https://github.com/qiskit/qiskit/issues/9421\r\n**Branch:** fix/issue-9421\r\n**Pre-fix HEAD:** 3f4a1b2 β revert with git reset --hard 3f4a1b2\r\n**Turns used:** 6 of 18\r\n**Cost:** $0.4912\r\n\r\n## Outcome\r\nβ Finished β in single pass\r\nPreserve global_phase through IfElseOp consolidation...\r\n\r\n## Safety gates\r\n- Self-review verdict: APPROVE\r\n- Tests observed passing: YES\r\n- Lint observed passing: YES\r\n\r\n## Files touched\r\n- qiskit/transpiler/passes/optimization/consolidate_blocks.py β 1 edit via apply_patch\r\n\r\n## Test runs\r\n- Total invocations: 1 Β· Passed: 1 Β· Failed: 0\r\n\r\n## Timeline (condensed)\r\n- Turn 1 β Scoring the shortlistβ¦\r\n - ranked files for: \"transpiler global phase conditional gates\"\r\n - read qiskit/transpiler/passes/optimization/consolidate_blocks.py\r\n- Turn 2 β Found it β line 142 drops .global_phaseβ¦\r\n - patched qiskit/transpiler/passes/optimization/consolidate_blocks.py\r\n- Turn 3 β ran tests: tox β PASS; ran lint: ruff check . β PASS; ran lint: mypy . β PASS\r\n- Turn 4 β signalled finish\r\n\r\n## Self-review report\r\n[full reviewer output]\r\n\r\n## Full tool transcript\r\nβ¦raw trace for debuggingβ¦\r\n```\r\n\r\n---\r\n\r\n## π Project structure\r\n\r\n```\r\ngithub-agent/\r\nβββ src/\r\nβ βββ pipeline.js β CLI entry + subcommands\r\nβ βββ orchestrator.js β engineering β review β revision β PR + project discovery\r\nβ βββ config.js β model, limits, cost rates\r\nβ βββ agents/\r\nβ β βββ engineeringAgent.js β issue β autonomous fix\r\nβ β βββ reviewCopilot.js β diff β structured audit\r\nβ β βββ agentLoop.js β multi-turn tool-use loop, retries, cost ceiling\r\nβ β βββ tools.js β tool schemas + sandboxed handlers\r\nβ βββ prompts/\r\nβ β βββ engineering.js β agentic system prompt, monorepo/lint/contrib hints\r\nβ β βββ review.js β review system prompt + verdict format\r\nβ βββ mapper/\r\nβ β βββ repoMap.js β big-project file walker, ignore-dirs, truncation\r\nβ β βββ fileRelevance.js β keyword scorer β starting-file prefilter\r\nβ βββ utils/\r\nβ β βββ cost.js β pricing math (input/output/cache)\r\nβ β βββ diffLines.js β unified-diff parser β valid inline-comment anchors\r\nβ β βββ githubUrl.js β parse owner/repo/number from URLs\r\nβ βββ cli/\r\nβ β βββ output.js β pretty terminal + cost summary\r\nβ βββ web/\r\nβ βββ server.js β Express SSE dashboard\r\nβ βββ public/index.html β live agent feed\r\nβββ tests/ β 127 tests across 9 suites\r\nβββ .github/workflows/test.yml β CI matrix: Linux/macOS/Windows Γ Node 18/20/22\r\n```\r\n\r\n---\r\n\r\n## π§ͺ Tests\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n**146 tests across 12 suites** covering path traversal, shell-injection guards, patch fallback strategies, repo walker truncation, big-project ignore-dirs, orchestrator verdict parsing, monorepo detection, CONTRIBUTING/DCO reading, cost math (including cache creation), audit trail structure, PR body + template honoring, GitHub Action verdict reporting, unified-diff line anchoring, inline-comment parsing/partitioning, and a mocked-SDK end-to-end run with retry semantics.\r\n\r\nCI runs the full suite on **Linux / macOS / Windows Γ Node 18 / 20 / 22** for every push and pull request. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contributor workflow and [`TESTING.md`](TESTING.md) for live, end-to-end feature testing recipes.\r\n\r\n---\r\n\r\n## πΊοΈ Roadmap\r\n\r\n- [ ] **Docker/devcontainer executor** β so `pytest` works on Qiskit-class repos that need BLAS / CUDA / compiled extensions\r\n- [ ] **Embedding-based relevance** β drop-in replacement for the keyword prefilter on very abstract issues\r\n- [ ] **Parallel triage** β one dashboard pane per issue when batching\r\n- [ ] **LangSmith / Helicone telemetry export**\r\n- [ ] **Pluggable language adapters** β `rustfmt`+`cargo`, `gofmt`+`go vet`, etc.\r\n\r\n---\r\n\r\n## π€ Contributing\r\n\r\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Short version: one behaviour change per PR, add a test with every behaviour change, `npm test` must be green on Node 18/20/22.\r\n\r\n---\r\n\r\n## π License\r\n\r\n[MIT](LICENSE) β use it, fork it, ship it.\r\n","readmeFilename":"README.md","_rev":"1-ae4df6db57e3bcaf0d1465e029c87dbb"}
![\"Claude](\"https://img.shields.io/badge/model-Claude%20Sonnet%204.6-blueviolet?style=flat-square&logo=anthropic\"){kind=icon}
\r\n ![\"146](\"https://img.shields.io/badge/tests-146%20passing-brightgreen?style=flat-square\"){kind=icon}
\r\n ![\"Node](\"https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=node.js\"){kind=icon}
\r\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-green?style=flat-square\"){kind=icon}
\r\n ![\"CI](\"https://img.shields.io/badge/CI-Linux%20%7C%20macOS%20%7C%20Windows-555?style=flat-square&logo=githubactions\"){kind=icon}
\r\n