npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nairon-ai/aegis

v0.7.2

Published

Self-hosted AFK bug-fixing agent for GitHub Issues and Linear

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

_obaid__obaid_

Keywords

Readme

Aegis

Self-hosted AFK bug-fixing agent for GitHub Issues and Linear.

Aegis watches bug tickets marked ready to implement, checks whether they have enough context, claims one safely, investigates in a Flue agent running inside Cloudflare Sandbox, posts a human-readable RCA checkpoint, waits for approval, then opens a PR. Human review stays in control.

GitHub/Linear bug ticket marked ready
        |
        v
Aegis readiness check
        |
        v
Flue agent in Cloudflare Sandbox
        |
        v
RCA checkpoint -> approve from GitHub/Linear or Telegram
        |
        v
Minimal fix branch -> PR -> stop

Start Here

If you want to connect Aegis to another repo and monitor its bugs, run Aegis from the product repo you want it to fix.

For example, if Aegis should monitor KeyLead-Team/keylead, run every setup command from your local KeyLead checkout:

cd ~/Desktop/keylead
npx --yes @nairon-ai/aegis@latest init
npx --yes @nairon-ai/aegis@latest setup

First prove Aegis can see a ready bug locally:

npx --yes @nairon-ai/aegis@latest status
npx --yes @nairon-ai/aegis@latest pickup --dry-run

Only deploy after pickup --dry-run finds the test issue.

Full setup guide: docs/SETUP.md.

First Local Test

No Cloudflare required for this part.

  1. cd into the product repo Aegis should monitor.
  2. Run npx --yes @nairon-ai/aegis@latest init.
  3. Run npx --yes @nairon-ai/aegis@latest setup.
  4. Choose One-click GitHub App unless you already know how to create a GitHub token.
  5. Choose Codex account / ChatGPT login or OpenAI API key, then choose the model.
  6. Choose plan-first and minimal for the first test.
  7. Add bug and ready to implement labels to the monitored GitHub repo.
  8. Create a test bug issue with both labels.
  9. Run npx --yes @nairon-ai/aegis@latest pickup --dry-run.

Good first result:

github:#123 would run - ready bug with enough context

If you see No ready bugs found, check MONITORED_REPO, exact label names, issue state, and GitHub token access.

GitHub Access Choices

During setup, choose one:

  • One-click GitHub App: recommended. Aegis opens a browser page, creates the app, asks you to install it on the repo, then saves the credentials. If you rerun setup later, Aegis reuses the saved app instead of creating another one. If it finds an installed Aegis app without local credentials, it helps you recover it by generating a new GitHub App private key.
  • GitHub token: quick local test if you already know how to create fine-grained GitHub tokens.
  • Paste existing GitHub App credentials: only if you already made an app manually.

Aegis auto-detects git remote origin and origin's default branch when you run setup inside your product repo, so it normally will not ask which repo or base branch to use. If no GitHub origin exists, it asks for owner/repo or a full GitHub URL like https://github.com/KeyLead-Team/keylead.

GitHub App credentials are saved in .aegis/.env and backed up for your Mac user under ~/.aegis/github-apps/, so future setup runs reuse the same app automatically. GitHub only requires a new private-key download if those local credentials were never saved or were deleted.

If you connect Linear, Aegis fetches your Linear teams after you paste the API key and lets you choose by name, for example Engineering (ENG). You do not need to hunt for Linear UUIDs manually.

For model auth, Aegis asks account first, then model. Codex account / ChatGPT login uses openai-codex/... models and stores OAuth credentials for your self-hosted Worker. OpenAI API key uses openai/... models and normal API billing.

Setup reruns check each completed step first. Existing Codex credentials, API keys, webhook secrets, Linear team, Telegram config, production context, model choice, and Worker URL are reused unless you choose to reconfigure that step.

Older .env.local values are read and migrated into .aegis/.env on the next setup save, so previous Linear/GitHub/model credentials should not need re-entry.

Deployed AFK Mode

Deploy only after the local dry-run works.

  1. Create a Cloudflare account.
  2. Enable Workers Paid.
  3. Start Docker locally.
  4. Log in with npx wrangler login.
  5. Run npx --yes @nairon-ai/aegis@latest deploy.
  6. Add GitHub/Linear/Telegram webhooks using the Worker URL printed by deploy.

Two Repos

Aegis is installed from npm/GitHub and configured inside the app repo.

  • Aegis package: this repo, installed through npx or as a dev dependency.
  • Monitored repo: the product repo Aegis fixes, for example your-org/your-app.
  • Project config: .aegis/ in the monitored repo.

