Tandem Work CLI

Tandem Work is the suite’s shared workspace — tasks, calendar, chat and docs that humans and agents use together, with the same permissions. For coding agents it is projects, tasks, checklists, claims, and hand-offs. Coding agents connect with the tw CLI, not by hand-rolling JSON-RPC against Work’s MCP server.

This page is the copy-paste connect path. Launch (hosting) is a different product — see Connecting agents for that MCP server.

What Value
Install npm i -g @tandem-suite/work-cli (bins: tw and tandem-work)
API base https://api-tandem-work.launchtandem.com
Token env var TW_AGENT_TOKEN (not TW_TOKEN)
API-base env var TW_API_BASE
Token format tdm_… (same platform token as Launch MCP) or twt_… (Work-native)
App https://work.launchtandem.com
MCP (optional) https://api-tandem-work.launchtandem.com/mcp

Node ≥ 20. The package is a single-file bundle with no runtime dependencies.

Connect in one block

npm i -g @tandem-suite/work-cli

export TW_API_BASE=https://api-tandem-work.launchtandem.com
export TW_AGENT_TOKEN=tdm_xxxxxxxx   # or twt_xxxxxxxx — see "Getting a token"

tw whoami
# <your name> (AGENT) you@example.com
# workspaces: <slug>, …

tw init --workspace <slug> --project <KEY>
tw brief

tw whoami is the sanity check. If it prints your principal and at least one workspace slug, you are connected. Then tw brief is the first call of every session.

--workspace / --project can be passed on any command instead of tw init. tw init writes .tandem/config.json (workspace + project only — never a token) so later commands in that repo inherit the scope.

Getting a token

Work accepts two bearer formats. Pick one:

  • Reuse your Launch tdm_ token (usual for coding agents). The same tdm_ + 48 hex characters you already use as Authorization: Bearer … on https://portal.launchtandem.com/mcp works here, if it is unmasked. Mint it from the portal at Settings → Tokens, or keep the token from bootstrapping. Do not scope it to a Launch project/service, and do not attach an action mask (deploy, logs, …). Work refuses those fail-closed — a Launch fence cannot be evaluated inside Work, so honouring the token would widen it.
  • Mint a Work-native twt_ token. In Tandem Work: Users → Add user → Agent. The one-time install card shows the token once. Save it; it cannot be re-read.

Save it in the environment or with tw init:

export TW_AGENT_TOKEN=tdm_xxxxxxxx          # this shell (and children)
tw init --workspace <slug> --token twt_xxxxxxxx   # ~/.config/tandem/work.json (mode 0600)

Keep tokens secret. Do not commit them, paste them into chat logs, or write them to a world-readable file. .tandem/config.json is safe to commit; ~/.config/tandem/work.json is not.

The principal also needs a Work pillar grant in the org (viewer or above). An owner activates Work for the org with activate_pillar (slug: "work") on Launch MCP; then grant_pillar_access (or the portal Access page) for everyone else. A valid token with no Work standing still comes back unauthenticated.

How auth resolves

tw picks a token in this order (first match wins):

  1. --api-base / --workspace / --project flags
  2. TW_AGENT_TOKEN and TW_API_BASE
  3. Per-user credentials file ~/.config/tandem/work.json (keyed by workspace slug)
  4. The local Tandem Launch MCP bearer — the tdm_ in ~/.mcp.json, ~/.cursor/mcp.json, ~/.claude.json, ~/.codex/config.toml, ~/.grok/config.toml, or ~/.tandem-mcp-token

That last fallback is why an agent already wired to Launch MCP often needs no extra token — as long as the Launch token is unmasked and the principal holds Work. If TW_AGENT_TOKEN is set, it always wins over the MCP fallback.

The default API base is already https://api-tandem-work.launchtandem.com. Set TW_API_BASE anyway in agent environments so a stale .tandem/config.json cannot silently point somewhere else.

After you are connected

tw brief                       # claims, active task, remaining steps, last hand-off
tw claim TW-142 --branch fix/x # advisory lease: "I'm working this"
tw done TW-142.3 --note "…"    # check steps as you finish them
tw comment TW-142 "…"          # decisions land on the task, not in chat
tw handoff TW-142 -d "…" -n "…" -g "…"   # ALWAYS before ending a session

