LanesLanes
Docs/Desktop/Integrations/Linear Integration

Linear Integration

Connect Lanes to Linear to import tickets, comment results back, and reach Linear from your agent via the Lanes MCP.

Lanes connects to Linear so you can pull tickets into the local board, work on them with an agent, and post the result back to Linear when you're done. The same connection lights up the Linear tool surface on the Lanes Desktop MCP server, so Claude Code or Codex can find a ticket, run a session on it, and comment back — all from chat.

Connecting Linear

Open Lanes, go to Settings, then Linear, and click Connect. Lanes opens your browser to the Linear OAuth screen; once you approve, the browser redirects back to a local loopback URL and the settings page flips to Connected as <your name>.

Behind the scenes:

  • The OAuth flow is brokered by the Lanes API (it holds the client_secret).
  • Scope requested: read. The grant also lets Lanes create issues and post comments through the same OAuth app, so the agent can push results back.
  • The loopback redirect uses a fixed port (127.0.0.1:53682). Linear requires an exact redirect_uri match, so the OAuth app is registered with that exact value and Lanes binds the same port. If something else on your machine is already using port 53682, the connect flow will fail — close the other tool and try again.
  • The access token, refresh token, and expiry are stored locally in integrations.json and never leave your machine.

To disconnect, click Disconnect. Lanes wipes the tokens from integrations.json; you can reconnect at any time.

Token Refresh

Linear access tokens are short-lived (about ten days). Refresh tokens are long-lived. Lanes refreshes proactively before every Linear call:

  • If the access token expires more than 60 seconds from now, use it as-is.
  • Otherwise call the Lanes API refresh endpoint with the refresh token, save the new pair to integrations.json, and use the new access token.

The refresh path is serialised — concurrent Linear calls won't fire duplicate refresh requests that would invalidate each other. You don't need to do anything; the only time you'd notice the refresh logic is if the refresh token itself gets revoked.

Reconnecting After a Revoked Token

If the refresh token gets revoked (Linear rotates them when you revoke an OAuth app, sign out of all sessions, or change your password), the next Linear call fails with a linear not connected error. Since v0.41, Lanes catches that case and surfaces a one-click Reconnect banner in the integration's settings page and on any UI that depends on the connection (the import dialog, the issue's external link badge). Click it to re-run the OAuth flow without losing your local data.

Earlier builds failed silently on this path; if you saw mysterious "could not fetch" errors on imported issues after a long break, this is the fix.

Default Team

The Linear settings page lets you pin a Default team. When set, the import dialog surfaces that team at the top of the team picker so you don't have to scroll past every team in your workspace. This is purely a UI convenience — the agent-facing MCP tools don't honour the default and always make the agent pick a team explicitly.

Importing an Issue

From any project view in Lanes, click Import from Linear in the header. The import dialog shows:

  1. A team picker. If you set a default team, it's first. Otherwise teams are listed in Linear's default order.
  2. The first 50 open issues in the selected team, sorted by most-recently updated. Completed and canceled issues are filtered out.
  3. A search box that hits the Linear GraphQL API. Type free text to match title or description, or an issue key (ENG-9, #9, or 9) to jump straight to a specific ticket.

Issues you've already pulled in are greyed out in the list with their local Lanes issue number shown alongside, so you can see at a glance what is and isn't on your board yet.

Click an issue to import it. Lanes creates a draft on your board with the title and description copied over, plus a marker line linking back to the Linear URL. The new Lanes issue carries the external* metadata that powers the external link badge in the issue detail panel.

Refreshing an Imported Issue

Each imported issue shows an external link badge in its detail panel. The badge has an open button (jumps to the Linear ticket) and a refresh button. Refresh re-fetches the issue from Linear and overwrites the local title and description with the upstream version.

If you made local edits since the last refresh, Lanes warns before overwriting them. You can keep the local copy or accept the upstream version.

From the Agent (via MCP)

Once Linear is connected in settings, every lanes_linear_* tool on the Lanes Desktop MCP server starts working. The agent can:

  • List teams you can access.
  • List or search issues in a team. The search tool understands ENG-9 / #9 / 9 shorthand for issue numbers.
  • Read a specific issue by its Linear UUID. (Note: the UUID is what the list/search tools return — not the human-readable identifier like ENG-9.)
  • Open new issues in a team.
  • Post comments on an issue.

Example prompts:

  • "Find Linear ENG-321 in the Eng team and pull it into Lanes."
  • "Comment on Linear ENG-321 with the PR link once the session lands."
  • "Open a new Linear issue in the Eng team called 'follow-up: cleanup' with these notes from the session."

The agent reads tokens from integrations.json directly, including the refresh path — you don't paste the access token anywhere. The skill at plugins/lanes-desktop/skills/linear-lanes-bridge/SKILL.md (ships with the lanes-desktop Claude Code plugin) walks an agent through the full import → execute → push loop, including dedup, sprint imports, and issue decomposition.

Scope Limits

A few things to know about what Lanes can and can't do via Linear:

  • lanes_linear_get_issue takes the UUID, not the identifier. Agents must look up the UUID via list_issues or search_issues first; passing ENG-9 directly will fail. The skill above handles this for you.
  • The default team is a UI affordance only. Agents always see every team and must pick one explicitly.
  • Linear projects, cycles, and priority are not currently mapped. The import dialog and the MCP tools focus on the core issue fields (title, description, state, URL). For richer metadata, comment back on the Linear ticket rather than trying to mirror everything into Lanes.
  • State mapping is not automatic. Linear's state names are team-scoped; Lanes columns are backlog / todo / in-progress / done. On import, the agent (or you) decide where the ticket lands.

For the agent-side details and the full tool reference, see Lanes Desktop MCP → Linear.