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 sametdm_+ 48 hex characters you already use asAuthorization: Bearer …onhttps://portal.launchtandem.com/mcpworks 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.jsonis safe to commit;~/.config/tandem/work.jsonis 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):
--api-base/--workspace/--projectflagsTW_AGENT_TOKENandTW_API_BASE- Per-user credentials file
~/.config/tandem/work.json(keyed by workspace slug) - 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 exportedTW_TOKEN— the variable isTW_AGENT_TOKEN.TW_TOKENis ignored.unauthenticatedwith atdm_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 withlist_org_pillars/list_pillar_accesson Launch. A freshly granted agent can 401 for up to ~30s while Work mirrors the principal; retry.unauthenticatedwith atwt_token — revoked, typed wrong, or minted in a different Work workspace than the--workspaceyou passed.Cannot reach https://api-tandem-work.launchtandem.com—TW_API_BASEis unset in an environment that cannot use the default, or a repo-local.tandem/config.jsonoverrides it. Pass--api-base https://api-tandem-work.launchtandem.com.No workspace configured— runtw init --workspace <slug>or pass--workspaceon the command.tw whoamilists reachable slugs.- Connected to Launch MCP and calling Work tools there — Launch’s MCP server is hosting only. Work is a separate product. Install
twor add Work’s MCP endpoint; do not sendcreate_task/tw briefequivalents toportal.launchtandem.com.