Kodiai is an installable GitHub App that delivers AI-powered code review, conversational assistance, issue intelligence, and Slack integration. One installation replaces per-repo workflow YAML — configure behavior with an optional .kodiai.yml file.

Service-level runtime features like Slack webhook relay are configured through environment variables, not .kodiai.yml.

31 milestones shipped (v0.1 through v0.31). See CHANGELOG.md for documented release history.

• Bun runtime
• PostgreSQL with the pgvector extension
• A GitHub App with webhook secret and private key
• A VoyageAI API key for embeddings

# Clone and install
git clone https://github.com/xbmc/kodiai.git
cd kodiai
bun install

# Configure local environment / deploy inputs
cp .env.example .env
# Fill in the values you need locally; do not commit .env

# Start the dev server
bun run dev

For local development, .env is the source of truth for application startup and for deploy.sh input values.

For production, the source of truth is the Azure Container Apps runtime secret set wired into the Container App through secret references. The checked-in .env.example file is a bootstrap/template surface for local work and deploy input collection; it is not the production runtime contract.

The server exposes:

Kodiai runs as a Bun + Hono HTTP server backed by PostgreSQL with pgvector for hybrid retrieval. It uses multi-model LLM routing via Vercel AI SDK, VoyageAI embeddings, and deploys to Azure Container Apps.

The system processes GitHub webhooks through a job queue with per-installation concurrency limits, uses Azure Files-backed workspaces for code analysis, and executes agentic tasks via isolated Azure Container App jobs that write result.json back to the shared workspace. Review-time structural analysis now consumes the persisted review graph substrate and canonical current-code corpus through a bounded structural-impact layer.

For the full architecture walkthrough — components, data flow, retrieval pipeline, structural-impact layer, and extension points — see docs/architecture.md.

Recent shipped milestones include:

• M051 manual rereview hardening around the explicit @kodiai review contract
• M052 Slack webhook relay operations
• M053 removal of unsafe new Function() usage proven by verify:m053
• M054 planning/verification surface repair proven by verify:m054:s01 and verify:m054:s04

Nightly maintenance workflows are part of the shipped operator surface:

• nightly-issue-sync runs bun scripts/backfill-issues.ts --sync
• nightly-reaction-sync runs bun scripts/sync-triage-reactions.ts
• both workflows support workflow_dispatch for manual retries
• operators should inspect GitHub Actions workflow run status first when a nightly sync fails

Code Review — Automatic PR review with inline suggestions, draft-aware tone, incremental re-review on changed hunks, explicit @kodiai review requests that publish through the dedicated interactive-review lane, dependency bump deep-review, bounded shallow-clone diff fallback for both automatic and explicit review flows, risk-weighted file prioritization for large PRs, collapsed clean approvals, and bounded Structural Impact evidence grounded in graph blast-radius plus canonical current-code retrieval.

@kodiai Mentions — Conversational responses to @kodiai across issue comments, PR comments, and review threads with context-aware follow-ups.

Issue Intelligence — Auto-triage with template validation, label recommendations, duplicate detection, troubleshooting synthesis from resolved issues, and PR creation from issues via apply:/change: commands.

Slack Integration — Thread-based assistant in #kodiai with read-only default, explicit write-mode activation, high-impact confirmation gating, and a verified webhook-to-Slack relay surface with explicit filtering and delivery diagnostics.

Knowledge System — 6-corpus hybrid retrieval (code, review comments, wiki, code snippets, issues, canonical current-code) with BM25 + vector search, Reciprocal Rank Fusion merging, and post-RRF neural reranking.

Epistemic Guardrails — 3-tier knowledge classification with severity demotion for unverifiable claims, applied across all response surfaces.

Contributor Profiles — GitHub/Slack identity linking, expertise inference with decay scoring, 4-tier adaptive review depth, persistence-time tier recalculation, truthful review-surface contributor guidance, and bounded cache/fallback author labeling.

Review Pattern Clustering — HDBSCAN + UMAP theme detection injected as footnotes in PR reviews.

Per-repo behavior is controlled by .kodiai.yml — review strictness, model overrides, write-mode rules, and more.

Service-level runtime configuration and secrets are separate from .kodiai.yml:

• local development and manual deploy input come from .env
• production runtime secrets come from Azure Container Apps secret references on the app

See docs/configuration.md for the complete reference.

For environment variables and application-level settings, see .env.example.

# Run tests (discovery configured in bunfig.toml, scans src/)
bun test

# Type check
bunx tsc --noEmit

Full documentation lives in the docs/ directory:

• Documentation Index — Start here for architecture, configuration, runbooks, and operational guides
• Architecture — System design, components, data flow
• Configuration — .kodiai.yml reference and environment variables

Kodiai deploys to Azure Container Apps via ACR remote build with zero-downtime rolling deploys, and the deploy script reports the active revision for post-deploy proof.

See docs/deployment.md for details. For diagnosing review-request issues, see docs/runbooks/review-requested-debug.md. For Slack assistant operations, see docs/runbooks/slack-integration.md. For webhook relay setup and troubleshooting, see docs/runbooks/slack-webhook-relay.md.

See CONTRIBUTING.md for development workflow, coding standards, and how to submit changes.

Proprietary. All rights reserved.