---
slug: "dex-x-5"
source_type: "clawhub"
source_url: "https://clawhub.ai/skills/dex-skill"
repo: ""
source_file: "description"
---
---
name: dex-skill
description: >
  Manage your Dex personal CRM — search, filter, create, archive, and update contacts; log notes;
  manage follow-ups, tags, groups, and custom fields; search connected email; and read or manage
  connected calendars.
  Use this skill to: (1) Find, add, or update contacts, (2) Log meetings and notes,
  (3) Manage reminders and keep-in-touch cadence, (4) Organize tags, groups, and custom fields,
  (5) Merge or archive contacts, (6) Review relationships or prepare meetings,
  (7) Search correspondence, (8) Manage calendar events, (9) Categorize, audit, or clean a network,
  (10) Turn notetaker output or transcripts into notes and follow-ups,
  (11) Prepare multiple meetings or event follow-up, (12) Authenticate via /dex-login,
  or handle another personal CRM task involving the user's professional network.
metadata:
  version: "2.1.0"
  openclaw:
    emoji: "\U0001F91D"
    homepage: https://getdex.com
    skillKey: "dex-skill"
    requires:
      bins: ["dex"]
    install:
      - id: "npm"
        kind: "node"
        package: "@getdex/cli"
        bins: ["dex"]
        label: "Install Dex CLI (npm)"
---

# Dex Personal CRM

Dex is a personal CRM that helps users maintain and nurture their professional relationships. It tracks contacts, interaction history, reminders, and organizational structures (groups, tags, custom fields).

## Setup — Detect Access Method

Check which access method is available, in this order:

1. **MCP tools available?** If `dex_search_contacts` and other `dex_*` tools are in the tool list, use MCP tools directly. This is the preferred method — skip CLI setup entirely.
2. **CLI installed?** Check if `dex` command exists (run `which dex` or `dex auth status`). If authenticated, use CLI commands.
3. **Neither?** Guide the user through setup.

### First-Time Setup

**Path A — Platform supports MCP (Claude Desktop, Cursor, VS Code, Gemini CLI, etc.):**

If the user already has the Dex MCP server configured, or their platform can add MCP servers:

```bash
npx -y add-mcp https://mcp.getdex.com/mcp -y
```

This auto-detects installed AI clients and configures the Dex MCP server for all of them. User authenticates via browser on first MCP connection.

**Path B — Install CLI:**

```bash
npm install -g @getdex/cli
```

Works with npm, pnpm, and yarn. No postinstall scripts — the binary is bundled in a platform-specific package.

**Keeping the CLI up to date:**

The CLI auto-generates commands from the MCP server's tool schemas at build time. When tools are added or updated on the server, users need to update the CLI to get the new commands. If a user reports a missing command or parameter, suggest updating:

```bash
npm install -g @getdex/cli@latest
```

**Path C — No Node.js:**

Direct the user to follow the setup guide at **https://getdex.com/docs/ai/mcp-server** — it has client-specific instructions for Claude Desktop, Claude Code, Cursor, VS Code, and other MCP-capable clients.

### Authentication

Triggered by `/dex-login` or on first use when not authenticated. Prefer MCP browser OAuth when available, then device code for an interactive CLI session, and API keys for CI or when the user explicitly chooses one.

