@kody/linear

@kody/linear — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets and OAuth by name only — never paste tokens. Do not disable live webhooks or jobs.

Auth

OAuth Bearer vs personal API key (no Bearer) is handled by the package. Host: api.linear.app. GraphQL: https://api.linear.app/graphql.

Do not hard-code a personal workspace slug or alias.

Import paths

Prefer static kody:@kody/linear/... imports from execute. Do not lead with packages.invoke.

Priority values: 0 none, 1 urgent, 2 high, 3 medium, 4 low. Workflow state types: triage, backlog, unstarted, started, completed, canceled.

Smoke test (read-only)

import smokeTest from 'kody:@kody/linear/smoke-test'

export default async function main() {
	return await smokeTest()
	// Without credentials: { ok: true, live: false } + connect / API-key URLs
	// With credentials: { live: true, hasViewerId, hasOrganizationId } (no email)
}

dryRun / confirm

Mutating helpers require confirm: true. Pass dryRun: true to inspect the GraphQL payload without calling Linear. ./request treats query documents as read-only; mutation documents need confirmation.

import createIssue from 'kody:@kody/linear/create-issue'

export default async function main() {
	const preview = await createIssue({
		title: 'Investigate checkout timeout',
		teamId: 'team-uuid',
		priority: 2,
		dryRun: true,
	})
	// After the user confirms the exact team and title:
	return await createIssue({
		title: 'Investigate checkout timeout',
		teamId: 'team-uuid',
		priority: 2,
		confirm: true,
	})
}

Read helpers:

import listIssues from 'kody:@kody/linear/list-issues'
import listWorkflowStates from 'kody:@kody/linear/list-workflow-states'

export default async function main() {
	const states = await listWorkflowStates({ teamKey: 'ENG' })
	return await listIssues({
		teamKey: 'ENG',
		stateType: 'started',
		first: 20,
	})
}

Unwrapped GraphQL:

import request from 'kody:@kody/linear/request'

export default async function main() {
	return await request({
		query: `query ($key: String!) {
			team(id: $key) { id name key }
		}`,
		variables: { key: 'ENG' },
	})
}

Edge cases

• If Linear returns 401/403 or GraphQL FORBIDDEN / insufficient-scope, helpers throw a message that names the missing scope and the next setup URL.
• assigneeId: 'me' on ./list-issues filters to the authorizing user.
• Helpers project slim objects. Use ./request when you need extra fields.
• Prefer @kody/linear-mcp only for a faster first win; this package is the preferred invoke path once BYO OAuth or an API key is set up.