linear-use

A small Claude Code / Codex plugin that keeps AI-driven work tracked in Linear. It's two pieces — a skill and a hook — plus the official Linear MCP, wired together so that the moment an agent starts deliberate work, a ticket exists and moves through your workflow on its own.

We built this for ourselves at Prime Radiant and use it every day. We're publishing it as an example of how we work, so you can see the pattern and adapt it to your team.

What it does

When you ask an agent to build, fix, refactor, or otherwise produce something, the plugin makes sure that work is tracked:

1. Find or create a ticket. The linear-ticket-lifecycle skill resolves a ticket from what you said, the branch name, a Linear search, or — if nothing fits — by creating one. You always end up with a ticket.
2. Move it as work progresses. Ticket goes to In Progress when work starts and In Review when implementation is done.
3. Leave an honest note. On reaching review, the agent writes a reflective comment — what was smooth, what was tricky, what a reviewer should watch — not a "done, all tests pass" status line.
4. Nudge so it doesn't get skipped. A UserPromptSubmit hook reminds the agent to invoke the skill, escalating when there are uncommitted changes.

The agent never closes tickets. Only humans move work to a terminal state.

How it's built

Install

/plugin marketplace add prime-radiant-inc/agent-plugin-linear-use
/plugin install linear-use@prime-radiant

Then connect Linear: run /mcp and complete the OAuth flow for the bundled linear server. That's the only setup — the skill speaks the official Linear MCP's tool vocabulary, so once you're authorized it just works.

Adapt it to your team

The skill ships configured for an example team. Three knobs to change:

• Team key. It uses ENG (e.g. ENG-123, branch match eng-(\d+)). Replace ENG throughout SKILL.md with your Linear team key.
• Workflow states. It uses In Progress (which ships with every Linear workspace) and In Review (common, but not a default — add it if your workspace doesn't have one). Rename them in SKILL.md to match your team; we use In Dev internally.
• Where the hook fires. By default the reminder fires in any git repo. To scope it, set LINEAR_USE_REPO_MATCH to a substring of your repos' origin URLs (e.g. export LINEAR_USE_REPO_MATCH=my-org); the hook then fires only when origin contains that substring. Leave it unset to fire everywhere.

Notes

• Hook mechanism. The reminder reaches the agent through hookSpecificOutput.additionalContext, the documented way for a UserPromptSubmit hook to add context Claude will read.
• A different Linear MCP. We also maintain @primeradianthq/streamlinear, an API-key-driven Linear MCP server, for environments where the hosted OAuth server isn't a fit. This plugin bundles the official one because it's the easiest to set up and matches the skill's tool names. If you swap in another Linear MCP, make sure its tools match (get_issue, list_issues, save_issue, save_comment, list_issue_statuses, list_projects).

Tests

test/ticket-phase-reminder.test.sh

Exercises the hook's branches: outside a git repo (silent), clean tree (gentle reminder), dirty tree (escalated reminder), and the LINEAR_USE_REPO_MATCH filter.

License

MIT — see LICENSE.