twentyhq/twenty installation guide

Install Twenty’s official Agent Skills for Claude Code on Apple-silicon macOS Tahoe

What this installation covers

The `twentyhq/twenty` repository is primarily the source monorepo for **Twenty**, an open-source CRM. You do **not** need to install the entire CRM, its Electron companion, Kubernetes files, or its React UI library merely to use its Claude Code integration.

For Claude Code, the relevant component is **Twenty Agent Skills** in `packages/twenty-agent-skills`. It provides five skills for creating, developing, managing, and publishing Twenty apps, plus a skill for using a Twenty workspace through MCP.

**Classification:** `claude_extension`

**Mechanisms:**

• **Context injection:** the installed Agent Skills give Claude Code specialized instructions and references for Twenty app development.
• **Tool surface, optional:** the `use-twenty-mcp` skill describes connecting to workspace data through MCP, but MCP access requires separate, private client configuration.

The four app-development skills work without MCP. The repository does not document a Claude Code plugin manifest or Claude-specific shell installer; installation is performed through the cross-harness `skills` CLI.

macOS Tahoe and Apple-silicon compatibility

The supplied Agent Skills documentation does not state a minimum macOS version, CPU architecture, or a Tahoe-specific compatibility test. Its installation uses `npx`, so there is no documented Rosetta requirement or Apple-silicon binary to install for the skills themselves.

This guide is therefore suitable for Terminal on an Apple-silicon Mac, but it cannot claim that the project formally certifies macOS Tahoe. The repository’s separate Electron companion does mention Apple-silicon support, but that application is an unsigned development build for recording meetings and is **not** the Claude Code extension covered here.

Before you begin

You need:

1. **Claude Code already installed.** The supplied repository files do not provide a Claude Code installation command, so this guide does not invent one.
2. **A Node.js environment that provides `npx`.** No supported Node version or Node installation command is stated for the published Agent Skills, so install Node separately if `npx` is unavailable.
3. **Internet access** to retrieve the skill distribution from GitHub and run the npm-hosted `skills` CLI.
4. A **Twenty workspace** only when you want to connect, synchronize, or publish. Merely installing the skills does not require workspace MCP access.
5. **Docker running** only if you later scaffold a Twenty app and use its automatic local Twenty server. Docker is not required just to add the Agent Skills.

Open **Terminal** on your Mac. Run each command exactly as shown. In particular, retain the quotes around `'*'`; without them, the default macOS shell may interpret the asterisk itself.

Recommended installation from the published skills branch

The repository publishes a generated, self-contained distribution on its `agent-skills` branch. The source package on `main` is not directly installable through the `skills` CLI because its references are shared between skills.

Step 1: List the available skills

Run:

npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list

The documented collection contains:

• `create-app` — scaffold a new Twenty app.
• `develop-app` — change objects, fields, logic functions, layouts, front components, and workflows.
• `manage-app` — manage remotes, synchronization, builds, deployment, logs, troubleshooting, and CI/CD.
• `publish-app` — prepare an app’s README, marketplace metadata, logos, screenshots, and public assets.
• `use-twenty-mcp` — connect to a workspace through MCP and present records as readable Markdown.

Listing first lets you confirm that the publishing branch is available before selecting what to install.

Step 2: Install the complete collection

For the simplest setup, install all five skills:

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

The CLI prompts you to choose target agents. Select **Claude Code**. The documentation says the CLI also supports Codex, Cursor, Pi, and other harnesses, so make sure you do not accidentally choose a different target.

Each installed skill includes the references it needs. Installing the complete collection does not itself authorize workspace access or publish anything to Twenty.

Alternative: install only the introductory skills

If you prefer a smaller installation, the repository gives these individual commands:

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

Choose Claude Code when prompted. You can use `create-app` for initial scaffolding and `develop-app` for ordinary development without installing the MCP-oriented skill.

Confirming the installation

The supplied files do not document a separate `skills` verification command, an installed-files location for Claude Code, or a Claude Code refresh command. Do not use an invented command for those tasks.

Treat a successful completion of the `npx skills add` operation, with Claude Code selected as the target, as the documented installation result. You can then begin a Claude Code session for a Twenty app and ask for work matching one of the installed skill descriptions. Skill activation still depends on the host recognizing the task as relevant.

Optional: create your first Twenty app

The skills enhance Claude Code, but they do not create an app merely by being installed. When you are ready, the repository recommends its official scaffolder.

First ensure Docker is installed and running. Then run:

npx create-twenty-app@latest my-twenty-app

Enter the generated project:

cd my-twenty-app

Start development mode:

yarn twenty dev

According to the project’s first-party documentation, the scaffolder creates a TypeScript project with linting, tests, and a preconfigured Twenty CLI. It also starts a local Twenty server through Docker, pulls the latest image, and authenticates with a development API key.

You may replace `my-twenty-app` with your preferred project name, but keep the same name in the subsequent `cd` command.

MCP: important limitation for Claude Code users

Installing all skills includes `use-twenty-mcp`, but a workspace MCP endpoint still requires each user’s private client configuration. Workspace URLs and credentials remain local to the user.

The supplied repository files provide MCP setup commands only for **Codex**, not Claude Code. Do not run those Codex commands as if they configured Claude Code. The repository points other clients to an additional setup reference, but that file was not supplied here, so this guide cannot provide a source-verified Claude Code MCP command.

You can safely use the other four app-development skills without MCP. Configure workspace MCP only after consulting the repository’s current first-party Claude-compatible setup documentation.

If the `agent-skills` branch is unavailable

The repository warns that the branch is created only after the first successful publishing workflow. If the listing command fails because that branch is unavailable, use the documented local-build route.

Clone the repository and enter it:

git clone https://github.com/twentyhq/twenty.git
cd twenty

Install the monorepo dependencies using its Yarn configuration:

yarn install

Validate and build the skills distribution:

npx nx run twenty-agent-skills:validate
npx nx run twenty-agent-skills:build

Install the documented local example:

npx skills add ./packages/twenty-agent-skills/dist --skill create-app

Select Claude Code when prompted. This fallback is more involved than the published-branch route and creates a large monorepo checkout, so use it only when necessary.

Troubleshooting a generated app

If the local server does not start, first check that Docker is running:

docker info

Then inspect the app’s Docker logs:

yarn twenty docker:logs

If workspace authentication fails, re-authenticate:

yarn twenty remote:add

If generated types are missing or stale, ensure development mode is running:

yarn twenty dev

Twenty CLI credentials are stored per remote in `~/.twenty/config.json`. Treat that file as sensitive and do not commit it to a project.

Safety, updates, and removal

The installation command retrieves executable package tooling and skill content from npm and GitHub. Confirm that the URL is exactly the official `twentyhq/twenty` repository before approving prompts. Skills influence Claude Code’s behavior through instructions, while app-management and publishing work can affect a real Twenty workspace; review proposed changes before applying or publishing them.

No uninstall or update command for these skills appears in the supplied first-party files. Rather than guessing, use the current first-party `skills` CLI or Claude Code documentation when you need removal or upgrades.