twentyhq/twenty instruction manual

1. What Twenty is and how it relates to Claude Code

Twenty is a public TypeScript monorepo for an open-source CRM intended to be customized and versioned like application code. Its documented product building blocks are CRM objects, fields, views, layouts, workflows, logic functions, front components, AI agents and chats. The implementation stack named by the project includes Nx, NestJS, BullMQ, PostgreSQL, Redis, React, Jotai, Linaria and Lingui.

**Claude Code classification:** `claude_extension` with the mechanisms `context_injection` and `tool_surface`, alongside a standalone CRM platform. This classification is supported by the official `packages/twenty-agent-skills` package: its skills can be installed into Claude Code through the `skills` CLI, and its `use-twenty-mcp` skill explains how to connect to workspace records through MCP. The skills inject app-development guidance; a user-specific MCP endpoint exposes workspace data as tools. Twenty is not merely a Claude Code add-on, however: the main repository is the CRM, SDK, UI library, desktop companion, documentation, and deployment infrastructure.

Use one of three documented entry paths. For the managed service, sign up at [twenty.com](https://twenty.com); the README describes this as the fastest path, with no infrastructure to manage. To build an extension app, scaffold with:

npx create-twenty-app my-app

To operate Twenty on your own infrastructure, follow the linked Docker Compose documentation. Kubernetes and Podman files are explicitly community-maintained rather than supported by the core team.

2. Scaffold and run a Twenty application

`create-twenty-app` is the official scaffolding CLI. It creates a TypeScript project with linting, tests, and a configured `twenty` command; it also starts a local Twenty server through Docker and authenticates with a development API key. The documented quick start is:

npx create-twenty-app@latest my-twenty-app
cd my-twenty-app
yarn twenty dev

The development process synchronizes app code and generates the typed client. Keep it running while developing. If the server does not start, verify Docker and inspect the app server logs using the documented commands:

docker info
yarn twenty docker:logs

If authentication fails, reconfigure the remote:

yarn twenty remote:add

The scaffolder accepts `--name <name>`, `--display-name <displayName>`, `--description <description>`, and `--url <url>`. The default workspace URL is `http://localhost:2020`. `--authentication-method <method>` accepts `oauth` or `apiKey`; the documented default is API-key authentication for local work and OAuth for remote workspaces.

For an existing project, install the SDK and client SDK instead of scaffolding:

yarn add twenty-sdk twenty-client-sdk

Add `"twenty": "twenty"` under `scripts` in `package.json`, then inspect the available CLI commands with:

yarn twenty help

Credentials are stored per remote in `~/.twenty/config.json`. Use `yarn twenty remote:add` to add or reauthenticate a remote and `yarn twenty remote:list` to inspect configured remotes. Restart `yarn twenty dev` when generated typings are stale or changes are not appearing.

3. Define, develop, manage, and publish apps

Twenty apps define CRM structure as code. The supplied example creates a `deal` object with text, currency, and date-time fields:

import { defineObject, FieldType } from 'twenty-sdk/define';

export default defineObject({
  nameSingular: 'deal',
  namePlural: 'deals',
  labelSingular: 'Deal',
  labelPlural: 'Deals',
  fields: [
    { name: 'name', label: 'Name', type: FieldType.TEXT },
    { name: 'amount', label: 'Amount', type: FieldType.CURRENCY },
    { name: 'closeDate', label: 'Close Date', type: FieldType.DATE_TIME },
  ],
});

Publish an app privately to the configured workspace with:

npx twenty app:publish --private

The official skill collection divides the lifecycle into five plain-language workflows. `create-app` scaffolds a new app. `develop-app` adds or changes objects, fields, logic functions, layouts, front components, and workflows. `manage-app` covers remotes, synchronization, builds, deployments, logs, troubleshooting, and CI/CD. `publish-app` prepares the README, marketplace metadata, logos, screenshots, and public assets. `use-twenty-mcp` connects to workspace records and formats them as readable Markdown.

The four app-development skills do not require MCP. They support hosted Twenty subdomains, custom HTTPS domains, self-hosted instances, and localhost HTTP URLs. Workspace addresses and credentials remain in each user’s local configuration according to the package README.

The old `twenty-cli` package is deprecated. Replace it with the SDK CLI using only the documented migration commands:

npm uninstall twenty-cli
npm install -g twenty-sdk

4. Install the official Claude Code skills and connect MCP

Install the built skill distribution from the `agent-skills` publishing branch, not from the source package on `main`. List available skills, install selected skills, or install all five:

npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list
npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill create-app
npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill develop-app
npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill '*'

The CLI prompts for a target agent. The README also documents `--agent`, including `--agent claude-code`, `--agent codex`, and `--agent '*'`. Each installed skill carries its required references. The branch exists only after the first successful publish from `main`; before that, use the documented local build procedure in Section 8.

Workspace MCP access is separate and user-specific. From a repository checkout, the setup helper accepts a Twenty subdomain, custom domain, or localhost address, normalizes it to `/mcp`, and assigns a host-derived server name:

bash packages/twenty-agent-skills/scripts/setup-mcp.sh myworkspace.twenty.com

For Codex, the equivalent manual setup is:

codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp
codex mcp login twenty-myworkspace

These Codex commands are not Claude Code setup commands; other clients must follow the package’s linked client-specific setup reference. The Codex plugin additionally bundles the public `twenty-docs` MCP server for official documentation search, but workspace data still requires the user’s own endpoint. The distribution supplies no `.app.json`, and a workspace MCP URL is not a ChatGPT connector identifier.

5. Use the twenty-ui React component library

`twenty-ui` is an alpha React 19 library containing components, icons, design tokens, utilities, and a zero-runtime CSS-variable styling layer. APIs and behavior may change between releases. In a standalone React application, install the library and peer dependencies:

npm install twenty-ui react@^19 react-dom@^19

Only consumers of `twenty-ui/components/code-editor` need the optional Monaco packages:

npm install @monaco-editor/react monaco-editor

Import base styles once, choose a light or dark theme stylesheet, and wrap the application in `ThemeProvider`:

import { ThemeProvider } from 'twenty-ui/theme-constants';
import { Button } from 'twenty-ui/primitives/input';

import 'twenty-ui/style.css';
import 'twenty-ui/theme-light.css';

export const App = () => (
  <ThemeProvider colorScheme="light">
    <Button>Click me</Button>
  </ThemeProvider>
);

Prefer subpath imports for tree-shaking; the root entry is also supported. Major subpaths cover assets, shared components, code editor, icons, foundational primitives, accessibility, data display, feedback, inputs, JSON visualization, layout, navigation, surfaces, typography, testing decorators, themes, theme constants, hooks, and utilities. `ThemeProvider` exposes the active theme through `useTheme()` and applies a `light` or `dark` class. `applyToRoot={false}` plus `overrides` scopes a theme to a subtree.

For Twenty apps, keep `twenty-ui`, `twenty-sdk`, and `twenty-client-sdk` at the same version; the front-component renderer supplies the workspace theme. Toast consumers call `useToast()` under a `ToastProvider`; each provider owns an internal store and queue.

6. Twenty desktop companion: meetings and recording

The Electron companion shows upcoming calendar events, joins meetings, records scheduled or unscheduled conversations, and opens recordings, transcripts, and summaries in the connected Twenty workspace. Home shows the next three events and five recent recordings. The native menu provides meeting times, join actions, per-meeting auto-join skips, and recording policy. Users can start, pause, resume, and finish a desktop recording; the timer excludes paused time.

This documented development build requires an Apple Silicon Mac with macOS 14.2 or newer. Windows and Linux recording and packaging are not implemented. A workspace administrator must install and configure the independent Desktop Recorder integration and Recall. Users then enter the workspace URL, authenticate in a browser, grant microphone, system-audio, and meeting-detection permissions, and optionally connect a calendar. Desktop recording requires an internet connection; summaries require Twenty AI configuration. Participants should be told when recording.

Auto-join is enabled by default but does not activate the camera or microphone. Automatic desktop recording is optional and off by default. Manual capture records microphone and all computer audio, has no video, and should not be used when a calendar bot is already recording the same meeting. Network loss stops capture; there is no offline mode or automatic restart.

Tokens are stored with macOS Keychain-backed Electron `safeStorage`; credentials and Recall upload tokens remain in the main process rather than the renderer. The desktop discovers service domains from the authenticated server and uses short-lived upload tokens. Closing the window leaves the menu-bar app running; quitting stops it. The feature set does not include Granola-style note editing, AI chat, or folders.

7. Self-hosting, documentation, email, frontend, and E2E utilities

The core team documents Docker as its maintained self-hosting route. The supplied Kubernetes, Helm, Podman, raw manifests, and Terraform material is community-maintained. The Helm chart is preferred over legacy manifests. Its documented quick install requires a configured cluster, Helm 3, and a real domain:

export DOMAIN=your-domain.com
helm install my-twenty packages/twenty-docker/helm/twenty \
  --namespace twentycrm --create-namespace --wait \
  --set server.ingress.hosts[0].host=$DOMAIN \
  --set server.ingress.hosts[0].paths[0].path=/ \
  --set server.ingress.hosts[0].paths[0].pathType=Prefix \
  --set server.ingress.tls[0].hosts[0]=$DOMAIN

The documentation package contains user, developer, and UI-library guides. Run or validate it from the monorepo root:

npx nx run twenty-docs:dev
npx nx run twenty-docs:validate

Navigation uses `navigation/base-structure.json` as its source, generated label templates for Crowdin, locale label files, and generated `docs.json`. After navigation edits, the documented scripts are `yarn docs:generate-navigation-template` and `yarn docs:generate`. UI references use `npx nx generate:ui twenty-docs`; check generated references and public imports with `npx nx check:ui twenty-docs`.

Twenty Emails supplies React Email templates with Lingui internationalization. Preview on port 4001 or build with:

npx nx start twenty-emails
npx nx build twenty-emails

For the frontend package, the sole documented instruction is to run `yarn dev` while the server is on port 3000. E2E utilities install browsers and run tests through `npx nx setup twenty-e2e-testing` and `npx nx test twenty-e2e-testing`; `test:ui`, `test:debug`, and `test:report` provide interactive, debug, and report modes.

8. Repository development, validation, and known boundaries

For general SDK development, clone and install the monorepo, then use the documented Nx targets:

git clone https://github.com/twentyhq/twenty.git
cd twenty
yarn install
npx nx run twenty-sdk:dev
npx nx run twenty-sdk:build
npx nx run twenty-sdk:start -- <command>

Build and validate Agent Skills locally before installation:

npx nx run twenty-agent-skills:validate
npx nx run twenty-agent-skills:build
npx skills add ./packages/twenty-agent-skills/dist --skill create-app
npx nx run twenty-agent-skills:test

For `twenty-ui`, the supplied checks build the dual ESM/CJS package and types, run Storybook, run unit tests, or target one Vitest file:

npx nx build twenty-ui
npx nx storybook:serve:dev twenty-ui
npx nx test twenty-ui
npx vitest run --root packages/twenty-ui --project unit <file>

For the companion, use Node 24 and the repository’s Yarn version. Its development, typecheck, test, build, and package workflows are documented, but generated applications are unsigned local builds rather than distributable releases. Signing, notarization, update delivery, billing-enabled credit tests, and supported-provider recording checks remain required before production distribution. Preview mode simulates UI state and captures no audio or external data.

Evidence boundaries matter: the supplied files do not provide the complete user guide, API reference, Docker Compose procedure, individual skill bodies, or every package README. Therefore this manual does not infer undocumented commands or behavior. Repository metadata reports `NOASSERTION` for the overall SPDX license; supplied first-party files identify `twenty-ui` as MIT and the documentation as AGPL-3.0, so review the applicable directory license before reuse.