Cal.com Development Guide for AI Agents

You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.

Do

Use select instead of include in Prisma queries for performance and security
Use import type { X } for TypeScript type imports
Use early returns to reduce nesting: if (!booking) return null;
Use ErrorWithCode for errors in non-tRPC files (services, repositories, utilities); use TRPCError only in tRPC routers
Use conventional commits: feat:, fix:, refactor:
Create PRs in draft mode by default
Run yarn type-check:ci --force before concluding CI failures are unrelated to your changes
Import directly from source files, not barrel files (e.g., @calcom/ui/components/button not @calcom/ui)
Add translations to apps/web/public/static/locales/en/common.json for all UI strings
Use date-fns or native Date instead of Day.js when timezone awareness isn't needed
Put permission checks in page.tsx, never in layout.tsx
Use ast-grep for searching if available; otherwise use rg (ripgrep), then fall back to grep
Use Biome for formatting and linting

Don't

Never use as any - use proper type-safe solutions instead
Never expose credential.key field in API responses or queries
Never commit secrets or API keys
Never modify *.generated.ts files directly - they're created by app-store-cli
Never put business logic in repositories - that belongs in Services
Never use barrel imports from index.ts files
Never skip running type checks before pushing
Never create large PRs (>500 lines or >10 files) - split them instead

PR Size Guidelines

Large PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.

Size Limits

Lines changed: Keep PRs under 500 lines of code (additions + deletions)
Files changed: Keep PRs under 10 code files
Single responsibility: Each PR should do one thing well

Note: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.

How to Split Large Changes

When a task requires extensive changes, break it into multiple PRs:

By layer: Separate database/schema changes, backend logic, and frontend UI into different PRs
By feature component: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)
By refactor vs feature: Do preparatory refactoring in a separate PR before adding new functionality
By dependency order: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)

Examples of Good PR Splits

Instead of one large "Add booking notifications" PR:

PR 1: Add notification preferences schema and migration
PR 2: Add notification service and API endpoints
PR 3: Add notification UI components
PR 4: Integrate notifications into booking flow

Instead of one large "Refactor calendar sync" PR:

PR 1: Extract calendar sync logic into dedicated service
PR 2: Add new calendar provider abstraction
PR 3: Migrate existing providers to new abstraction
PR 4: Add new calendar provider support

Benefits of Smaller PRs

Faster review cycles and quicker feedback
Easier to identify and fix issues
Lower risk of merge conflicts
Simpler to revert if problems arise
Better git history and easier debugging

Commands

File-scoped (preferred for speed)

# Type check - always run on changed files
yarn type-check:ci --force

# Lint and format single file
yarn biome check --write path/to/file.tsx

# Unit test specific file
yarn vitest run path/to/file.test.ts

# Unit test specific file + specific test
yarn vitest run path/to/file.test.ts --testNamePattern="specific test name"

# Integration test specific file
VITEST_MODE=integration yarn test path/to/file.integration-test.ts

# Integration test specific file + specific test
VITEST_MODE=integration yarn test path/to/file.integration-test.ts --testNamePattern="specific test name"

# E2E test specific file
PLAYWRIGHT_HEADLESS=1 yarn e2e path/to/file.e2e.ts

# E2E test specific file + specific test
PLAYWRIGHT_HEADLESS=1 yarn e2e path/to/file.e2e.ts --grep "specific test name"

Project-wide (use sparingly)

# Development
yarn dev              # Start dev server
yarn dx               # Dev with database setup

# Build & check
yarn build                   # Build all packages
yarn biome check --write .   # Lint and format all
yarn type-check              # Type check all

# Tests (use TZ=UTC for consistency)
TZ=UTC yarn test      # All unit tests
yarn e2e              # All E2E tests

# Database
yarn prisma generate  # Regenerate types after schema changes
yarn workspace @calcom/prisma db-migrate  # Run migrations

Biome focused workflow

yarn biome check --write .
yarn type-check:ci --force

Boundaries

Always do

Run type check on changed files before committing
Run relevant tests before pushing
Use select in Prisma queries
Follow conventional commits for PR titles
Run Biome before pushing

Ask first

Adding new dependencies
Schema changes to packages/prisma/schema.prisma
Changes affecting multiple packages
Deleting files
Running full build or E2E suites

Never do

Commit secrets, API keys, or .env files
Expose credential.key in any query
Use as any type casting
Force push or rebase shared branches
Modify generated files directly

Project Structure

apps/web/                    # Main Next.js application
packages/prisma/             # Database schema (schema.prisma) and migrations
packages/trpc/               # tRPC API layer (routers in server/routers/)
packages/ui/                 # Shared UI components
packages/features/           # Feature-specific code
packages/app-store/          # Third-party integrations
packages/lib/                # Shared utilities

Key files

