Skip to main content
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.
Linear integration is optional but strongly recommended. Without it, agents lose the ability to track and coordinate work through tickets.

​
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
Plus-addressing (e.g., you+juno@gmail.com) forwards to your inbox automatically. No new email accounts needed.

​
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:
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: 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:
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
You can set or rotate webhook secrets post-deploy with clawup secrets set linearWebhookSecret <secret> --agent <role>.

​
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:

​
By Role

​
Manifest Configuration

Set your Linear team in the manifest so agents know which team to work with:
This maps to the {{LINEAR_TEAM}} template variable in identity workspace files.