Codesteward Review

Agentic code review that knows your graph.
Gate every merge. Steward every branch. Self-hosted.

Node ≥ 22 · pnpm 9 · TypeScript ESM · Apache-2.0

Why Codesteward

Most AI review tools skim a diff and guess. Codesteward runs multi-agent reviews against a structural code graph — call chains, dependencies, auth paths — so findings are grounded in how the codebase actually works.

	Gate	Stewardship
When	PR / MR open, push, or `@codesteward review`	Long-lived branches & paths
Scope	Diff-focused units	Package / path / tree batches
Output	Inline review, check run, verdict	Durable findings lifecycle
Policy	`STEWARD.md` + path rules from base branch	Same model

One finding schema. One policy model. Multi-provider LLMs. Product UI, CLI, GitHub Action, and workers you can scale.

Highlights

Graph-aware agents — specialists use Codesteward Graph (MCP) for structure, not only the patch
Dual mode — PR gate + continuous branch stewardship on one platform
Identity — Keycloak OIDC (SPA PKCE); API validates JWTs (no sticky sessions)
Orgs & policy — members, connectors, STEWARD.md / path rules, learning, optional SCIM
Learning loop — 👍/👎, dismissals, org memories → quieter next reviews
Multi-SCM — GitHub App/webhooks, GitLab, Bitbucket, Azure DevOps, Gitea
Horizontal scale — API/UI stateless; workers × concurrent specialists; optional queue broker + KEDA
Self-hosted — your cloud, your models, your keys

Architecture

┌──────────────┐  SPA OIDC (PKCE)  ┌─────────────────┐
│  UI :8080    │ ───────────────►  │  Keycloak IdP   │
│  React       │ ◄── access_token ─│  MFA / federated│
└──────┬───────┘                   └─────────────────┘
       │ Bearer JWT
       ▼
┌──────────────┐   enqueue    ┌──────────────────────────────┐
│  API :8081   │ ───────────► │  Postgres jobs (default SoT) │
│  Hono        │              │  + optional NATS/Rabbit/Pulsar│
└──────┬───────┘              └──────────────┬───────────────┘
       │ sessions / findings                 │ claim
       ▼                                     ▼
┌──────────────┐                    ┌─────────────────┐
│  Postgres    │                    │  Workers (HPA / │
│  product SoT │                    │  KEDA optional) │
└──────────────┘                    └────────┬────────┘
                                             │
              ┌──────────────────────────────┼────────────────────────┐
              ▼                              ▼                        ▼
     Codesteward Graph MCP           Model router              Sandbox / Prove
     GraphQLite · Neo4j · Janus      OpenAI · Anthropic · SpaceXAI   local · docker · k8s

Layer	Role
UI	Product surface; browser holds OIDC tokens
API	Validates JWT / API key; enqueues reviews; webhooks
Worker	Orchestrator, specialists, judge, SCM publish
Graph	Structural intelligence via MCP
Queue	Postgres by default; optional broker for KEDA depth scaling

Quick start

Category stack (recommended demo)

Full stack: Postgres, Graph MCP, API, worker, UI, Keycloak.

export OPENAI_API_KEY=sk-...   # or compatible provider
pnpm install && pnpm -r run build

pnpm compose:category
# UI  → http://localhost:8080
# API → http://localhost:8081
# IdP → http://localhost:8083  (admin / admin for Keycloak console)

Sign in via the platform IdP (Codesteward-themed Keycloak).
Demo app user (realm seed): admin@demo.com / DemoAdmin.123.

pnpm compose:category:down

Local packages (dev)

pnpm install && pnpm -r run build

# Optional durable state
export DATABASE_URL=postgres://steward:steward@localhost:5432/codesteward
pnpm migrate

export MODEL_PROVIDER=openai-compatible OPENAI_API_KEY=sk-...
pnpm dev:api      # :8081
pnpm dev:worker
pnpm dev:ui       # :8080

CLI

pnpm stew -- doctor full
pnpm stew -- review -p . -r codesteward --tier thorough --depth thorough
pnpm stew -- steward -p . -r codesteward
pnpm stew -- findings export --sarif -s <sessionId>
pnpm stew -- ask "What does a review unit cover?"