Routes: apps/web/app/ (App Router)
Database schema: packages/prisma/schema.prisma
tRPC routers: packages/trpc/server/routers/
Translations: apps/web/public/static/locales/en/common.json
Workflow constants: packages/features/ee/workflows/lib/constants.ts

Tech Stack

Framework: Next.js 13+ (App Router in some areas)
Language: TypeScript (strict)
Database: PostgreSQL with Prisma ORM
API: tRPC for type-safe APIs
Auth: NextAuth.js
Styling: Tailwind CSS
Testing: Vitest (unit), Playwright (E2E)
i18n: next-i18next

Code Examples

Good error handling

// Good - Descriptive error with context
throw new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);

// Bad - Generic error
throw new Error("Booking failed");

For which error class to use (ErrorWithCode vs TRPCError) and concrete examples, see Error Types in knowledge-base.md.

Good Prisma query

// Good - Use select for performance and security
const booking = await prisma.booking.findFirst({
  select: {
    id: true,
    title: true,
    user: {
      select: {
        id: true,
        name: true,
        email: true,
      }
    }
  }
});

// Bad - Include fetches all fields including sensitive ones
const booking = await prisma.booking.findFirst({
  include: { user: true }
});

Good imports

// Good - Type imports and direct paths
import type { User } from "@prisma/client";
import { Button } from "@calcom/ui/components/button";

// Bad - Regular import for types, barrel imports
import { User } from "@prisma/client";
import { Button } from "@calcom/ui";

API v2 Imports (apps/api/v2)

When importing from @calcom/features or @calcom/trpc into apps/api/v2, do not import directly because the API v2 app's tsconfig.json doesn't have path mappings for these modules, which causes "module not found" errors.

Instead, re-export from packages/platform/libraries/index.ts and import from @calcom/platform-libraries:

// Step 1: In packages/platform/libraries/index.ts, add the export
export { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";

// Step 2: In apps/api/v2, import from platform-libraries
import { ProfileRepository } from "@calcom/platform-libraries";

// Bad - Direct import causes module not found error in apps/api/v2
import { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";

PR Checklist

Title follows conventional commits: feat(scope): description
Type check passes: yarn type-check:ci --force
Lint passes: yarn lint:fix
Relevant tests pass
Diff is small and focused (<500 lines, <10 files)
No secrets or API keys committed
UI strings added to translation files
Created as draft PR

When Stuck

Ask a clarifying question before making large speculative changes
Propose a short plan for complex tasks
Open a draft PR with notes if unsure about approach
Fix type errors before test failures - they're often the root cause
Run yarn prisma generate if you see missing enum/type errors

Business rules

Managed event types

When a managed event type is created we create a managed event type for team (parent managed event type) and for each user that has been assigned to it (child managed event type). Parent managed event type will have "teamId" set in the EventType table row and child one "userId". If we create managed event type and assign Alice and Bob then three rows will be inserted in the EventType table.
It is possible to book only child managed event type.

Organizations and teams both are stored in the "Team" table. Organizations have "isOrganization" set to true, and if the entry has "parentId" set then it means it is a team within an organization.
There are two types of OAuth clients you have to distinguish between:

"OAuth client" which resides in the "OAuthClient" table. This OAuth client allows 3rd party apps users to connect their cal.com accounts.
"Platform OAuth client" which resides in the "PlatformOAuthClient" table. This OAuth client is used only by platform customers integrating cal.com scheduling directly in their platforms. If someone says "platform OAuth client" then they mean the one in the "PlatformOAuthClient" table.

Extended Documentation

For detailed information, see the agents/ directory:

agents/README.md - Architecture overview and patterns
agents/rules/ - Modular engineering rules (performance, architecture, data layer, etc.)
agents/commands.md - Complete command reference
agents/knowledge-base.md - Domain knowledge and best practices
agents/coding-standards.md - Coding standards with examples

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cal.com Development Guide for AI Agents

Do

Don't

PR Size Guidelines

Size Limits

How to Split Large Changes

Examples of Good PR Splits

Benefits of Smaller PRs

Commands

File-scoped (preferred for speed)

Project-wide (use sparingly)

Biome focused workflow

Boundaries

Always do

Ask first

Never do

Project Structure

Key files

Tech Stack

Code Examples

Good error handling

Good Prisma query

Good imports

API v2 Imports (apps/api/v2)

PR Checklist

When Stuck

Business rules

Extended Documentation

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Cal.com Development Guide for AI Agents

Do

Don't

PR Size Guidelines

Size Limits

How to Split Large Changes

Examples of Good PR Splits

Benefits of Smaller PRs

Commands

File-scoped (preferred for speed)

Project-wide (use sparingly)

Biome focused workflow

Boundaries

Always do

Ask first

Never do

Project Structure

Key files

Tech Stack

Code Examples

Good error handling

Good Prisma query

Good imports

API v2 Imports (apps/api/v2)

PR Checklist

When Stuck

Business rules

Extended Documentation