From Linear Issue to Agent-Built PR: A Working Workflow

Published July 10, 2026 · by the AQ team

The cleanest Linear coding agent workflow is label-driven: add an "ai-task" label to an issue, and a ready-to-work agent workspace appears for your team, with the issue moved to In Progress. A human then opens that workspace, starts the agent with the issue as context, and steers it to a PR that is tracked back against the issue.

This guide walks the full loop as it works in AQ, and explains one deliberate design choice up front: the label does not launch an agent. A person does.

Why route agent work through Linear at all?

Because the issue tracker is already where work is defined, prioritized, and assigned. Bolting an agent workflow onto a separate tool creates a second backlog nobody grooms. When the trigger is a Linear label, agent work inherits everything the tracker already does: the written spec in the issue description, the priority discussion in the comments, the assignee, and the status that the rest of the company watches. The agent becomes a way to execute issues, not a new place where work hides.

The workflow, step by step

AQ is the multiplayer workspace where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. Here is what happens when you connect it to Linear.

1. Label an issue "ai-task"

Any issue you judge agent-suitable gets the label. Good candidates read like a spec: a bug with reproduction steps, a well-scoped feature, a mechanical refactor. The labeling decision is itself the first act of triage: you are asserting the issue is defined well enough that an agent plus a reviewer can carry it.

2. A workspace appears in the sidebar, and the issue moves to In Progress

AQ receives the label event by webhook (with a sync poll as a fallback) and creates a workspace for the issue: an isolated git worktree with its own branch, visible in the team's sidebar. The Linear issue is moved to In Progress automatically, so the tracker reflects reality without anyone touching it. If the issue already has a workspace, the label is deduplicated instead of spawning a second one. Ownership follows the Linear assignee, so the issue's owner owns the workspace.

3. A teammate opens the workspace and starts the agent

This is the human-in-the-loop step. Someone opens the workspace and launches the CLI they want (Claude Code, Codex, Cursor Agent, Kimi, Grok, or a plain shell) with the issue context to hand. The environment is already prepared: worktree checked out on its own branch, dependencies installed. The person starting the run frames the task, sets constraints, and stays in the loop while the agent works; teammates can open the same workspace and watch or steer the same live terminal.

4. The agent works, commits, and opens a PR

The agent runs as a real CLI in tmux on your infrastructure, streamed to the browser. It commits and pushes on the workspace branch and opens the PR with the operating user's own GitHub credentials, so authorship and permissions are the user's, not a bot account's.

5. AQ tracks the PR on the workspace

PRs opened from the workspace branch are discovered and tracked automatically: opened, merged, and closed each become events on the workspace. Anyone looking at the workspace (or the sidebar) can see where the work stands without cross-referencing GitHub.

6. Closing the loop

When the Linear issue is marked Done or Canceled, AQ closes the workspace. The tracker stays the source of truth for whether the work is finished, and the platform follows it, cleaning up the worktree rather than accumulating zombie environments.

Why doesn't the label auto-launch the agent?

Deliberately. AQ creates the workspace from the label but never starts an agent on its own, and this is the part of the design most worth defending:

• Review bandwidth is the real constraint. An auto-launcher turns every labeled issue into an unreviewed diff by lunchtime. Agents generate code much faster than teams review it; a queue of workspaces waiting for a human start is honest about that. A pile of auto-generated PRs is not.
• Intent matters at launch time. The first prompt sets scope, constraints, and approach, and it benefits from a human who has just read the issue. Two issues with identical labels can deserve completely different framings.
• Accountability stays with a person. The engineer who starts the run owns steering it and owns the PR. "The label did it" is not an owner.

The result is a queue model rather than a fire-and-forget model: Linear labels fill the queue, humans drain it at the pace they can actually review.

What makes a Linear issue agent-ready?

• A concrete definition of done. "Fix flaky checkout test" beats "improve test reliability."
• Reproduction steps or pointers. File paths, error messages, and links to prior art cut the agent's exploration time dramatically.
• Explicit non-goals. One line ("do not touch the payment provider integration") prevents the most common agent failure: enthusiastic overreach.
• Right-sized scope. One issue, one branch, one PR a reviewer can hold in their head. If the issue needs three PRs, split the issue first.

Teams that adopt this loop tend to start writing better issues within a couple of weeks, because vague issues visibly stall at step 3 while precise ones flow through.

The full loop at a glance

Two automations bookend the loop (workspace creation at the start, PR tracking and closure at the end), and the judgment calls in the middle stay human. That split is what keeps an agent workflow fast without letting it outrun the team's ability to review what it produces.