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: Provide Keys During Init

The clawup init wizard prompts you for each agent’s Linear API key: 
? Linear API key for Juno (pm) lin_api_XXXXXXXXXXXX
? Linear API key for Titus (eng) lin_api_XXXXXXXXXXXX
? Linear API key for Scout (tester) lin_api_XXXXXXXXXXXX
Keys are stored encrypted in Pulumi config as secrets (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:
AgentAdds to QueueRemoves from Queue
Juno (PM)Backlog, UnstartedTriage, Started, Completed, Cancelled
Titus (Eng)Backlog, StartedTriage, Completed, Cancelled
Scout (QA)StartedTriage, 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
During clawup init, the CLI collects a Linear webhook secret per agent. 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. Set the secret to match what you provided during init
  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: 
# 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

AgentHow 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: 
{
  "linearTeam": "ENG"
}
This maps to the {{LINEAR_TEAM}} template variable in identity workspace files.