Codekeeper
Codekeeper is a guided CLI that installs an always-available maintainer in a GitHub.com repository. It reviews pull requests, triages issues, audits repository health, and can prepare small, verified repairs from GitHub Actions you own.
You do not write the workflows by hand. The CLI helps you choose models, capabilities, validation commands, and GitHub App permissions, then opens a setup pull request for you to review. It never merges that pull request.
Requires Node.js 22 or newer, Git, an authenticated GitHub CLI, and permission to administer the target repository.
Install
From a clean checkout of the repository's default branch:
npx @coryparry/[email protected] init
The installer:
- checks Node, Git, GitHub CLI authentication, admin access, and checkout state;
- lets you choose Recommended (automatic PR review and manual maintenance) or Customize;
- helps you create an adopter-owned GitHub App with the required permissions;
- uploads provider credentials and the App private key to GitHub secrets; and
- opens a setup pull request. It does not merge it.
After you merge that pull request, from a clean checkout of the default branch:
npx @coryparry/[email protected] verify
Open one small same-repository pull request and confirm the App-authored review before you make the review gate required.
What the installer writes
Selected workflows determine the exact set. A Recommended install typically includes:
.github/codekeeper.json— policy, models, and safety boundaries.github/codekeeper-release.json— installed package identity and receipt.github/codekeeper/README.md— ownership of installed files.github/codekeeper/actions/acquire-package/action.yml— exact package fetch.github/workflows/codekeeper.yml— one static caller for every installed mode.github/workflows/codekeeper-runtime.yml— shared compute, validate, publish, and credential-proof jobs
Optional .github/codekeeper/agents/*.md files override packaged agent
profiles after they merge to the default branch.
GitHub App and secrets
The installer creates or updates repository secrets and variables. It does not print their values.
Typical names:
| Name | Kind | Purpose |
|---|---|---|
CODEKEEPER_ENABLED | variable | Startup switch; set last |
CODEKEEPER_APP_CLIENT_ID | variable | GitHub App client ID |
CODEKEEPER_AUTOMATION_BOT_LOGIN | variable | Trusted App bot login |
CODEKEEPER_APP_PRIVATE_KEY | secret | App PEM |
OPENAI_API_KEY | secret | OpenAI model calls when selected |
DEEPSEEK_API_KEY | secret | DeepSeek when selected |
OPENROUTER_API_KEY | secret | OpenRouter when selected |
OPENAI_TRACE_API_KEY | secret | Optional tracing; do not reuse the model key |
Install the App only on the selected repository. Do not paste the PEM into the terminal; choose the downloaded file in the installer.
CLI
npx @coryparry/[email protected] init
npx @coryparry/[email protected] update
npx @coryparry/[email protected] update --to X.Y.Z
npx @coryparry/[email protected] update --check
npx @coryparry/[email protected] rollback --to X.Y.Z
npx @coryparry/[email protected] doctor [--json]
npx @coryparry/[email protected] verify [--json] [--controlled]
init also reopens guided settings for an existing installation. update
moves to a newer verified release. rollback --to asks that older release to
open a normal update pull request; it never force-pushes.
To pack this source checkout into a local tarball instead of using npm, see INSTALL.md.
Supported surface
- GitHub.com repositories. GitHub Enterprise Server is not supported.
- Review: same-repository, non-draft pull requests.
- Automatic repair and automatic merge stay limited to the configured default branch.
- Forks, drafts, and merge queues are outside the supported surface.
- Installed runtimes use ephemeral GitHub-hosted Ubuntu runners. Persistent shared self-hosted runners are unsupported.
- Code-changing capabilities need a deterministic repository validation command
beyond
git diff --check.
Recommended starts with repair, issue implementation, duplicate closure, scheduled maintenance, tracing, and automatic merge off.
Documentation
The installer records the exact Git commit of a package build in generated asset metadata. Do not hand-edit that commit.
Security
Do not commit provider keys, GitHub App private keys, tokens, or live traces. Report vulnerabilities through GitHub private vulnerability reporting as described in SECURITY.md.
License
Apache-2.0. See LICENSE.