GitHub Action

permissions:
  contents: read
  pull-requests: write
  checks: write
  security-events: write   # Code Scanning / Security tab SARIF upload

- uses: ./actions/review-action
  with:
    risk-tier: full
    publish: "true"
    fail-on: high
    sarif-output: codesteward.sarif
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    # Worker/API path also uploads SARIF when publishing to GitHub (set 0 to disable)
    STEW_PUBLISH_SARIF: "1"

# Optional: upload the Action-written file via CodeQL action (needs security-events)
- uses: github/codeql-action/upload-sarif@v4
  if: always()
  with:
    sarif_file: codesteward.sarif
    category: codesteward/gate

Security tab: Codesteward can push SARIF into Security → Code scanning when code scanning is enabled on the repo and the token/app has security_events: write. That is separate from PR review comments and the Checks tab (codesteward/gate check run).

Product capabilities

Review pipeline

Specialists (correctness, security, performance, testing, rules, …) → optional discourse (thorough) → verifier → judge → noise filter → gate verdict → SCM publish (inline comments + check run + optional SARIF → Code Scanning / Security tab).

Policy

STEWARD.md — severity floor, nits, skip globs, verification bar
.codesteward/rules/**/*.md — path-scoped guidance
Always loaded from the base / default branch, not PR head alone

Webhooks & mentions

# GitHub App webhook
# https://<public-api-host>/v1/webhooks/github

# On a PR comment (default mention token):
@codesteward review

Override with STEW_MENTION_TOKEN. Events: pull_request (opened / synchronize / reopened / ready_for_review) and issue_comment for mentions.

Identity & orgs

Keycloak as identity SoT (groups /orgs/{slug}, roles steward-admin|reviewer|viewer)
SPA OIDC login; API validates access tokens via JWKS
Org slug auto-generated from name (409 on collision)
Optional SCIM: /scim/v2/orgs/{orgId|slug} with per-org bearer

Learning

React 👍/👎 on findings, set false-positive / won’t-fix — org memories feed the next review prompt. SARIF export for GHAS / other tools.

Scaling

Concern	Approach
More concurrent reviews	Scale workers (`STEW_MAX_CONCURRENT` specialists per job)
More HTTP / webhooks	Scale API (JWT auth is stateless)
More UI traffic	Scale UI (static nginx)
Queue-depth autoscaling	Optional `STEW_QUEUE_BROKER=nats\|rabbitmq\|pulsar` + KEDA
Broker disaster recovery	Workers still claim from Postgres; platform ops can republish pending jobs to rehydrate broker depth

# Minimal: Postgres only for jobs
DATABASE_URL=postgres://...

# Optional hybrid (PG SoT + broker for KEDA)
STEW_QUEUE_BROKER=rabbitmq
RABBITMQ_URL=amqp://...

# After broker message loss (platform operator):
#   GET  /v1/platform/queue
#   POST /v1/platform/queue/republish   # body: { "limit": 500 } optional
# Or UI: Settings → Platform ops → Job queue recovery

# Helm workers
helm upgrade --install codesteward ./deploy/helm/codesteward \
  --set worker.hpa.maxReplicas=20 \
  --set worker.maxConcurrent=8

Compose brokers: deploy/compose/docker-compose.queue.yml (profiles rabbitmq / nats).

Monorepo

packages/
  core · model-router · graph-client · policy · findings
  learning · db · sandbox · scm · agents · webhooks
  api · cli · mcp-server · ui
services/worker          # job consumer
actions/review-action    # GitHub Action
deploy/compose           # demo + category + keycloak + queue
deploy/helm/codesteward  # production chart + HPA / KEDA
docs/                 # Docusaurus product & operator docs (Cloudflare-ready)

Script	Purpose
`pnpm build`	Build all packages
`pnpm compose:category`	Full product demo stack
`pnpm dev:api` / `dev:worker` / `dev:ui`	Local surfaces
`pnpm stew -- …`	CLI
`pnpm migrate`	Postgres migrations

Configuration sketch

# Graph
GRAPH_MOCK=0
GRAPH_MCP_MODE=stdio                 # embedded codesteward-mcp in the worker
GRAPH_BACKEND=neo4j                  # or graphqlite / janusgraph
# NEO4J_URI=bolt://localhost:7687

