Website • Usage • AGENTS.md conventions • Security • Changelog

Sadr (pronounced SAD-er, /ˈsædər/) is the bright star at the center of the Northern Cross, the heart of the constellation Cygnus.

What is Sadr?

Sadr is a dark factory for software. It works through every repo you own with the lights off, keeping each one current, secure and up to your standards, and building the features waiting in your issues. People set the standard and review what comes out. Nothing in between waits on them.

Cygnus Strategy builds its software with Sadr. It's open source, so you can run your own.

From idea to production

1. You file the idea as an issue, and a maintainer labels it sadr.
2. The nightly Sadr run builds it, alongside keeping dependencies, runtimes and CI current.
3. The pull request merges through your required checks.
4. Your CI deploys it. You never sat through a build session.

What it does

• Builds the issues a maintainer accepts by labeling them sadr.
• Keeps dependencies, runtimes, toolchains and CI current, majors included.
• Hardens the supply chain: releases wait before they're used, and actions and images are pinned.
• Fixes what security scanners find, in the pull request.
• Writes down what it learns about each repo in its AGENTS.md, in a PR of its own.
• Runs on your schedule, within time and spend limits, and merges only when you let it.

Install

Sadr runs three ways. Pick one.

1. Claude Code plugin. Run Sadr from your own machine, by hand or as a Claude Code scheduled task. The plugin updates itself from this repo.

   /plugin marketplace add Cygnus-Strategy/sadr
   /plugin install sadr@sadr
   

   Then ask it to preview Sadr on an org, a list of repos, or one repo. A real run acts as your own Sadr App, so set up option 3 first.

2. GitHub Action. Call Sadr's reusable workflow on a schedule, pinned to a release. Sadr's upkeep PR moves the pin to newer releases after the cooldown.

   on:
     schedule: [{cron: "17 3 * * *"}]   # nightly
   jobs:
     sadr:
       uses: Cygnus-Strategy/sadr/.github/workflows/run.yml@<sha> # v2.0.0
       with:
         sadr-ref: <sha>
       secrets:
         app_id: ${{ secrets.SADR_APP_ID }}
         app_private_key: ${{ secrets.SADR_APP_PRIVATE_KEY }}
         claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

   examples/ has the full workflows for one repo and for a whole organization or user account.

3. Your own Sadr App. Sadr commits, opens PRs and comments as a GitHub App that you create from app/manifest.json and own. Its private key stays in your secrets, so nobody else can act as your Sadr. Use it with the Action or the plugin. Without it, the Action runs in a degraded mode that cannot change workflow files or read other repos.

Manual setup of the Sadr App

1. Serve app/ over HTTP (python3 -m http.server in that folder) and open create.html. Enter your organization, or choose a personal account.
2. Name the App Sadr for and your account name, or another free name. App names are unique across GitHub, and Sadr is reserved.
3. On GitHub, check that the permissions are exactly: Contents, Pull requests, Issues and Workflows read and write, and Administration, Checks, Commit statuses and Metadata read. Create the App.
4. Run the commands the page prints. They store SADR_APP_ID and SADR_APP_PRIVATE_KEY as organization secrets without printing them.
5. In the App's settings, under "Display information", upload assets/app/sadr-app-logo.png.
6. Install the App on your account, on all repositories.
7. Add the workflow from option 2, with a credential for Claude.

app/README.md has the manifest flow request by request, the commands for a personal account, and key rotation. references/permissions.md explains Sadr's identity and tokens.

Agent instructions

Paste this into an AI agent that can drive a web browser and run gh, to set up the App for you:

Set up the Sadr GitHub App for the GitHub account OWNER (an organization unless I say it is a personal account). Use a web browser for the GitHub pages and the gh CLI for secrets. Ask me before any step that needs my password or two-factor code, and let me type those myself.

1. Clone https://github.com/Cygnus-Strategy/sadr. Read app/README.md and app/manifest.json in full.
2. Serve the app/ folder over HTTP on localhost and open create.html in the browser. Enter OWNER. Use the App name "Sadr for OWNER". If GitHub says the name is taken, pick another free name.
3. On GitHub's confirmation page, check that the repository permissions are exactly: Contents, Pull requests, Issues and Workflows read and write; Administration, Checks, Commit statuses and Metadata read; nothing else, no webhook, no events. If they differ, stop and tell me. Otherwise create the App.
4. Run the commands that create.html prints. They store SADR_APP_ID and SADR_APP_PRIVATE_KEY as secrets. Never print, copy or show the private key, and never write it to a file outside a temporary one you delete at once.
5. In the App's settings, under Display information, upload assets/app/sadr-app-logo.png from the clone as the logo.
6. Install the App on OWNER, on all repositories.
7. Confirm with: gh secret list --org OWNER (or --repo for a personal account). Report the App's URL, its slug, and where it is installed. Do not report the key.

Then tell Sadr about each repo in plain language, in the ## Sadr section of its AGENTS.md. USAGE.md shows how to run Sadr, hand it issues, and let it merge. docs/agents-md.md is the full reference.

Design principles

• Light by design. A skill, a few scripts and two workflows. It leans on the model's judgment, not on a heavy harness.
• Lights out. It runs unattended, on your schedule.
• Stateless. What it knows lives in your repos and on GitHub.
• Language over configuration. Settings are sentences in AGENTS.md.
• Fix it, don't file it. Real problems are fixed in the pull request.
• Secure by default. And it meets its own standard.
• People decide what ships. Nothing merges unless you merge it or told it to.
• Nothing to do, nothing sent. A repo that meets the standard gets no PR and no comment.

License

BSD 3-Clause. Made by Cygnus Strategy LLC. Contributions are welcome under the DCO. See CONTRIBUTING.md.