**Option 1 — API Key:**
1. User generates a key at [Dex Settings > Integrations](https://getdex.com/appv3/settings/api) (requires Professional plan)
2. Ask the user to run `dex auth --token dex_your_key_here` in their own terminal
3. Key is saved to `~/.dex/api-key` (chmod 600)

Never ask the user to paste an API key into chat. Do not print, log, commit, or include it in tool arguments that will be shown back to the user.

**Option 2 — Device Code Flow (works on remote/headless machines):**

Drive this flow directly via HTTP — no browser needed on the machine:

1. Request a device code:
   ```bash
   curl -s -X POST https://mcp.getdex.com/device/code -H "Content-Type: application/json"
   ```
   Response: `{ "device_code": "...", "user_code": "ABCD-EFGH", "verification_uri": "https://...", "expires_in": 600, "interval": 5 }`

2. Show the user the `user_code` and `verification_uri`. They open the URL on any device with a browser, log in to Dex, and enter the code.

3. Poll for approval every 5 seconds without logging the successful response:
   ```bash
   curl -s -X POST https://mcp.getdex.com/device/token \
     -H "Content-Type: application/json" \
     -d '{"device_code": "<device_code>"}'
   ```
   - `{"error": "authorization_pending"}` → keep polling
   - A response containing `api_key` → stop polling and save it without rendering the value

4. Create the protected destination, then use local secret-aware parsing to write only the `api_key` value directly to it:
   ```bash
   install -d -m 700 ~/.dex
   umask 077
   ```
   Write the parsed key bytes to `~/.dex/api-key` without printing them and ensure the file mode is `600`. If the execution surface cannot keep the successful response out of chat or tool logs, stop and ask the user to complete CLI authentication in their own terminal.

For CI/automation with no human present, use the API key method with `DEX_API_KEY` environment variable.

## Data Model

```
Contact
├── Emails, Phone Numbers, Social Profiles
├── Company, Job Title, Birthday, Website
├── Description (rich text notes about the person)
├── Tags (flat labels: "Investor", "College Friend")
├── Groups (collections with emoji + description: "🏢 Acme Team")
├── Custom Fields (user-defined: input, dropdown, datepicker)
├── Notes/Timeline (interaction log: meetings, calls, coffees)
├── Reminders (follow-up tasks with optional recurrence)
└── Starred / Archived status
```

## Using Tools

### MCP Mode

Call `dex_*` tools directly. All tools accept and return JSON.

### CLI Mode

Use the `dex` command. CLIHub generates subcommands from MCP tool names (replacing `_` with `-`):

```bash
dex dex-search-contacts --query "John"
dex dex-list-contacts --limit 100
dex dex-create-contact --first-name "Jane" --last-name "Doe"
dex dex-list-tags
dex dex-create-reminder --text "Follow up" --due-at-date "2026-03-15"
```

Use `--output json` for machine-readable output, `--output text` (default) for human-readable.

Run `dex --help` for all commands, or `dex <command> --help` for command-specific help.

See **[CLI Command Reference](references/cli-commands.md)** for the full mapping table of all 47 tools to CLI commands.

## Core Workflows

### 1. Find a Contact

```
choose search/filter/list → get details (with notes if needed)
```

- Use `dex_search_contacts` for keywords or real geographic proximity with `near` and optional `radius_km`
- When using `near`, keep `query` for an additional non-location filter; do not repeat the place in both fields
- Use `dex_filter_contacts` for structured AND filters such as tags, groups, company, profile presence, dates, archived state, and custom fields
- Use `dex_list_contacts` for unfiltered bulk iteration (up to 500 per page, cursor-paginated)
- Use an empty search query to browse a single batch of contacts sorted by most recent interaction
- Include `include_notes: true` when user needs interaction history

### 2. Add a New Contact

```
create contact → (optionally) add to groups → apply tags → set reminder
```

- Create with whatever info is available (no fields are strictly required)
- Immediately organize: add relevant tags and groups
- Set a follow-up reminder if the user just met this person

**Bulk import (CSV, spreadsheet, list):**
```
batch create contacts → add to group → create note for all
```

- Use `dex_create_contact` with the `contacts` array (up to 100 per call) for batch creation
- Use the returned contact IDs to add them all to a group with `dex_add_contacts_to_group`
- Use `dex_create_note` with `contact_ids` to log a shared note across all imported contacts

### 3. Log an Interaction

```
(optional) list note types → create note on contact timeline
```

- Discover note types first with `dex_list_note_types` to pick the right one (Meeting, Call, Coffee, Note, etc.)
- Set `event_time` to when the interaction happened, not when logging it
- Keep notes concise but capture key details, action items, and personal context
- Use `contact_ids` (plural) to link a single note to multiple contacts (e.g. a group meeting)

### 4. Manage Follow-Ups

```
set cadence or create reminder → complete/snooze when due
```

- Use `dex_update_contact.keep_in_touch` for relationship cadence; use a reminder for a specific task
- Always require `due_at_date` (ISO format: "2026-03-15")
- Use `text` for the reminder description — there is no separate title field
- Recurrence options: `weekly`, `biweekly`, `monthly`, `quarterly`, `biannually`, `yearly`
- Use `dex_complete_keep_in_touch` without `snooze_days` after a real interaction; use `snooze_days` to defer without recording a touch

### 5. Organize Contacts

**Tags** — flat labels for cross-cutting categories:
```
create tag → add to contacts (bulk)
```

**Groups** — named collections with emoji and description:
```
create group → add contacts (bulk)
```

Best practice: Use tags for attributes ("Investor", "Engineer", "Met at Conference X") and groups for relationship clusters ("Startup Advisors", "Book Club", "Acme Corp Team").

### 6. Manage Custom Fields

```
list fields → create field definition → batch set values on contacts
```

- Three field types: `input` (free text), `autocomplete` (dropdown with options), `datepicker`
- Use `dex_set_custom_field_values` to set values on multiple contacts at once
- For autocomplete fields, provide `categories` array with the allowed options

### 7. Meeting Prep

When a user says "I have a meeting with X":

1. Search for the contact
2. Get full details with `include_notes: true`
3. Check recent reminders for pending items
4. Optionally search relevant email correspondence and fetch the calendar event when the user asks for live context
5. Summarize: last interaction, key notes, pending follow-ups, shared context, attendees, and recent correspondence
6. See [CRM Workflows](references/crm-workflows.md) for detailed meeting prep guidance

### 8. Manage Calendar Events

- Use `dex_list_calendar_events` for a time window or plain-text event search across all connected Google/Microsoft accounts
- Reuse an event's returned `email` as `account_email` for get/update/delete
- For create/update/delete, also pass `account_provider` when the same address is connected to both providers; `dex_get_calendar_event` currently accepts only `account_email`
- For timed events, provide both `start_datetime` and `end_datetime` with explicit offsets; include an IANA `timezone`
- For all-day events, provide `start_date`; `end_date` is exclusive and defaults to the next day
- Confirm before creation when attendees may receive invitations
- On update, `attendees` replaces the whole list; fetch the event first and include everyone who should remain
- A recurring series ID updates the whole series; state that scope before confirmation
- Identical create/update retries are idempotent after a timeout

An update cannot move an event between connected accounts. To transfer one, fetch the original, confirm creating a replacement on the target account, then separately confirm deleting the original. Preserve the full attendee list and details, and warn that organizer identity, RSVP state, conferencing data, and provider notifications may change.

If a calendar write fails for missing provider scope, direct the user to **Settings → Sync & Integrations → Grant calendar access** for that account.

### 9. Search Correspondence

- Use `dex_search_emails` for live, read-only search across all connected Google/Microsoft mailboxes
- Use plain keywords such as a name, company, domain, or topic; provider operators such as `from:` and `to:` are neutralized
- Set `after` and `before` for precise date ranges; otherwise the search covers roughly the last six months
- Results contain metadata, snippets, and provider links, not full bodies
- Dex cannot send email; do not imply that this tool drafts or sends messages

### 10. Archive, Delete, or Merge

Prefer reversible cleanup:

1. Use `dex_archive_contacts` for contacts the user may want later
2. Find archived contacts with `dex_filter_contacts` and `archived_only: true`
3. Restore them with `dex_archive_contacts` and `archived: false`

For duplicates:

```
search for potential duplicates → confirm with user → merge
```

- Dex chooses the oldest record in each group as the survivor, regardless of input order
- Read `mergedContactIds` from the response to learn which ID survived
- Always confirm with the user before merging (destructive operation)
- Can merge multiple groups in a single call

### 11. Handle Outcome-Oriented Requests

For multi-contact or multi-step requests, follow this reusable contract:

```
define scope → inspect current state → preview proposed outcome → confirm writes → execute → verify
```

- Treat requests to analyze, recommend, audit, or prepare as read-only unless the user also asks for changes
- When the user says “all,” paginate the complete relevant dataset and state whether the scope includes active contacts, archived contacts, or both
- Reuse existing tags, groups, custom fields, contacts, and recent notes before creating anything
- Separate high-confidence actions from ambiguous records that need review
- Present exact additions, updates, removals, archives, merges, notes, and reminders before bulk writes
- Verify changed records with fresh reads and report successes, skips, and failures

Load [CRM Workflows](references/crm-workflows.md) for detailed playbooks when the user asks to:

- Categorize or reorganize their whole network
- Turn a notetaker summary or transcript into notes, contact updates, and reminders
- Audit or clean up CRM data
- Import and follow up with people from an event or roster
- Review relationship health or plan outreach
- Prepare a day or week of meetings
- Build a target contact list from several criteria

## Important Patterns

### Privacy and Data Minimization

- Retrieve only the fields and history needed for the request; leave `include_notes` and `include_contacts` off unless relationship context is necessary
- Treat contact methods, notes, email snippets, attendee lists, and provider links as private relationship data
- Summarize relevant context instead of repeating unnecessary personal details
- Never share or transmit Dex data to another service without an explicit user request
- Do not claim access to full email bodies when `dex_search_emails` returns only metadata and snippets

### Pagination

Only responses with `has_more` and `next_cursor` use cursor pagination:
- `dex_list_contacts`: default 100 per page, max 500
- `dex_filter_contacts`: default 50 per page, max 200
- Tag, group-contact, note, and reminder lists: default 10 per page
- Check `has_more` in response
- Pass `next_cursor` from previous response to get next page
- Iterate until `has_more: false` to get all results

`dex_search_contacts`, `dex_list_calendar_events`, and `dex_search_emails` return a bounded single batch, not a cursor. Narrow the query or date range when necessary.

### Destructive Operations

Respect MCP host confirmations. In CLI mode, explicitly summarize the target and consequence before any operation that deletes, overwrites, removes relationships, archives, completes cadence state, changes external calendar state, or may send invitations.

High-risk examples:

- Contact deletion, merge, and bulk archive
- Any update that overwrites saved fields or replaces a collection
- Removing tags or group memberships
- Completing/snoozing keep-in-touch state
- Deleting groups, tags, notes, reminders, or custom fields
- Setting custom field values in bulk
- Creating, updating, or deleting calendar events

Before a destructive call, resolve names to current IDs, read the current record when overwriting a collection, show the intended delta, and never guess ambiguous targets.

For contact cleanup, do not define “stale” from inactivity alone. Review open reminders and active relationship signals, present exact archive/retain lists, and require approval before archiving or changing cadence. Date filters exclude contacts with no recorded interaction, so review those separately when they matter.

### Response Truncation

Responses are capped at 25,000 characters. Cursor-based tools preserve `next_cursor` and `has_more`; continue with a smaller page. For single-batch search, calendar, and email tools, reduce `limit` or narrow the query/date range.

### Date Formats

- All dates: ISO 8601 strings (e.g., `"2026-03-15"`, `"2026-03-15T14:30:00Z"`)
- Birthdays: `YYYY-MM-DD`
- Reminder due dates: `YYYY-MM-DD`
- Calendar timed events: ISO 8601 with an explicit UTC offset plus an IANA timezone
- Calendar all-day `end_date`: exclusive

## Detailed References

- **[Tool Reference](references/tools-reference.md)** — Complete parameter documentation for every tool, with examples
- **[CLI Command Reference](references/cli-commands.md)** — Full MCP tool → CLI command mapping table (only needed for CLI mode)
- **[CRM Workflows](references/crm-workflows.md)** — Relationship management best practices, follow-up cadences, and strategies for being an effective CRM assistant