maintainr

maintainr turns incoming GitHub issues into a small, evidence-backed queue of decisions. It also maintains a separate, persisted inventory of repository issues and pull requests. It verifies and durably records GitHub webhooks, analyzes issues asynchronously when writes are enabled, suggests low-risk actions, and keeps every GitHub write behind both runtime policy and explicit maintainer approval.

The repository contains a complete credential-free demo mode plus adapters for a real GitHub App and an optional model provider.

Live GitHub mode is read-only by default. If GITHUB_READ_ONLY is omitted while APP_MODE=github, the API and worker still block GitHub mutations. The inventory path can read, cache, filter, and display issue/PR metadata without adding a file, commit, branch, label, or comment to the target repository. See Read-only GitHub inventory for the defense-in-depth model and the exact mbdalpha/hvac-mpc connection procedure.

Quick start

Requirements: Node.js 24 LTS and npm 11 or newer.

cp .env.example .env
npm ci
npm run demo:reset
npm run dev

Open http://localhost:5173. The API listens on http://localhost:3001; its readiness endpoint is /readyz and the versioned contract is exposed at /api/v1/openapi.json.

The local adapter is the default. It needs neither GitHub credentials nor a model key. npm run demo:reset recreates the database and processes ten deliberately messy issue fixtures through the same signed webhook endpoint used by GitHub.

Hackathon presentation

The stage path uses the public synthetic repository mbdalpha/maintainr-demo as its evidence source. It preloads two OpenAI proofs and leaves one deterministic revision ready for an on-stage OpenAI run. Put an API key in the ignored root .env, then run:

npm ci --strict-allow-scripts
npm run demo:present

The presentation command builds the API and dashboard, reserves a free loopback port, reads the public GitHub repository without a token, makes two featured OpenAI assessment requests using OPENAI_MODEL, and serves the complete app from the one URL printed in the terminal. In the proof carrying the live revision strip, choose Run OpenAI live to make the third request and visibly replace revision 1 with a server-confirmed OpenAI revision 2. Approved actions are recorded only in the dedicated disposable SQLite database: the presentation never labels, comments on, or otherwise changes GitHub.

The seeded story contains three approval-gated decisions plus an issue-and-pull-request inventory. Run the visible OpenAI checkpoint, inspect the new revision's evidence and exact proposed effects, then apply or ignore it to show the durable queue transition. Press Ctrl+C when finished. The presentation database is removed automatically; rerun the same command to reset the story from the beginning.

Keep the credential-free path as the on-stage fallback:

npm run demo:present:offline

Before going on stage, exercise both the deterministic fallback and the live GitHub + OpenAI journey:

npm run demo:smoke
npm run demo:smoke:live

Each smoke command uses its own disposable database and port. The live check requires two preloaded OpenAI proofs, requests the third through the public reanalysis API, polls it for up to 90 seconds, and fails unless the assessment ID changes, the revision advances, and the refreshed provider is OpenAI without a deterministic fallback. Both checks require the session, repository, three-decision queue, mixed issue/PR inventory, terminal decision operation, and queue decrement to work together.

The public fixture repository is intentionally synthetic. Its provisioning script is dry-run by default and idempotent:

npm run demo:github:plan
npm run demo:github:create

The execute form requires an authenticated GitHub CLI account with permission to create mbdalpha/maintainr-demo; it does not clone or push this checkout.

Verification

npm run check
npm run build
npm run format:check
# With PostgreSQL available:
TEST_DATABASE_URL=postgresql://... npm test -w @maintainr/api

Project map

• apps/api — separate API/worker/migration roles, PostgreSQL production queue, loopback SQLite adapter, repository inventory, domain services, OAuth, and external adapters.
• apps/web — replaceable React dashboard and inventory view. They know only the shared API contract.
• packages/contracts — runtime-validated DTOs, replaceable frontend gateway port, and test/demo fixtures.
• deploy/kubernetes — non-root/read-only API, worker, migration, ingress, and network-policy baseline.
• docs/wiki — architecture, security, operations, recovery, extension, and frontend replacement guides.
• MAINTAINR_PLAN.md — original product plan.

Start with the architecture wiki for design rationale and production guidance.

For an interactive local presentation, use the pinned DeepWiki sidecar. It imports the current reviewed wiki without coupling DeepWiki to the API or replaceable frontend.