# Models
MODEL_PROVIDER=openai-compatible
MODEL_NAME=gpt-4.1-mini
OPENAI_API_KEY=
# STEW_MODEL_JUDGE=…  STEW_MODEL_CHEAP=…

# Auth (category stack sets these for Keycloak)
STEW_IDENTITY_MODE=keycloak
OIDC_ISSUER=http://keycloak:8083/realms/codesteward
OIDC_PUBLIC_ISSUER=http://localhost:8083/realms/codesteward
OIDC_CLIENT_ID=codesteward-ui

# Webhooks (public URL required for live GitHub)
STEW_WEBHOOK_PUBLIC_URL=https://your-tunnel.example
GITHUB_WEBHOOK_SECRET=...
STEW_MENTION_TOKEN=@codesteward

See .env.example for the full template.

Graph backends

Backend	Use	Notes
GraphQLite	Laptop / demo	Embedded SQLite graph
Neo4j	Production default	`deploy/compose/docker-compose.neo4j.yml`
JanusGraph	Large scale	Apache-2.0 path
Mock	CI	`GRAPH_MOCK=1`

Changelog & release

CHANGELOG.md — Keep a Changelog (current: 1.2.0)
CI — .github/workflows/ci.yml (build, typecheck, unit tests, Semgrep, zizmor, dependency-review)
Release — tag vX.Y.Z → .github/workflows/release.yml publishes GHCR images + GitHub Release notes from the matching changelog section:

# After CHANGELOG has ## [1.2.0] and versions are bumped
git tag v1.2.0
git push origin v1.2.0

Images (Codesteward/codesteward → GHCR, lowercased):

Image	Dockerfile	Tags
`ghcr.io/codesteward/codesteward`	`deploy/compose/Dockerfile.node` (API; `SERVICE=worker` for workers)	product semver (`1.2.0`)
`ghcr.io/codesteward/codesteward/ui`	`deploy/compose/Dockerfile.ui`	product semver
`ghcr.io/codesteward/codesteward/keycloak`	`deploy/compose/keycloak/Dockerfile`	upstream Keycloak (`26.7.0`, not product)
Helm chart `oci://ghcr.io/codesteward/codesteward/charts/codesteward`	`deploy/helm/codesteward`	product semver

Codesteward Graph (MCP) image used by compose stacks:

Image	Source
Embedded `codesteward-mcp` (PyPI) in worker image	Graph MCP stdio — no separate graph container

Also: weekly security scans, OpenSSF Scorecard, Renovate (renovate.json).

Status

Self-hosted dual-mode review platform with product UI, Keycloak identity, orgs, webhooks, and horizontal workers.

This release is free to run under Apache-2.0 — use your own models, keys, and infra.

License

Codesteward Review is licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE.

You may use, modify, and self-host this software under the terms of that license.

Codesteward Graph (when used as a dependency or service) is separately distributed under Apache-2.0.

Govern · Verify · Evolve

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
actions/review-action		actions/review-action
deploy		deploy
docs		docs
evals		evals
packages		packages
scripts		scripts
services/worker		services/worker
skills		skills
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.semgrepignore		.semgrepignore
.trivyignore		.trivyignore
CHANGELOG.md		CHANGELOG.md
CLA.md		CLA.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
STEWARD.md		STEWARD.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
renovate.json		renovate.json
tsconfig.base.json		tsconfig.base.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Codesteward Review

Why Codesteward

Highlights

Architecture

Quick start

Category stack (recommended demo)

Local packages (dev)

CLI

GitHub Action

Product capabilities

Review pipeline

Policy

Webhooks & mentions

Identity & orgs

Learning

Scaling

Monorepo

Configuration sketch

Graph backends

Changelog & release

Status

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Codesteward Review

Why Codesteward

Highlights

Architecture

Quick start

Category stack (recommended demo)

Local packages (dev)

CLI

GitHub Action

Product capabilities

Review pipeline

Policy

Webhooks & mentions

Identity & orgs

Learning

Scaling

Monorepo

Configuration sketch

Graph backends

Changelog & release

Status

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages