---
title: Asana board
---

# Asana board

> **Status:** in development. Gated via the `asana-board` unreleased-feature
> registry (`asanaBoardEnabled` toggle in Settings → Lab, or
> `AMC_SHOW_ASANA_BOARD=1`). The sidebar row appears once enabled.

## What it is

A first-party AMC integration that brings your Asana tasks into the app so you
can manage work without opening Asana's website. It surfaces as an **"Asana"
row in the projects sidebar** (plugin tier) that will open a board view.

It is gated through the unreleased-feature registry (`asana-board`) — invisible
until a developer flips its status to `shipped` in `unreleased-features.ts`.

## Where to find it

### How to use it

1. **Enable it:** Settings → Lab → toggle **Asana board** on. An "Asana" row
   appears in the sidebar.
2. **Connect:** open the **Asana** sidebar row and enter your credentials:
   - **Personal Access Token** — create one at
     **app.asana.com → My Settings → Apps → Developer apps → Personal access tokens**
   - **Workspace GID** — the numeric workspace identifier from your Asana URL
3. Credentials are saved encrypted at rest (listed in `ENCRYPTED_APP_SETTINGS_KEYS`).

**Inbox integration:** turn on **"Asana tasks assigned to me in Inbox"** in
Settings → Lab. AMC then checks Asana in the background (every few minutes,
only while on) and surfaces your assigned, incomplete tasks as rows in the
unified **Inbox**. When a task updates, its row pops back to the top. Click a
row to view it; snooze or dismiss like any inbox item. Requires the Asana board
enabled and connected. Kill switch: `AMC_DISABLE_ASANA_INBOX_POLL=1`.

**Workflow trigger:** Asana tasks can trigger workflow automations. Events:
`created`, `completed`, `updated`. Poll interval: 2 minutes. Kill switch:
`AMC_DISABLE_ASANA_WORKFLOW_TRIGGER=1`.

**CLI routes:**
- `POST /asana/move-to-section` — move a task to a different section
- `POST /asana/reorder` — reorder a task within its section

## How it behaves

Once the feature is enabled and your token and workspace id are saved, an Asana row appears in
the sidebar and opens a board view of your tasks. The board panel itself is not implemented
yet, so today the live surfaces are the inbox rows and the workflow trigger: Asana is checked
in the background every few minutes, only while the inbox toggle is on, and a task that
updates pops back to the top of your inbox. The limit worth knowing before you rely on this is
that it is an unreleased feature behind the Lab gate — nothing is visible, and nothing polls,
until it is turned on.

## For agents

### How it works (internals)

- **Auth:** Personal Access Token (PAT) — sent as `Bearer <token>` against the
  Asana REST API v1 (`https://app.asana.com/api/1.0/`).
- **Credentials:** stored as flat `AppSettings` fields — `asanaAccessToken`,
  `asanaWorkspaceGid`. The token is listed in `ENCRYPTED_APP_SETTINGS_KEYS`
  (encrypted at rest) and `CLI_SETTINGS_SENSITIVE_KEYS` (stripped from reads).
- **Client:** `src/main/services/asana/asana-client.ts` — requests go through a
  concurrency-limited queue (5 concurrent, 429 backoff with exponential retry).
  Errors are humanized via `humanizeIntegrationHttpError`; raw HTTP detail goes
  to logs only.
- **Request queue:** `src/main/services/asana/asana-request-queue.ts` — shared
  concurrency gate + retry logic (max 3 retries on 429, exponential backoff
  with jitter via `computeBackoffMs`).
- **IPC:** `asana:list-sections`, `asana:list-tasks`, `asana:task-detail`,
  `asana:move-to-section`, `asana:reorder`, `asana:settings`. None return the
  token; all humanize failures.
- **Inbox poller:** `src/main/services/asana-inbox/asana-inbox-poller.ts` — uses
  `createInboxPoller` with `diffMode: 'updated-at'`. Snapshots cached in
  `asana_inbox_snapshots` table via named-TX wholesale replace.
- **Workflow trigger:** `src/main/services/workflow-engine/asana-task-trigger.ts`
  — poll+delta pattern matching `jira-issue-trigger.ts`. Memory-only snapshots,
  first-tick baseline (never-replay rule).
- **UI:** behind unreleased gate; board panel not yet implemented. Inbox items
  render through the standard `createInboxItemsProjector` pipeline.

## Related

- [jira-board.md](jira-board.md) — the closest analog; same architecture pattern.
- Contract: `.claude/memory/contracts/asana-integration-contract.md` — the
  invariants and the tests that lock them.