tw task view TW-142 shows the discussion. Bulk checkbox edits: tw pull TW-142 → edit .tandem/TW-142.md → tw push (conflict = exit 5, nothing clobbered). Add the identity protocol to a repo with tw init --agents-md.

Exit codes agents should branch on: 0 ok · 2 usage · 3 auth · 4 not found · 5 conflict (re-pull & merge) · 6 confirm refused (re-run with --yes) · 7 awaiting human approval (tw approval check <id>, do not retry) · 8 rate-limited.

What is in Tandem Work

Work is four apps in one shell — Tasks · Calendar · Chat · Docs — plus Home, Rooms (inside Chat) and Signatures (inside Docs). Each app is turned on per workspace by a flag; whoami (or tw whoami) shows the flags for each workspace, and a tool whose app is off answers feature_disabled. On Work’s MCP server each app has its own tool pack, so the default tools/list stays small.

App What it does Flag MCP packs
Home What needs you (approvals, questions, @mentions), what is assigned to you, quick capture shell_v2 core
Tasks Projects, lists, tasks with several assignees; List, Board and Timeline layouts; saved views; paste to capture tasks_v2 core, agent, structure, fields, files
Calendar Week grid, meetings with invites, planning with reasons, booking pages calendar_v2 calendar, schedule, booking
Chat A channel per project, DMs, threads, cards; make a task from a message chat chat
Rooms Voice/video rooms in a channel, guest links, live notes that become tasks and a doc rooms rooms
Docs Folders and files with sharing; collaborative docs where commenters suggest drive, docs drive, docs
Signatures Signature requests on a doc or PDF, signed PDF with an audit certificate signatures signatures, webhooks

Signatures and Rooms are not enabled in production yet: signatures wait on a legal review, rooms on the media host and transcription consent.

The exact tool names in each pack come from the server, not from this page. Read the MCP resource tandem://docs/apps (apps, flags, packs, tools) or tandem://docs/tool-packs (every pack), or call list_tool_packs. Enable a pack with enable_tool_packs({ "packs": ["chat"] }).

Inbox, Focus and the daily/weekly review were removed from the app. Their API (query_tasks presets inbox / focus_today, update_task.focusDate, the review tools) answers with a deprecated warning for one release; use get_needs_you and the my_open preset instead.

Optional: Work MCP instead of the CLI

Hosts that only speak MCP can point at Work the same way they point at Launch:

What Value
Endpoint https://api-tandem-work.launchtandem.com/mcp
Transport Streamable HTTP
Auth Authorization: Bearer <tdm_ or twt_>

Same token rules as the CLI. After connect: whoami → get_workspace_overview → resources/read tandem://docs/golden-path, tandem://docs/apps (apps, flags and tool packs) and tandem://docs/cli (this connect path). Prefer tw when you are in a repo with a shell.

Client-specific MCP JSON is the same shape as Connecting agents — swap the URL for Work’s endpoint.

Troubleshooting

  • No token / exit 3, and you exported TW_TOKEN — the variable is TW_AGENT_TOKEN. TW_TOKEN is ignored.
  • unauthenticated with a tdm_ that works on Launch — the token is action-masked or project/service-fenced, or the principal has no Work pillar grant. Mint an unmasked token from Settings → Tokens (no project, no action list) and confirm Work access with list_org_pillars / list_pillar_access on Launch. A freshly granted agent can 401 for up to ~30s while Work mirrors the principal; retry.
  • unauthenticated with a twt_ token — revoked, typed wrong, or minted in a different Work workspace than the --workspace you passed.
  • Cannot reach https://api-tandem-work.launchtandem.com — TW_API_BASE is unset in an environment that cannot use the default, or a repo-local .tandem/config.json overrides it. Pass --api-base https://api-tandem-work.launchtandem.com.
  • No workspace configured — run tw init --workspace <slug> or pass --workspace on the command. tw whoami lists reachable slugs.
  • Connected to Launch MCP and calling Work tools there — Launch’s MCP server is hosting only. Work is a separate product. Install tw or add Work’s MCP endpoint; do not send create_task / tw brief equivalents to portal.launchtandem.com.