open-agents: Instructions file for Codex

AGENTS.md

This file provides guidance for AI coding agents working in this repository.

This is a living document. When you make a mistake or learn something new about this codebase, add it to Lessons Learned.

Quick Links

• Architecture & Workspace Structure
• Code Style & Patterns
• Lessons Learned

Authentication

Authentication uses Better Auth with Vercel OAuth (sign-in) and GitHub OAuth (repo access). Config lives in apps/web/lib/auth/config.ts. Sessions are managed by better-auth's built-in session system — there is no manual JWE/encryption layer.

Key env vars: BETTER_AUTH_SECRET (session signing), NEXT_PUBLIC_VERCEL_APP_CLIENT_ID + VERCEL_APP_CLIENT_SECRET (Vercel OAuth), plus GitHub App credentials for repo access. See apps/web/.env.example for the full list.

Database & Migrations

Schema lives in apps/web/lib/db/schema.ts. Migrations are managed by Drizzle Kit.

After modifying schema.ts, always generate a migration:

pnpm --dir apps/web db:generate   # Creates a new .sql migration file

Commit the generated .sql file alongside the schema change. Do not use db:push except for local throwaway databases.

Migrations run automatically during pnpm build (via lib/db/migrate.ts), so every Vercel deploy — both preview and production — applies pending migrations to its own database.

Environment isolation

Neon database branching is enabled in the Vercel project settings. Every preview deployment automatically gets its own isolated database branch forked from production. This means preview deployments never read or write production data. Production deployments use the main Neon database.

Commands

# Development
pnpm web            # Run web app

# Quality checks (REQUIRED after making any changes)
pnpm run ci                             # Required: run format check, lint, typecheck, and tests
turbo typecheck                            # Type check all packages

# Linting and formatting (Ultracite - oxlint + oxfmt, run from root)
pnpm check                              # Lint and format check all files
pnpm fix                                # Lint fix and format all files

# Filter by package (use --filter)
turbo typecheck --filter=web # Type check web app only

# Testing
bun test                                              # Run all tests
bun test path/to/file.test.ts                         # Run single test file
bun test --watch                                      # Watch mode
pnpm test:verbose                                  # Run tests with JUnit reporter streamed to stdout (useful in non-interactive shells)
pnpm test:verbose path/to/file.test.ts             # Same verbose output for a single test file