Turn any GitHub PR or repo into a shareable, self-contained HTML explanation page.
- PR pages — paste a pull request URL, get a readable HTML summary with context, diffs, and rationale.
- Repo pages — generate a high-level overview of any public repository's architecture and purpose.
- OSS + bring-your-own-key — self-host the bot or run the CLI locally; you supply the LLM API key.
Open ./examples/pr-explainer.html in a browser to see a rendered PR explanation.
Recommended (Bun):
bun install -g @vdmkotai/azri
# or pin the current release
bun install -g @vdmkotai/azri@0.3.0npm:
npm install -g @vdmkotai/azri
npm install -g @vdmkotai/azri@0.3.0pnpm:
pnpm add -g @vdmkotai/azri
pnpm add -g @vdmkotai/azri@0.3.0Note:
npmandpnpminstall the package, but the CLI callsbunat runtime. Make surebunis on yourPATHbefore runningazri.
Quickstart:
bunx azri pr https://github.com/owner/repo/pull/123Don't have Bun?
curl -fsSL https://bun.sh/install | bashThen open a new terminal and re-run the install command above.
The bot runs as a GitHub App and posts explanation links as PR comments. Railway is the fastest path to production.
- Fork
https://github.com/vdmkotai/azriand push to your account. - Create a GitHub App in your org or personal account. Set the webhook URL to
https://<your-railway-domain>/webhook. Grant read access to pull requests and repository contents. - Download the private key (
.pem) from the GitHub App settings page. - Create a new Railway project from your fork. Add the environment variables from
.env.example— at minimumGITHUB_APP_ID,GITHUB_PRIVATE_KEY,GITHUB_WEBHOOK_SECRET, and one LLM key (ANTHROPIC_API_KEYorOPENAI_API_KEY). - Deploy. Railway picks up the
Dockerfileautomatically. - Install the GitHub App on the repos you want covered. Azri will comment on new PRs within seconds of opening.
For Fly.io and VPS deployment, see docs/OPERATOR.md.
Azri reads .azri/config.json at the repo root when generating repo pages. Minimum working config:
{
"modules": ["src"],
"excludePaths": ["node_modules/**", "dist/**"],
"maxFiles": 200,
"maxLines": 10000,
"telemetry": false
}All environment variables are documented in .env.example.
examples/pr-explainer.html— a rendered PR explanation pageexamples/repo-overview.html— a rendered repo overview page
Azri v0.3 processes each request through a dynamic Section Registry pipeline:
flowchart LR
S0["Stage 0\nTriage"] --> S1["Stage 1\nSummarize"]
S1 --> S2["Stage 2\nPlan sections"]
S2 --> S3["Stage 3\nProduce sections"]
S3 --> S4["Stage 4\nRender"]
S4 --> S5["Stage 5\nValidate"]
| Stage | Name | What it does |
|---|---|---|
| 0 | Triage | Classifies the input (PR diff, repo tree) and decides which sections to generate |
| 1 | Summarize | Produces a concise summary of the change or codebase |
| 2 | Plan | Chooses the best section mix from the 37-type registry |
| 3 | Produce | Fills selected sections in parallel with schema-validated output |
| 4 | Render | Assembles the final HTML with Tailwind v4 utility classes loaded from CDN |
| 5 | Validate | Checks output quality and retries failed sections |
The pipeline is implemented in packages/core using Effect for typed error handling and structured concurrency. The v0.3 renderer dynamically composes 37 registered section types and themes pages with Tailwind v4 CDN utilities. The LLM layer is swappable via adapters in packages/adapters/.
These items are deferred to v2 and are not in the current release:
- Private repo support (GitHub App installation token scoping)
- Payments adapter for hosted usage metering
- Hosted SaaS (azri.dev) with managed keys
- Multi-language UI (i18n)
Alpha. The core pipeline works. APIs and config formats may change without notice before v1.0.
See CONTRIBUTING.md. No CLA. DCO sign-off required (git commit -s).
Apache 2.0. See LICENSE.
Azri was inspired by Thariq Shihipar's article on AI-generated code explanations: https://thariq.io/blog/ai-pr-explainer.