---
title: Monday.com (connect your real Monday.com account)
---

# Monday.com (Cloud) Integration

## What it is

> **Status:** in development. Enable it in **Settings → Features -> "Monday.com"**
> (or set `AMC_SHOW_MONDAY_CLOUD=1`); the "Monday.com" sidebar row appears once
> it is on.

### What it is

A first-party Omniscio integration that connects to your **real Monday.com account**
via its Cloud API so you can view boards, manage items, track assigned work in
your inbox, and trigger workflows from item changes; all without leaving Omniscio. It
surfaces as a **"Monday.com"** row in the projects sidebar (gated via the
`monday-cloud` unreleased-feature registry, default off).

This is **NOT** the existing **Mission Control** integration (id `'monday'`), which is a
self-hosted project management system backed by its own database. The two
share no code. This integration (id `'monday-cloud'`) talks to the real
monday.com API.

## Where to find it

Enable it in **Settings → Features → Monday.com**, after which a **Monday.com** row appears in the sidebar and the boards live behind it.

## How it behaves

### How to connect

1. **Enable it:** Settings → Features -> toggle **Monday.com** on. A "Monday.com"
   row appears in the sidebar.
2. **Get your API token:** go to monday.com -> click your avatar ->
   Developers -> My Access Tokens. Copy the token.
3. **Connect (in-panel):** open the **Monday.com** sidebar row and click **Set up
   Monday.com** on the connect screen, then paste your API token in the drawer and
   Save — it tests the connection on save. (Monday.com uses the shared in-app
   connection stack — the same drawer as the Jira, Linear, Notion, and ClickUp
   boards — not a separate settings page.)

Your API token is **encrypted at rest** on your device (`mondayCloudApiToken`
is in `ENCRYPTED_APP_SETTINGS_KEYS`) and is never sent to the renderer.

### Features

- **Board view**: see all your boards, groups rendered as swimlanes, items
  with inline column values
- **Item detail**: full item drawer with column values, updates/comments,
  and subitems
- **Inline editing**: change status, person, date, text columns directly —
  on the item AND on its subitems (each subitem edit is scoped to the subitem's
  own board)
- **File columns**: view a file column's attachments as download links, and
  upload a new file via a native picker (parent items)
- **Search**: find items across a board by column value
- **Item creation**: create new items in any group
- **Move items**: move items between groups
- **Comments**: post updates (comments) on items
- **Inbox**: items assigned to you appear in the unified inbox (enable
  "Monday.com Inbox" in settings); all assigned items surface as rows;
  updates re-fire the push
- **Workflow triggers**: fire automations when items are created, updated,
  or change status on a specific board

### Limitations

- Personal API token only (no OAuth yet)
- Rate limited by Monday.com's complexity budget (approximately 3 req/s
  effective); the client logs the remaining budget but does not proactively
  throttle
- Subitems are editable in the item drawer (status/person/date/text columns),
  EXCEPT a subitem's own file columns, which are shown read-only (file upload
  targets parent items only)
- File/asset columns: view (download links) + upload (native picker) are
  supported on parent items; monday's relational column types (formula, mirror,
  dependency, connect-boards) are still not supported
- Column values are JSON-encoded strings in the API (must `JSON.stringify`
  before sending)

### Troubleshooting

- **"Invalid API token"**: regenerate at monday.com -> Admin -> API
- **"Rate limit reached"**: wait 60 seconds; Monday.com resets per-minute
  complexity
- **Board not showing**: check workspace filter in the sidebar
- **Feature not visible**: ensure `mondayCloudEnabled` is on in Settings ->
  Lab, or set `AMC_SHOW_MONDAY_CLOUD=1`

## For agents

### How it works (internals)

- **Auth:** personal API token sent verbatim in the `Authorization` header
  (NOT "Bearer" prefixed; a monday.com API quirk). Token auth, not OAuth.
- **Credentials:** stored as the flat `AppSettings` field
  `mondayCloudApiToken`. Listed in `ENCRYPTED_APP_SETTINGS_KEYS` (encrypted at rest).
  Loaded via `getSavedMondayCloudCreds` in main-process memory only.
- **Client:** `src/main/services/monday-cloud/monday-cloud-client.ts`. All
  requests go to `https://api.monday.com/v2` (fixed constant, no SSRF
  surface). A `Semaphore(5)` caps concurrent requests. Mutations (detected
  by `/^\s*mutation\b/`) are never retried (`maxAttempts: 1`); queries retry
  up to 3 times on 429/5xx with exponential backoff + jitter.
- **IPC:** `monday-cloud:auth-status` + `monday-cloud:test-connection`
  (connect); reads `monday-cloud:list-boards`, `monday-cloud:get-board`,
  `monday-cloud:get-items`, `monday-cloud:get-item`,
  `monday-cloud:list-workspaces`, `monday-cloud:search`; writes
  `monday-cloud:create-item`, `monday-cloud:update-column`,
  `monday-cloud:move-item`, `monday-cloud:create-update`,
  `monday-cloud:add-file` (desktop-only file upload — native picker in Main,
  bytes never cross IPC, refused over the web WS bridge). None return the
  token; all humanize failures. Every successful write also pushes
  `monday-cloud/items-changed`, which makes an open board view re-fetch its
  rows (debounced 300ms) so an edit shows up without switching boards — on
  mobile/web too.
- **Inbox poller:** `src/main/services/monday-cloud-inbox/monday-cloud-inbox-poller.ts`.
  Uses the shared `createInboxPoller` factory with diff mode `'updated-at'`
  and wholesale `replaceAll` on each tick. Kill switch:
  `AMC_DISABLE_MONDAY_CLOUD_INBOX_POLL=1`.
- **Workflow trigger:** `src/main/services/workflow-engine/monday-cloud-item-trigger.ts`.
  Polls items on watched boards; baselines on first tick (no replay on
  restart; snapshot is memory-only). Kill switch:
  `AMC_DISABLE_MONDAY_CLOUD_WORKFLOW_TRIGGER=1`.
- **UI:** credentials entered in-panel; board view, item drawer, and search
  in the `monday-cloud` feature folder. Sidebar row gated via
  `isUnreleasedFeatureVisibleInRenderer('monday-cloud', settings)` in
  Dashboard's `visibleProjects` filter.

### CLI routes

All routes are gated by `mondayCloudMutationPreamble` (feature visibility +
auth + rate limit). Returns 404 when the feature is not visible.

| Method | Path                          | Purpose                                                 |
| ------ | ----------------------------- | ------------------------------------------------------- |
| GET    | `/monday-cloud/boards`        | List visible boards                                     |
| GET    | `/monday-cloud/board/:id`     | Board detail (columns, groups)                          |
| GET    | `/monday-cloud/item/:id`      | Item detail (column values, subitems, updates)          |
| GET    | `/monday-cloud/search`        | Search items by column value (boardId, columnId, value) |
| POST   | `/monday-cloud/update-column` | Change one column value                                 |
| POST   | `/monday-cloud/move-item`     | Move item to a group                                    |
| POST   | `/monday-cloud/create-item`   | Create a new item                                       |
| POST   | `/monday-cloud/create-update` | Post a comment on an item                               |

### Integration registry

The integration manifest (`src/shared/integrations/monday-cloud.ts`) declares
`parentGroupId: 'productivity'`, matching the Mission Control sibling.

## Related

### Related

- [mission-control.md](mission-control.md): the built-in project management system (different
  feature, different code)
- Contract: `.claude/memory/contracts/monday-cloud-contract.md`: the invariants
  and the tests that lock them