Linear Issues

Agents file, triage and close issues. The failure modes are quiet: a retry after a lost response files a duplicate, two agents move the same issue, or a comment posts twice. Invoke closes each one.

Tool names depend on how your workspace connects to Linear. Run invoke gateway tools to see the tools your workspace has.

One issue per piece of work

Name the issue after the work it tracks. The same key is the same issue:

const filed = await invoke.call({
  tool: "linear.create_issue",
  params: { team_id: "team_eng", title: "Fix checkout timeout bug", description: "Found in checkout logs." },
  agentId: "eng-agent",
  idempotencyKey: "linear:checkout-timeout",
})

A retry, or another run of the same plan, resolves with status: "duplicate" and the original issue. No second issue is filed. If the response is lost after Linear got the request, Invoke can’t tell whether the issue was created, so it doesn’t file it again. The call throws OutcomeUnknownError with safeToRetry: false. Check the team’s backlog, then settle it at err.resolveUrl.

Updating is safe to repeat

linear.update_issue reads the issue first and applies only what’s missing. Its comment has a fixed id, so posting it twice is impossible. That makes it safe to re-run as the same action: if an answer is lost, the SDK sends the same action again and Invoke reconciles it. You get the receipt, and one comment.

await invoke.call({
  tool: "linear.update_issue",
  params: { issue_id: "ENG-42", state: "In Review", comment: "Fix is up for review." },
  agentId: "eng-agent",
  idempotencyKey: "ENG-42:review",
})

One agent per issue

When an agent claims an issue through Invoke, the claim locks it. Another agent’s write to that issue is refused with DeniedError (denied_claim) and never reaches Linear. Reads never wait on a claim. The claim is released when the task is completed or handed off.

Next steps

TypeScript SDK: idempotency and errors in full
Reconciliation: what happens when an answer is lost
Invoke MCP: claims, context and handoffs for MCP agents

Get Started

Core Concepts

Guides

SDK & CLI

Configuration

One issue per piece of work

Updating is safe to repeat

One agent per issue

Next steps

​One issue per piece of work

​Updating is safe to repeat

​One agent per issue

​Next steps

One issue per piece of work

Updating is safe to repeat

One agent per issue

Next steps