Linear
Resolve team-specific workflows before mutation and keep Linear's native priorities, cursor pagination, and parent links behind the normalized contract.
Configure
import { createWorkClient } from "work-sdk";
import { linear } from "work-sdk/linear";
export const work = createWorkClient({
adapter: linear({
apiKey: process.env.LINEAR_API_KEY!,
teamId: "team_01JEXAMPLE",
}),
});Use a personal API key for a single workspace or an OAuth access token for an installed application. teamId provides the default team for creates and state resolution.
Teams and identifiers
get accepts a Linear UUID or readable identifier such as ENG-123. Creates need a team from the adapter or input.project. List cursors are opaque GraphQL cursors and must be passed back unchanged.
State and label names are scoped by workspace and team. Resolve them through the adapter rather than hard-coding internal Linear IDs in an agent prompt.
States and priorities
| Work SDK | Linear |
|---|---|
| backlog | Workflow state type backlog |
| unstarted | Workflow state type unstarted |
| started | Workflow state type started |
| completed | Workflow state type completed |
| urgent / high / medium / low / none | Native priority 1–4 or 0 |
The normalized state is portable. stateName preserves the workspace's exact display name, such as “In review”.
Safe write
const change = await work.prepareUpdate("ENG-123", {
state: "Done",
priority: "high",
parentId: "ENG-100",
});
const receipt = await work.commit(change, {
idempotencyKey: "agent-run:42:ENG-123",
});Prepared changes include the current Linear issue and revision fingerprint. A final read blocks a stale plan before mutation; Linear does not expose an atomic compare-and-set for this adapter, so the guarantee remains preflight.
Limits
- Linear supports one assignee in the portable contract.
- Custom fields and project milestones remain provider-specific.
- Workspace permissions and team membership still apply to every request.