Airlock

The last checkpoint before AI code ships.

Airlock is a mission-control interface for AI-assisted code review before shipping. It watches a local git repository in real time, shows staged/unstaged updates, and provides an AI Control Room for Explain, Review, and Quiz workflows.

What this project does

• Live repository watch for staged + unstaged updates
• File-level stage/unstage actions
• Change Chamber viewer with stacked/split patch modes
• AI Explain assistant on selected file or full change set
• AI Code Review with bug/security/quality findings
• AI Quiz generation with result tracking
• AI commit message generation
• Launch Control + Flight Check governance UI
• Commit, push, and stash actions from the app

Governance behavior

When Launch Control is ON, the UI requires:

1. A quiz result for the current diff hash
2. Clearance for the current diff hash

Flight Check shows:

• Launch Control state
• Quiz status (Ready / Missing / Stale)
• Clearance required/given
• Next move recommendation

Backend strict checks enforce quiz freshness on commit/push.

Tech stack

• Frontend: React + TypeScript + Vite
• Backend: Express + TypeScript
• AI: OpenAI via Codex SDK client
• Diff rendering: @pierre/diffs

Project structure

airlock/
  core/                  # backend service
  frontend/              # React mission-control UI
  testbench/             # grader setup + testing/inference documents and scripts
  README.md

Dependencies

• Node.js 20+
• npm 10+
• Optional: Bun (for workspace scripts)
• OpenAI API key

Environment variables

Create .env in the repository root:

DIFF_REPO_PATH=/absolute/path/to/repo-to-watch
OPENAI_API_KEY=your_openai_api_key
PORT=3001
CORS_ORIGIN=http://localhost:5173

Defaults if not set:

• PORT=3001
• CORS_ORIGIN=http://localhost:5173

Setup and run

Option A: Bun (preferred)

bun install

# terminal 1
bun run dev:core

# terminal 2
bun run dev:frontend

Option B: npm + tsx (fallback)

npm --prefix core install
npm --prefix frontend install

# terminal 1
DIFF_REPO_PATH=/absolute/path/to/repo OPENAI_API_KEY=your_openai_api_key npx tsx core/src/index.ts

# terminal 2
npm --prefix frontend run dev

Open the app at: http://localhost:5173

Build and lint

npm --prefix frontend run build
npm --prefix frontend run lint

Judge / grader testbench

All grader-facing material is in testbench/:

• testbench/SETUP_AND_RUN.md - step-by-step environment setup and app startup
• testbench/TESTING_INFERENCE.md - end-to-end verification and inference walkthrough
• testbench/create_demo_repo.sh - creates a realistic demo repo with staged/unstaged flaws
• testbench/api_smoke.sh - quick backend endpoint sanity checks

Notes for judging

• Use localhost:5173 (not 127.0.0.1:5173) unless you also update CORS.
• For fastest demo path, use testbench/create_demo_repo.sh to generate a realistic sample repo.

License

Hackathon submission repository by 13shreyansh.