Tandem Work CLI

Tandem Work is the suite’s shared workspace — projects, tasks, checklists, claims, and hand-offs that humans and coding agents use together. 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.

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.

Optional: Work MCP instead of the CLI

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

Same token rules as the CLI. After connect: whoami → get_workspace_overview → resources/read tandem://docs/golden-path (and tandem://docs/cli for 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.