> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawup.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Connect your agents to Linear for ticket tracking and backlog management

Linear is the primary way your agents coordinate work. Juno breaks down tickets, Titus picks them up for engineering, and Scout tracks verification — all through Linear.

## What You Need

A **Linear API key** for each agent. Each agent gets its own Linear account so you can see who did what.

<Note>
  Linear integration is optional but strongly recommended. Without it, agents lose the ability to track and coordinate work through tickets.
</Note>

## Step 1: Create Agent Accounts

Each agent needs its own Linear account so you can track who did what. A recommended approach is to use plus-addressing — no extra email addresses needed.

1. Go to your Linear workspace settings
2. Invite each agent using plus-addressing on your email:
   * `you+juno@yourdomain.com` (PM)
   * `you+titus@yourdomain.com` (Engineer)
   * `you+scout@yourdomain.com` (QA Tester)
3. Follow the invite links to create each account and join your workspace

<Tip>
  Plus-addressing (e.g., `you+juno@gmail.com`) forwards to your inbox automatically. No new email accounts needed.
</Tip>

## Step 2: Generate API Keys

For each agent account:

1. Log into Linear as that agent
2. Go to **Settings** > **Security & Access** > **Personal API keys**
3. Click **"New API key"**
4. Copy the key — it starts with `lin_api_`

## Step 3: Add Keys to `.env`

Add each agent's Linear API key to your `.env` file using the `<ROLE>_LINEAR_API_KEY` pattern:

```bash theme={null}
PM_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
ENG_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
TESTER_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
```

When you run `clawup deploy`, these are validated and stored encrypted in Pulumi config (e.g., `pmLinearApiKey`, `engLinearApiKey`).

## What Gets Installed

On each agent's server, the deploy process automatically:

1. Installs **Deno** and the **Linear CLI** (`@schpet/linear-cli`)
2. Sets `LINEAR_API_KEY` as an environment variable
3. Installs and configures the **openclaw-linear plugin** — the webhook-driven queue system that triggers agent work

## Linear Plugin

The `openclaw-linear` plugin is the core mechanism that drives agent work. It's an OpenClaw extension that receives Linear webhooks, maintains per-agent ticket queues, and automatically invokes queue handler skills when tickets arrive.

### How It Works

1. A ticket changes state in Linear (e.g., moved to "Backlog" or "In Progress")
2. Linear sends a webhook to the agent's endpoint
3. The plugin evaluates per-role routing rules to decide whether to add or remove the ticket from the agent's queue
4. When a ticket is added to the queue, the plugin automatically triggers the agent's **queue handler skill**

### Queue Routing Rules

Each role has rules that determine which Linear workflow states add or remove tickets from the queue:

| Agent           | Adds to Queue      | Removes from Queue                    |
| --------------- | ------------------ | ------------------------------------- |
| **Juno** (PM)   | Backlog, Unstarted | Triage, Started, Completed, Cancelled |
| **Titus** (Eng) | Backlog, Started   | Triage, Completed, Cancelled          |
| **Scout** (QA)  | Started            | Triage, Completed, Cancelled          |

For example: when a ticket moves to "Backlog", it enters both Juno's and Titus's queues. When it moves to "Started", it enters Titus's and Scout's queues (and is removed from Juno's).

### Queue Handler Skills

Each agent has a queue handler skill that processes tickets from their queue:

* **`pm-queue-handler`** (Juno) — Routes the ticket by labels, preps it with research and context via `linear-ticket-prep`, sizes it, and assigns it to Titus
* **`eng-queue-handler`** (Titus) — Delegates implementation to Claude Code, monitors progress, runs build/test checks, creates a PR, and assigns Scout for review
* **`tester-queue-handler`** (Scout) — Reviews the PR against acceptance criteria, runs build/test suites, auto-fixes simple failures, and reports results

These skills are not user-invocable — they're triggered automatically by the plugin when a ticket enters the queue.

### Webhook Setup

Each agent gets a webhook endpoint on your Tailscale network:

```
https://<stack>-<agent-name>.<tailnet>/hooks/linear
```

Each agent needs a **Linear webhook secret**. Add them to your `.env` file as `<ROLE>_LINEAR_WEBHOOK_SECRET`. You need to register the webhook URL in Linear:

1. Go to **Linear Settings** > **API** > **Webhooks**
2. Create a webhook pointing to the agent's endpoint URL
3. Copy the signing secret and add it to `.env`
4. Enable the **Issues** event type

<Tip>
  You can set or rotate webhook secrets post-deploy with `clawup secrets set linearWebhookSecret <secret> --agent <role>`.
</Tip>

### Plugin Configuration

The plugin is configured automatically during deploy with:

* **API key** — The agent's Linear API key
* **Webhook secret** — For verifying incoming webhooks
* **Agent mapping** — Maps the Linear user UUID to the OpenClaw agent ID
* **State actions** — Per-role routing rules (which workflow states add/remove from the queue)

## How Agents Use Linear

Agents use the Linear CLI and plugin tools to manage tickets:

```bash theme={null}
# List tickets assigned to the agent
linear issue list --filter "assignee:me"

# View ticket details
linear issue view ENG-123

# Update ticket status
linear issue update ENG-123 --state "In Progress"

# Create a sub-task
linear issue create --title "Implement auth endpoint" --team ENG --parent ENG-100
```

### By Role

| Agent                | How They Use Linear                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Juno** (PM)        | Receives tickets via queue, breaks them down into sub-tasks, preps with research and context, assigns to Titus |
| **Titus** (Engineer) | Receives tickets via queue, delegates to Claude Code, creates PRs, assigns Scout for review                    |
| **Scout** (QA)       | Receives tickets via queue, reviews PRs against acceptance criteria, runs tests, reports results               |

## Manifest Configuration

Set your Linear team in the manifest so agents know which team to work with:

```json theme={null}
{
  "linearTeam": "ENG"
}
```

This maps to the `{{LINEAR_TEAM}}` template variable in identity workspace files.