Twenty CRM

Browse and edit the records in a Twenty workspace: people, companies, opportunities, notes, tasks and any custom objects. The assistant can read and change the same records.

Layout

twenty/
  index.ts          Entry point: manifest + view + action handlers
  manifest.ts       Id, permissions and the actions offered to the assistant
  actions.ts        Action handlers, written against lib/client.ts
  lib/types.ts      Settings, object/field metadata, records, list parameters
  lib/client.ts     The REST client (auth, envelopes, errors, metadata, search) and display helpers
  lib/events.ts     Declared events; the client emits them after each create and update
  lib/settings.ts   Connection settings, shared by the view and the actions
  lib/mcp.ts        The connection to Twenty's own MCP server (`mcpServerFor`), and which of its tools ask first
  lib/hooks.ts      Live data hooks for the view
  lib/route.ts      The view's route (Back/Forward, links): parse and format
  lib/viewState.ts  Saved view per object (columns, sorts, filters, layout) → Twenty filter/order_by strings
  lib/related.ts    Hooks for a record's timeline, tasks, notes, files and links
  view/             The view, laid out like Twenty itself (see below)

The view

It copies Twenty's placement of things, not its styling:

• ObjectRail: Twenty's navigation drawer: workspace menu, Settings, then the "Workspace" objects (People, Companies, Opportunities, Tasks, Notes, then the rest) and custom ones.
• IndexPage: header with the object name, "New record" and "⋯"; ViewBar under it (view picker, Filter, Sort, Options, and a chips row for what's applied); then RecordTable or Kanban. Selecting rows brings up the floating action bar (Delete, Export).
• RecordTable: checkbox column, sticky name column with avatar and an "Open" button on hover, field icons in headers, a "+" header for hidden fields, inline cell editing (CellEditor), "+ Add New" row and a "Count all" footer. More rows load on scroll.
• Kanban: one column per option of a select field (Stage for opportunities), drag cards between columns.
• RecordPanel: the side panel next to the table, or the full show page when "Open" is pressed. Summary card, fields as label/value rows, relation sections, and the Timeline / Tasks / Notes / Files tabs (view/record/). Notes and tasks show their body and what they're linked to.
• chips.tsx and icons.tsx: Twenty's value chips, select tags, avatars, and object/field icons (Tabler names mapped to Lucide).

Routes

The listed object, the open record and how it's shown are the view's route (lib/route.ts), so Back and Forward step through them and a reload reopens the same place:

The connection dialog, menus, the view's filters/sorts (saved per object instead) and which pane a phone shows are not in the route. A route naming an object the workspace doesn't have falls back to the nearest page with replace; deleting the open record does the same. Notification targets (<object>/<id>) open the record over the current list as a new step.

How data flows

Twenty is remote and is the source of truth. Nothing is cached on disk except the connection settings (server URL and API key, under host storage key settings), so the view and the assistant always see what's in Twenty.

• Every call goes through createClient(settings) in lib/client.ts, a wrapper over host.net.fetch that sends the key as a Bearer token and turns failures into a TwentyError that says how to fix them (bad key, unreachable server, Twenty's own validation messages).
• Requests go out through the SpaceMIX server, so CORS doesn't apply. The permission is net:* because the user names the server; the app asks once per new host.
• Which objects and fields exist comes from /rest/metadata/objects, fetched once per client and kept in memory. Only active, non-system objects and active fields are used. The actions keep one client per server + key; the view builds its own.
• Records are read and written through /rest/{namePlural}. Writes made through any client fire changes, so the view refetches after the assistant edits something.
• summarize turns a record into the compact form the assistant sees: composites flattened to text where nothing is lost, related records as { id, label }, long text cut off.

Twenty's metadata format differs between versions (paginated data: [...] now, data: { objects } before; relation targets under relation, fromRelationMetadata/toRelationMetadata, or only settings.joinColumnName). The client reads all of them; see relationOf.

Links in the view (web links, attachments) open through host.shell.openUrl; email addresses and phone numbers are copied, since the frame can't open them.

Events

Twenty has no collections, so these are all its events. lib/client.ts emits them after every successful create and update made through SpaceMIX (view and assistant alike); changes made in Twenty itself, or through its own MCP tools, aren't seen. Twenty's system records (the links between tasks or notes and records) are left out. Both target <object>/<id>, which opens the record.

Assistant tools

twenty_objects, twenty_fields, twenty_list, twenty_get, and, with the user's approval, twenty_create, twenty_update, twenty_delete. They need the extension to be connected; until then they return an error asking the user to paste an API key.

The assistant also gets every tool of Twenty's MCP server ({serverUrl}/mcp, same API key), prefixed twenty_. They're listed when a chat turn starts (cached for five minutes) and only while the extension is connected. Read-only tools run directly; anything else asks for approval (see "MCP servers" in EXTENSIONS.md). A server tool whose name matches one of the actions above (objects, fields, list, get, create, update, delete) is left out, since the action is tuned for this extension, and the chat shows a notice. If the server can't be reached or rejects the key, the chat shows that too and the actions above keep working.