# Project pack: Twenty @ c13b414

Facts about **Twenty** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Twenty is an open-source CRM, an alternative to Salesforce and HubSpot. You track people, companies and deals, customise objects and fields, view data as tables or boards, and connect email and calendar. It is built with modern web tools and has an API and a way to build your own apps.

## Version and source
- Repository: https://github.com/twentyhq/twenty
- Pinned commit: `c13b414b7a5a8a0a9c4f967be40bfa2c5a3a175e`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/twentyhq/twenty/archive/c13b414b7a5a8a0a9c4f967be40bfa2c5a3a175e.zip
- Official docs: https://docs.twenty.com
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. Files marked Enterprise are under a commercial licence, and some packages are MIT. Check each file's header before reusing it.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/twentyhq/twenty bespoke-twenty
  cd bespoke-twenty
  git checkout --detach c13b414b7a5a8a0a9c4f967be40bfa2c5a3a175e
  # Prepare development requirements and local configuration first.
  corepack enable
  yarn install
  npx nx database:reset twenty-server
  yarn start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the self-hosting guide at https://docs.twenty.com/developers/self-host/self-host, which provides a Docker Compose file.
  ```

- Needs: Docker with 4 GB or more of memory; Node 24 and Yarn 4 for development
- Develop: `yarn start`
- Test: `npx nx test twenty-server`
- Check/lint: `npx nx lint:diff-with-main twenty-server`
- Stack: typescript (React, NestJS, GraphQL, TypeORM, Nx, Yarn 4). Difficulty for a non-developer with an AI: **advanced**. A large Nx monorepo. The product is designed for customisation inside the app: objects, fields, views and apps. Changing the core needs the full toolchain and plenty of memory.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **objects-and-fields** [settings]: Add your own objects (such as Properties or Pets), fields and relations. → `Settings → Data model`
- **views-and-workflows** [settings]: Saved filters, pipelines and automations. → `Views, Kanban, Workflows`
- **apps-and-api** [extend]: Build small apps and integrations with the SDK. → `packages/twenty-apps, packages/twenty-sdk, GraphQL and REST APIs`
- **front-end** [code]: New screens and components. → `packages/twenty-front/src`
- **server** [code]: New back-end modules and jobs. → `packages/twenty-server/src`

## Must keep working
- Database migrations in packages/twenty-server. Add new ones; never edit old ones.
- Workspace data isolation and permission checks.
- GraphQL schema compatibility. Regenerate types after changes.

## Staying updatable
Use objects, fields, workflows and the SDK first. For code changes, stay out of Enterprise-licensed files and keep patches small.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database plus a files store. Contains personal data about contacts. Treat it under your privacy laws and back it up.
- Service: Email and calendar connection (Google or Microsoft) (optional, free): Sync emails and meetings to contacts.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations and notifications.
- Setting `APP_SECRET` (**secret**: the person enters it themselves, never in chat): Secret used to sign logins. Never paste it into an AI chat.
- Setting `PG_DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Postgres connection string. Contains a password.
- Setting `SERVER_URL`: The address people use to reach Twenty.
- It stores personal data about other people. Follow privacy rules and limit access.
- Keep APP_SECRET and database passwords out of Git and chats.

---

# Customising Twenty

Twenty is made to be customised inside the app, so start with the data model. The monorepo is large, so only fork it when an app cannot do the job.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Front end | packages/twenty-front/src/ |
| API, GraphQL and jobs | packages/twenty-server/src/ |
| Shared types | packages/twenty-shared/ |
| UI components | packages/twenty-ui/ |
| Apps and SDK | packages/twenty-sdk/ and packages/twenty-apps/ |
| Self-host setup | packages/twenty-docker/ |
| End-to-end tests | packages/twenty-e2e-testing/ |

## Use the gentlest change first

1. **Settings (no code):** objects, fields, views, roles and workflows.
2. **Extend:** the SDK and the REST and GraphQL APIs.
3. **Code:** front-end components and server modules.

## Recipes

- **New object:** create it in Settings → Data model first. Only write code if the standard views are not enough.
- **New app:** use the `create-twenty-app` package and the SDK to define objects, logic and UI extensions.

## Running and checking your changes

- `yarn start` runs front end, server and worker together.
- `npx nx test twenty-server` and the same for `twenty-front`.
- Run `npx nx build twenty-shared` after changing shared code.

## Pitfalls

- `twenty-shared` must be rebuilt after branch switches.
- Do not copy files marked as Enterprise.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/twenty/c13b414/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/twenty/c13b414/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/twenty/c13b414/r2/SKILL.md)