MONITORED_REPO=your-org/your-app is the pointer between them.

Do I Need Cloudflare?

  • Local dry-run: no Cloudflare required. npx @nairon-ai/aegis pickup --dry-run only scans GitHub/Linear and prints decisions.
  • Real AFK watcher: yes. Aegis v1 deploys as a Cloudflare Worker and runs coding work in Cloudflare Sandbox/Containers.
  • Database: no. Aegis uses GitHub/Linear labels, statuses, comments, and PR branches as its state tracker.
  • Cloudflare auth: only needed for deploy. Run npx wrangler login once; aegis deploy checks this before building.
  • Sandbox setup: no separate sandbox dashboard step. Flue generates the Wrangler config and Aegis deploys the Worker/Sandbox binding.

Cloudflare Sandbox is currently available on Workers Paid and uses Docker during deploy. See Cloudflare's Sandbox overview and getting started guide.

What Aegis Does

  • Watches GitHub Issues and/or Linear issues.
  • Picks up bugs only.
  • Requires a ready signal plus a readiness check.
  • Uses Flue as the programmable agent harness.
  • Runs code work in Cloudflare Sandbox.
  • Uses GitHub/Linear as the tracker and durable state.
  • Optionally sends Telegram approval summaries.
  • Optionally gives the agent read-only DB access and Vercel logs.
  • Opens PRs, then stops. No auto-merge.

What Aegis Does Not Do

  • It does not host customer code or secrets for you.
  • It does not require a database.
  • It does not implement features in v1.
  • It does not write to production systems by default.
  • It does not self-heal PR review comments yet.
  • It does not require Sentry. Error providers should be linked or pasted into the issue.

Requirements

  • Bun
  • Docker running locally for Cloudflare Sandbox image deploy
  • Cloudflare account and Workers Paid for deployed mode
  • GitHub App or GitHub token with Contents, Issues, and Pull Requests read/write access
  • Codex account login for the default openai-codex/gpt-5.5 model, or an OpenAI API key for openai/... models
  • Optional: Linear API key
  • Optional: Telegram bot
  • Optional: read-only production database URL
  • Optional: Vercel API token/project ID for logs

Telegram bot setup is:

  1. Open Telegram and search for the verified @BotFather account.
  2. Send /newbot.
  3. Pick a display name.
  4. Pick a username ending in bot.
  5. Copy the HTTP API token BotFather replies with.

Aegis then asks you to message your new bot once and auto-detects the chat ID.

Quick Start

cd your-product-repo
npx @nairon-ai/aegis init
npx @nairon-ai/aegis setup

Create a bug in the monitored repo with:

  • label: bug
  • label: ready to implement
  • enough context: what happened, what should have happened, where it happened, and an error/log excerpt if available

Then run:

npx @nairon-ai/aegis pickup --dry-run

If that finds the issue, deploy:

npx wrangler login
npx @nairon-ai/aegis deploy

Then configure webhooks using the Worker URL printed by deploy. Full details: docs/SETUP.md.

Pause Aegis

Run this from your product repo any time you want Aegis to stop touching tickets:

npx --yes @nairon-ai/aegis@latest pause

This sets MAX_CONCURRENT_RUNS=0 locally and on the deployed Cloudflare Worker. No Docker rebuild needed.

While paused, Aegis will not scan, claim tickets, move tickets, run stale recovery, handle approvals, or start sandboxes. Webhooks and cron can still arrive, but the Worker returns immediately without doing work.

Resume later:

npx --yes @nairon-ai/aegis@latest resume

Resume with more parallelism:

npx --yes @nairon-ai/aegis@latest resume --concurrency 2

Disconnect Aegis

Run this from the product repo to print the shutdown checklist:

npx --yes @nairon-ai/aegis@latest disconnect

To fully stop using Aegis:

  1. Delete the Cloudflare Worker if deployed: npx wrangler delete aegis-worker.
  2. Revoke Codex account OAuth access or revoke the OpenAI API key, depending on model auth.
  3. Uninstall the Aegis GitHub App from the repo, or revoke the GitHub token.
  4. Delete Aegis webhooks from GitHub, Linear, and Telegram if configured.
  5. Remove local config: rm -rf .aegis.
  6. Remove cached GitHub App credentials if you used the app flow: rm -f ~/.aegis/github-apps/YOUR-ORG-YOUR-REPO.env.
  7. Optionally remove Aegis-only labels: aegis:in-progress, aegis:needs-info, aegis:blocked, aegis:pr-opened.

