Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

• Before submitting a new issue or PR, check if it already exists in issues or PRs.
• GitHub issues: take note of the 🚨 needs approval label.
  • For Contributors:
    • Feature Requests: Wait for a core member to approve and remove the 🚨 needs approval label before you start coding or submit a PR.
    • Bugs, Security, Performance, Documentation, etc.: You can start coding immediately, even if the 🚨 needs approval label is present. This label mainly concerns feature requests.
  • Our Process:
    • Issues from non-core members automatically receive the 🚨 needs approval label.
    • We greatly value new feature ideas. To ensure consistency in the product's direction, they undergo review and approval.

Type of Issue	Priority
Minor improvements, non-core feature requests
Confusing UX (... but working)
Core Features (Booking page, availability, timezone calculation)
Core Bugs (Login, Booking page, Emails are not working)

The development branch is dev. This is the branch that all pull requests should be made against. We will merge into main every week.

To develop locally:

1. Fork this repository to your own GitHub account and then clone it to your local device.

2. Create a new branch:

   git checkout -b MY_BRANCH_NAME

3. Install bun:

   https://bun.sh/docs/installation

4. Install the dependencies with:

   bun i

5. Set up your .env file:

   • Duplicate .env.example to .env.
   • Use openssl rand -base64 32 to generate a key and add it under SECRET_KEY in the .env file.
   • Setup Trigger.dev
     • CD into apps/app and run bunx trigger.dev@latest login, then bunx trigger.dev@latest dev
     • Use openssl rand -base64 32 to generate a key and add it under TRIGGER_SECRET_KEY in the .env file.

6. Start developing and watch for code changes:

   bun run dev

You can build the project with:

bun run build

Please be sure that you can make a full production build before pushing code.

Coming soon.

Coming soon.

To check the formatting of your code:

bun run lint

If you get errors, be sure to fix them before committing.

Every endpoint in apps/api/src/ ships to three places: the public OpenAPI spec (packages/docs/openapi.json), the customer-facing MCP server published as @trycompai/mcp-server on npm, and the runtime ValidationPipe. Endpoints that break the contract either silently fail for AI agents (Claude Desktop, Cursor, Codex, etc.) or reject requests at runtime.

Read the full contract before adding a body-accepting endpoint:

• AI tool users: .claude/skills/api-endpoint-contract/SKILL.md (Claude auto-loads) or .cursor/rules/api-endpoint-contract.mdc (Cursor auto-loads).
• For Codex/ChatGPT and human reading: see the "API Endpoint Contract" section in AGENTS.md.

Short checklist for every body endpoint:

1. DTO is a class (not interface, not inline type).
2. Every field has both @ApiProperty/@ApiPropertyOptional and a class-validator decorator (@IsString, @IsOptional, @IsObject, @IsArray, etc.).
3. @ApiBody({ type: DtoClass }) on the endpoint.
4. @ApiOperation.description ≤ 240 chars (truncator in seo-text.ts).
5. Long-running ops return a run handle and document the poll target — don't make agents wait synchronously.
6. File uploads accept an s3Key field (presigned upload path) — never base64 inline from agents.
7. After your change: bun run --filter '@trycompai/api' dev regenerates packages/docs/openapi.json on boot — commit it with your PR. The daily Speakeasy CI reads from that file.

• Be sure to check the "Allow edits from maintainers" option while creating your PR.
• If your PR refers to or fixes an issue, be sure to add refs #XXX or fixes #XXX to the PR description. Replacing XXX with the respective issue number. See more about Linking a pull request to an issue.
• Be sure to fill the PR Template accordingly.

Lastly, make sure to keep the branches updated (e.g. click the Update branch button on GitHub PR).