linear-multi-workspace-setup

Linear Multi-Workspace Setup

Stop switching Linear logins when your agents move between workspaces.

This open Agent Skill helps Codex and Claude Code connect to several Linear workspaces without silently sharing or replacing authentication.

It guides Codex or Claude Code through a safe setup:

1. Map each work area to Linear, Jira, or another tracker.
2. Create one named MCP connection per Linear workspace.
3. Pause for user-controlled OAuth.
4. Verify each connection through its exact namespace.
5. Recheck earlier connections after every new login.
6. Require approval before Linear writes.
7. Scope each Codex repo to only its intended Linear connection.
8. Install clear workspace-routing guidance.

For local multi-workspace OAuth, the setup guide can label each browser URL with workspace=<alias> through mcp-remote. The label helps you match the sign-in to its terminal; you still select the workspace in Linear.

Optional CLI

The router/ folder holds a small Node CLI (linear-workspace-router) that does the setup, check and repo-scope steps for you: it runs each connection through a wrapper that shows a labeled sign-in page, replaces Claude Code entries without removing them first, reuses an existing server name for the same credential folder, and saves each confirmed workspace ID so later checks compare IDs. Saved IDs and custom server names stay in local files that Git ignores. npx skills add copies this whole repo into the installed skill, so the CLI is then at <installed skill folder>/router/bin/linear-workspace-router.mjs; node <that path> install-skill writes the CLI skill with that real path filled in. You can also clone the repo and run it from there. Clean installs name Roster's server linear-onroster by default (login folder linear-roster); other aliases use linear-<alias>.

Install

View the skill on skills.sh

npx skills add switmer/linear-multi-workspace-setup \
  --skill linear-multi-workspace-setup

If you know which workspaces you want, ask:

Set up my Roster, HopperX, and personal Linear workspaces. Dock411 uses Jira.

If you are unsure, ask:

Help me set up the Linear workspaces I want to use in Codex. I do not know the full list, so help me discover them one at a time.

The agent will show a proposed map before changing anything. It will then guide you through each OAuth screen and report which connections are verified, failed, or still unverified.

How workspace discovery works

The skill does not claim it can list every Linear workspace your account can access before OAuth. It discovers which workspaces you want the agent to use.

• If you know the list, name each work area, tracker, and Linear workspace.
• If you are unsure, the skill asks you to check Linear's workspace switcher and choose only the workspaces you want connected.
• If you still do not have a full list, the skill plans, authenticates, and verifies one workspace at a time. After each one, it asks whether you want to add another.

Existing MCP connections and team names never decide the workspace count. You confirm each planned connection and the final routing map.

Why verification matters

Different MCP server names do not prove separate authentication. After each login, the skill rechecks every previous connection.

When Linear exposes get_workspace, the skill records its immutable workspace ID. If only team names are available, it requires user confirmation and marks workspace identity and credential isolation as unverified.

Repo-level guards

Global named connections make each workspace available to Codex, but most repos need only one. For a confirmed repo-to-workspace route, the skill can add a small .codex/config.toml override that enables the intended Linear server and disables the others.

Before writing overrides, it requires complete server definitions for every referenced connection, including disabled ones. Replacement must keep config valid throughout and restore the prior config after failure. It checks all installed linear@… plugin IDs, including the remote variant, rather than trusting config flags alone.

It then checks the loaded MCP and plugin state from that repo and verifies the workspace identity in a fresh process. The check fails if the project is untrusted, another Linear connection remains exposed, or the workspace does not match. Existing panes must be restarted after the config changes.

Safety

• OAuth consent stays with the user.
• The skill never inspects, copies, prints, or modifies credential storage.
• Setup uses read-only checks and stops before writes on an identity mismatch.
• Work areas using Jira or another tracker do not receive Linear connections.
• A bundled Linear connector is changed only with user approval and must be checked from a fresh process.

Support

macOS tested. Codex and Claude Code supported. Other MCP clients may work but are unverified.

Local named MCP connections do not change the hosted ChatGPT Linear plugin.

Report a bug or confusing behavior.

Documentation

• Canonical Agent Skill
• Codex setup
• Claude Code setup
• Generic MCP guidance
• Troubleshooting
• Initial eval suite
• Manual OAuth acceptance

License

MIT