How Pickup Works

Aegis scans every 10 minutes and also reacts to GitHub/Linear webhooks.

Manual cloud trigger:

curl -X POST https://YOUR_WORKER.workers.dev/api/pickup

For each ticket:

  1. Must be labeled/statused ready.
  2. Must be a bug.
  3. Must have enough context.
  4. Must not already have an active Aegis run.
  5. Aegis claims it.
  6. Aegis starts a Flue planning run.

If context is too thin, Aegis comments with one concrete question and does not burn a sandbox run.

Watching Runs

Run these from the product repo.

See tickets Aegis is currently working on:

npx --yes @nairon-ai/aegis@latest runs

Include blocked, needs-info, and PR-opened tickets:

npx --yes @nairon-ai/aegis@latest runs --all

Peek inside one run's Cloudflare Sandbox:

npx --yes @nairon-ai/aegis@latest peek eng-950

This shows the sandbox workspace, git state, recent commits, and running processes without printing GitHub tokens or the full agent context.

Tail live Worker/Sandbox logs for one run:

npx --yes @nairon-ai/aegis@latest logs eng-950

Tail all Aegis Worker logs:

npx --yes @nairon-ai/aegis@latest logs

logs is live. Press Ctrl-C to stop it.

Recover stuck runs:

npx --yes @nairon-ai/aegis@latest recover

This marks any run that has been stuck without a tracker update for 20+ minutes as blocked, posts a plain-English failure note on the ticket, and sends Telegram a short failure message when Telegram is configured. Deployed Aegis also runs this watchdog before cron/manual pickup.

For run errors, Aegis tries both notifications independently: it updates GitHub/Linear and sends the connected Telegram chat the same failure context. If the tracker update fails, Telegram is still attempted.

Approval Flow

Aegis posts the full RCA to GitHub/Linear.

Telegram gets a short non-technical summary:

Aegis found a likely fix

Bug: Users see an error after clicking Checkout

Why: The app expects a related record to exist, but sometimes it is missing.

Fix: Add a safe check and a regression test.
Risk: Low

Approve: /aegis proceed <run-id>
Stop: /aegis stop <run-id>

Approve from GitHub/Linear or Telegram:

/aegis proceed <run-id>

Cancel:

/aegis stop <run-id>

Ask a follow-up or add context:

/aegis ask <run-id> <question or extra detail>

Aegis reruns the planning checkpoint with that extra context.

Production Context

Minimal mode uses only:

  • issue text
  • repo code

Production mode can add:

  • read-only DATABASE_URL
  • Vercel logs around the issue time

Use read-only production access. Do not give Aegis write access unless you have a tighter policy layer.

During setup and status, Aegis checks the monitored GitHub repo for Actions secret names like DATABASE_URL, POSTGRES_URL, and VERCEL_TOKEN when gh is logged in. GitHub does not allow any tool to read secret values back, so Aegis can confirm a secret exists but cannot import it. Start with Minimal mode; paste read-only production values only when you want the agent to inspect production context.

Commands

npx @nairon-ai/aegis init
npx @nairon-ai/aegis setup
npx @nairon-ai/aegis pickup --dry-run
npx @nairon-ai/aegis status
npx @nairon-ai/aegis deploy

Releases

Aegis uses semantic-release. Push conventional commits to main:

  • fix: -> patch npm release
  • feat: -> minor npm release
  • feat!: or BREAKING CHANGE: -> major npm release

See docs/RELEASING.md.

Worker endpoints:

GET  /
GET  /api/pickup
POST /api/pickup
POST /api/runs/:id/proceed
POST /api/runs/:id/stop
POST /webhook/github
POST /webhook/linear
POST /webhook/telegram
POST /agents/bug-fix/:runId

Architecture

.flue/app.ts                    Worker app wrapper + Flue route
.flue/agents/bug-fix.ts         Flue coding agent
.agents/skills/bug-fix          Agent instructions
src/server/app.ts               Hono routes, cron, webhooks
src/core/pickup.ts              scan/claim orchestration
src/sources/*                   GitHub + Linear source adapters
src/integrations/*              GitHub, Linear, Telegram, webhook helpers
src/shared/*                    config, types, readiness, formatting

Current Limits

  • Bugs only.
  • PR self-heal is not implemented.
  • WhatsApp is not implemented.
  • Arbitrary third-party tool connectors are not implemented.
  • Cloudflare Sandbox is the primary runtime; freestyle.sh support was removed.

License

MIT