Show HN: Aido – an AI companion for the pull requests your AI writes

The AI companion for the pull requests your AI writes.

AI agents — Copilot, Claude Code, Cursor — are opening more and more pull requests, and a human still has to understand code they didn't write. Aido keeps that human in the loop: when an AI-authored PR lands, it can automatically explain, summarize, review, and document the change. And you can run those same commands on any PR or issue on demand — just comment aido <command>

.

One companion, the whole review lifecycle: review, summarize, explain, document, test, and triage — with Gemini, ChatGPT, or Claude, right inside GitHub Actions. Install with a single workflow file.

• 🤖 Auto-companion for AI-authored PRs— when Copilot / Claude Code / Cursor open a PR, Aido runs automatically (explain + summarize by default; review/docs/test opt-in) - ⚡ On-demand on any PR or issue—aido review

,summarize

,explain

,docs

,suggest

,test

,triage

• 🧩 Consolidated, persona-guided reviewer with applyable inline suggestions(robust validation, zero false positives) - 🔌 Multi-provider, bring-your-own-key: Gemini (default), ChatGPT, Claude — no third-party data processor - 📦 One-file install from a pinned release tag; upgrading is a one-line bump - 🔧 Fully configurable prompts, personas, tones, and per-command models

Secrets(add underSettings → Secrets and variables → Actions):GEMINI_API_KEY

(required for default provider)CHATGPT_API_KEY

(if using ChatGPT)CLAUDE_API_KEY

(if using Claude)

• Uses the built-in for posting comments and reviews.GITHUB_TOKEN

⚠️ Forked PRs: repository secrets may be unavailable due to GitHub policy.

Comment these on any PR:

aido review

→ Multi-persona code review + digestaido summarize

|aido sum

|aido summary

→ High-level PR summary for stakeholdersaido explain

→ Developer-focused step-by-step explanationaido docs

→ Draft/augment documentationaido suggest

|aido improve

→ Safe improvement ideasaido test

→ Structured test plan, coverage gaps, and follow-up tasksaido config-check

→ Validate configs

Comment these on any issue:

aido triage

→ Classify, suggest labels, find similar issues, recommend next steps

When an AI agent (Copilot, Claude Code, Cursor, …) opens a pull request, Aido can run automatically — no comment needed — so a human can quickly understand and digest code they didn't write.

• Add .github/workflows/aido-auto.yml

(copy-based) orexamples/remote/aido-auto.yml

(remote install). - Configure which authors trigger it and which commands run in .github/scripts/auto/aido-auto-config.json

. Companion-first defaults:explain

+summarize

. Addreview

,docs

, ortest

to thecommands

list to run more.Only AI-authored PRs trigger it(peraiAuthors

); human PRs are never auto-run. It fires on PR open/reopen/ready —not on every commit.** Per-PR opt-out:**add ano-aido

label (configurable viaskipLabels

) or put<!-- aido: skip -->

in the PR body to skip a single PR — no config change needed.- Fires on pull_request

(notpull_request_target

), so forked PRs stay safe (read-only token, no secrets).

// .github/scripts/auto/aido-auto-config.json
{
  "enabled": true,
  "aiAuthors": ["copilot", "claude-code[bot]", "cursor[bot]"],
  "commands": ["explain", "summarize"],
  "skipLabels": ["no-aido"],
}

Note:

github-actions[bot]

anddependabot[bot]

are excluded by default — the former is too broad, and Dependabot PRs run with a read-only token and no repo secrets, so Aido can't act on them. Add them explicitly at your own risk.

Prefer to control exactly when Aido runs? Add it as a step in your own workflow — the Marketplace-published composite action:

- uses: aido-dev/aido@v1
  with:
    command: review # review | summarize | explain | docs | suggest | test | triage
    pr_number: ${{ github.event.pull_request.number }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

For triage

, pass issue_number

instead of pr_number

. See examples/action/ for full workflows.

Two ways to run Aido — pick per use case:

Reusable workflows / one-file install(below) → the comment-driven UX (aido review

on a PR) and auto-run on AI-authored PRs.This composite action→ run a specific command as a step, on your own triggers (e.g. review every PR onpull_request

).

• Add repository secrets: GEMINI_API_KEY

(default provider)CHATGPT_API_KEY

(if using ChatGPT)CLAUDE_API_KEY

(if using Claude)

• Copy toexamples/remote/aido.yml

.github/workflows/aido.yml

— a single thin workflow that runs Aido from a pinned release tag. Upgrading is a one-line tag bump. - Comment aido review

on a PR. - (Optional) Customize any command by adding its config file (e.g. .github/scripts/review/aido-review-config.json

) — overrides the shipped defaults, no scripts needed. Seefor details.examples/remote/

• Add repository secrets (as above).
• Commit workflows ( .github/workflows/*

) and scripts (.github/scripts/*

).⚠️ Make sure to include.github/scripts/lib/

— all command scripts depend on this shared library. - Comment aido review

on a PR. - (Optional) Customize configs in aido-*-config.json

— or the prompts and scripts themselves.

• Audience:

• Summarize: stakeholders (product/engineering leadership)

• Explain: developers/reviewers

• Depth:

• Summarize: high-level intent, scope, risks, impact; no implementation details

• Explain: step-by-step mechanics, rationale, risks, verification

• Content constraints:

• Summarize: no code blocks, diffs, or inline suggestions; concise and skimmable

• Explain: may include tiny illustrative snippets only if essential; avoid suggestions and large blocks

As more of your PRs are written by AI, Aido makes sure a human still understands them — automatically, and on demand. It's practical, configurable, and team-friendly: save time, catch issues early, and keep everyone in the loop — without leaving GitHub.

Dispatcher:.github/workflows/aido-dispatch.yml

Parses the first line of the comment, normalizes it, and routes to the right reusable workflow.Reusable workflows (invoked viaworkflow_call

):.github/workflows/aido-review.yml

.github/workflows/aido-summarize.yml

.github/workflows/aido-explain.yml

.github/workflows/aido-docs.yml

.github/workflows/aido-suggest.yml

.github/workflows/aido-test.yml

.github/workflows/aido-triage.yml

(issues)

Each workflow builds a prompt from PR context (title, body, changed files, truncated diff ~15k chars), calls the selected provider/model, and posts a PR review with inline, applyable suggestions (when applicable), validated by a robust layer to ensure safety and accuracy.

Shared library (required by all commands):.github/scripts/lib/

providers.js

— AI provider wrappers (ChatGPT / Gemini / Claude), model resolutiongithub.js

— GitHub API client, event parsing, PR context fetchers, comment postingconfig.js

— JSON config with defaults and deep mergetext.js

— truncation, files summary, prompt templates, comment footers

Review:- Script: .github/scripts/review/aido-review.js

• Config: .github/scripts/review/aido-review-config.json

(object with{ reviewer, personas }

; reviewer sets provider/model; personas guide facets)

• Script: Summarize (stakeholder-facing; aliases:summarize

|sum

|summary

):- Script: .github/scripts/summarize/aido-summarize.js

• Config: .github/scripts/summarize/aido-summarize-config.json

• Script: Explain (developer-focused):- Script: .github/scripts/explain/aido-explain.js

• Config: .github/scripts/explain/aido-explain-config.json

• Script: Docs:- Script: .github/scripts/docs/aido-docs.js

• Config: .github/scripts/docs/aido-docs-config.json

• Script: Suggest:- Script: .github/scripts/suggest/aido-suggest.js

• Config: .github/scripts/suggest/aido-suggest-config.json

• Script: Test:- Script: .github/scripts/test/aido-test.js

• Config: .github/scripts/test/aido-test-config.json

(addstestFocus

for unit / integration / e2e / regression / performance / security / accessibility)

• Script: Triage (issues):- Script: .github/scripts/triage/aido-triage.js

• Config: .github/scripts/triage/aido-triage-config.json

(addscandidateLabels

,severityLabels

, andapplyLabels

to optionally auto-apply suggested labels; defaultfalse

)

• Script:

Each config supports:

provider

(CHATGPT|GEMINI|CLAUDE),model

,language

,tone

,style

,length

,include

(title/body/filesSummary/diff),additionalInstructions

, and an optionalpromptTemplate

with placeholders.

• Use a single consolidated reviewer informed by your configured personas inaido-review-config.json

.- Top-level reviewer

chooses provider/model (and optional context checks). personas

define roles with prompt/tone/style/language to guide faceted notes.

• Top-level
• The review body contains a clean summary, recommendation, faceted notes, and optional context checks.
• All code changes are delivered as inline PR review suggestions(with “Apply suggestion” buttons), thoroughly validated for safety and actionability — not in the body. Keep it reasonable: start with3–5 personas(e.g., pedagogy, architecture, security, performance, QA).

Pre-curated packs: see /examples/.github/review/example personas/

example-personas.json

(~50 personas)great_defaults-personas.json

(balanced starter set)- Topic packs: web_frontend-*.json

,cloud_and_devops-*.json

,security-*.json

, and more.

• Prefer short, focused prompts and configs. - Use aido config-check

if things look off. - For UI work, pair aido explain

withaido suggest

. - For releases, run aido summarize

→aido docs

. - Before merging, run aido test

to surface missing test cases and coverage gaps. - For new issues, run aido triage

to get a quick classification, label suggestions, and similar-issue links.

• Diff is truncated (~15k chars) to keep prompts efficient.
• Provider/model availability and naming can change; set explicit models in configs.
• Forked PRs may lack secrets → provider calls may be skipped.

github-actions

· ai-code-review

· ai-assistant

· developer-productivity

· persona-based-reviews

· openai

· gemini

· claude

· chatgpt

· pr-bot

· automated-code-review

Happy shipping! ✨

Note

Data handling:

• Prompts, code, and metadata may be sent to external AI services and could be logged or retained by those providers.
• Do not include secrets, confidential, or regulated data unless you fully trust the operator and provider.

Reliability:

• Providers can rate‑limit, change models/behavior, or go offline without notice.
• Do not depend on AI outputs for production without human review and validation.

Accuracy:

• AI models can be incorrect, outdated, or hallucinate details.
• Always verify explanations, reviews, and code suggestions before applying.

source & further reading

github.com — original article