@calltelemetry/openclaw-linear 0.3.0 → 0.4.0

package/README.md

@@ -1,120 +1,287 @@
-# Linear Agent Plugin for OpenClaw
+# @calltelemetry/openclaw-linear
 
-Webhook-driven Linear integration with OAuth support, multi-agent routing, and a 3-stage AI pipeline for issue triage and implementation.
+An OpenClaw plugin that connects your Linear workspace to AI agents. Issues get triaged automatically, agents respond to @mentions, and a full plan-implement-audit pipeline runs when you assign work to the agent.
 
-## What It Does
+## Features
 
-- **Issue triage** — When an issue is assigned/delegated to the app user, an agent estimates story points, applies labels, and posts an assessment
-- **Agent sessions** — Full plan-approve-implement-audit pipeline triggered from Linear's agent UI
-- **@mention routing** — Comment mentions like `@qa` or `@infra` route to specific role-based agents with different expertise
-- **App notifications** — Responds to Linear app mentions and assignments via branded comments
-- **Activity tracking** — Emits thought/action/response events visible in Linear's agent session UI
+- **Auto-triage** — New issues get story point estimates, labels, and priority automatically
+- **@mention routing** — `@qa`, `@infra`, `@docs` in comments route to specialized agents
+- **Agent pipeline** — Assign an issue to the agent and it plans, implements, and audits the work
+- **Branded replies** — Each agent posts with its own name and avatar in Linear
+- **Real-time progress** — Agent activity (thinking, acting, responding) shows in Linear's UI
+- **Unified `code_run` tool** — One tool, three coding CLI backends (Codex, Claude Code, Gemini CLI), configurable per agent
+- **Issue management via `linearis`** — Agents use the `linearis` CLI to update status, close issues, add comments, and more
 
-## Quick Install
+## Architecture
+
+### Webhook Flow
+
+```
+  Linear                  OpenClaw Gateway              AI Agents
+    |                           |                          |
+    |  Webhook (issue created)  |                          |
+    |  ────────────────────────>|                          |
+    |                           |  Dispatch triage agent   |
+    |                           |  ───────────────────────>|
+    |                           |                          |
+    |                           |  Estimate + labels       |
+    |                           |  <───────────────────────|
+    |  Update issue             |                          |
+    |  <────────────────────────|                          |
+    |  Post assessment comment  |                          |
+    |  <────────────────────────|                          |
+```
+
+```
+  Linear                  OpenClaw Gateway              AI Agents
+    |                           |                          |
+    |  "@qa check this"         |                          |
+    |  ────────────────────────>|                          |
+    |                           |  Route to QA agent       |
+    |                           |  ───────────────────────>|
+    |                           |                          |
+    |                           |  Response                |
+    |                           |  <───────────────────────|
+    |  Comment from "QA"        |                          |
+    |  <────────────────────────|                          |
+```
+
+### Two Webhook Systems
+
+Linear delivers events through two separate webhook paths:
+
+1. **Workspace webhook** (Settings > API > Webhooks) — handles Comment, Issue, and User events
+2. **OAuth app webhook** (Settings > API > Applications > your app) — handles `AgentSessionEvent` (created/prompted)
+
+Both must point to the same URL: `https://<your-domain>/linear/webhook`
+
+### Source Layout
+
+```
+index.ts                  Plugin entry point, CLI checks, tool/webhook registration
+src/
+  webhook.ts              Webhook handler — routes events to agents, builds prompts
+  pipeline.ts             3-stage pipeline: plan → implement → audit
+  agent.ts                Agent execution wrapper
+  active-session.ts       In-process session registry (issueId → session)
+
+  code-tool.ts            Unified code_run tool — dispatches to configured backend
+  cli-shared.ts           Shared helpers for CLI tools (buildLinearApi, resolveSession)
+  codex-tool.ts           Codex CLI runner (JSONL stream → Linear activities)
+  claude-tool.ts          Claude Code CLI runner (JSONL stream → Linear activities)
+  gemini-tool.ts          Gemini CLI runner (JSONL stream → Linear activities)
+  coding-tools.json       Backend config (default tool, per-agent overrides, aliases)
+
+  tools.ts                Tool registration (code_run + orchestration)
+  orchestration-tools.ts  spawn_agent / ask_agent for multi-agent delegation
+  linear-api.ts           Linear GraphQL API client, token resolution, activity streaming
+  client.ts               Lightweight Linear GraphQL client (legacy, unused by tools)
+  auth.ts                 OAuth token management and profile storage
+  oauth-callback.ts       OAuth callback handler
+  cli.ts                  CLI subcommands (auth, status)
+  codex-worktree.ts       Git worktree management for isolated Codex runs
+```
+
+## Coding Tool (`code_run`)
+
+The plugin provides a single `code_run` tool that dispatches to one of three coding CLI backends. Agents call `code_run` without needing to know which backend is active — the dispatcher handles routing.
+
+### Supported Backends
+
+| Backend | CLI | Stream Format | Key Flags |
+|---|---|---|---|
+| **Codex** (OpenAI) | `codex` | JSONL | `--full-auto`, `-q` |
+| **Claude Code** (Anthropic) | `claude` | JSONL (`stream-json`) | `--print`, `--dangerously-skip-permissions`, `--verbose` |
+| **Gemini CLI** (Google) | `gemini` | JSONL (`stream-json`) | `--yolo`, `-o stream-json` |
+
+All three stream JSONL events that get mapped to Linear agent activities in real-time (thoughts, actions, tool results).
+
+### Backend Resolution Priority
+
+When `code_run` is called:
+
+1. **Explicit `backend` parameter** — Agent passes `backend: "gemini"` (or any alias)
+2. **Per-agent override** — `agentCodingTools` in `coding-tools.json`
+3. **Global default** — `codingTool` in `coding-tools.json`
+4. **Hardcoded fallback** — `"claude"`
+
+### Configuration (`coding-tools.json`)
+
+```json
+{
+  "codingTool": "codex",
+  "agentCodingTools": {
+    "kaylee": "claude",
+    "inara": "gemini"
+  },
+  "backends": {
+    "claude": {
+      "aliases": ["claude", "claude code", "anthropic"]
+    },
+    "codex": {
+      "aliases": ["codex", "openai"]
+    },
+    "gemini": {
+      "aliases": ["gemini", "google"]
+    }
+  }
+}
+```
+
+- **`codingTool`** — Default backend for all agents
+- **`agentCodingTools`** — Per-agent overrides (keyed by agent ID)
+- **`backends.*.aliases`** — Alias strings so the agent (or user) can say "use google" and it resolves to `gemini`
+
+### Backend-Specific Notes
+
+**Claude Code:**
+- Must unset `CLAUDECODE` env var to avoid "nested session" error
+- Requires `--verbose` alongside `stream-json` for full event output
+- Content blocks are arrays: `message.content[].type` can be `text` or `tool_use`
+
+**Gemini CLI:**
+- Working directory set via `spawn()` `cwd` option (no `-C` flag)
+- Model override via `-m <model>` flag
+- Stderr may include "YOLO mode" warnings — filtered from output
+
+**Codex:**
+- Uses git worktrees for isolated runs (see `codex-worktree.ts`)
+- Model/timeout configurable via plugin config (`codexModel`, `codexTimeoutMs`)
+
+## Linear Issue Management (`linearis` Skill)
+
+Issue management (update status, close, assign, comment, labels, etc.) is handled by the **`linearis`** CLI, installed as an OpenClaw skill. This replaces custom GraphQL tools — agents use `linearis` via exec.
+
+### Install
 
 ```bash
-openclaw plugins install @calltelemetry/openclaw-linear
-openclaw gateway restart
+npx clawhub install linearis
+npm install -g linearis
 ```
 
-That's it — the plugin is installed and enabled. Continue with the [setup steps](#setup) below to configure Linear OAuth and webhooks.
+### Auth
+
+```bash
+echo "lin_api_..." > ~/.linear_api_token
+```
 
-> To install from a local checkout instead: `openclaw plugins install --link /path/to/linear`
+Or set `LINEAR_API_TOKEN` env var.
+
+### Key Commands
+
+```bash
+linearis issues list -l 20               # List recent issues
+linearis issues list --team UAT           # Filter by team
+linearis issues search "auth bug"         # Full-text search
+linearis issues read API-123              # Get issue details
+linearis issues update API-123 --status "Done"     # Close issue
+linearis issues update API-123 --status "In Progress"
+linearis issues update API-123 --assignee user123
+linearis issues update API-123 --labels "Bug" --label-by adding
+linearis issues create --title "Fix it" --team UAT --priority 2
+linearis comments create API-123 --body "Fixed in PR #456"
+linearis teams list
+linearis users list --active
+linearis projects list
+linearis documents list
+linearis usage                            # Full command reference
+```
+
+All output is JSON, suitable for piping to `jq`.
 
 ## Prerequisites
 
-- OpenClaw gateway running (systemd service)
-- A Linear workspace with API access
-- A Linear OAuth application (Settings > API > Applications)
-- A public URL for webhook delivery (e.g., Cloudflare tunnel)
+- **OpenClaw** gateway running (v2026.2+)
+- **Linear** workspace with API access
+- **Public URL** for webhook delivery (Cloudflare Tunnel recommended)
+- **Coding CLIs** (at least one): `codex`, `claude`, `gemini` — installed in PATH
+- **linearis** CLI — for issue management
+
+## Install
+
+```bash
+openclaw plugins install @calltelemetry/openclaw-linear
+```
 
 ## Setup
 
-### 1. Create a Linear OAuth Application
+### 1. Create a Linear OAuth App
+
+Go to **Linear Settings > API > Applications** and create a new application:
+
+- **Webhook URL:** `https://<your-domain>/linear/webhook`
+- **Redirect URI:** `https://<your-domain>/linear/oauth/callback`
+- Enable webhook events: **Agent Sessions**, **Comments**, **Issues**
 
-1. Go to **Linear Settings > API > Applications**
-2. Click **Create new application**
-3. Fill in:
-   - **Application name:** your agent's name
-   - **Redirect URI:** `https://<your-domain>/linear/oauth/callback`
-   - **Webhook URL:** `https://<your-domain>/linear/webhook`
-4. Note the **Client ID** and **Client Secret**
-5. Enable the webhook events you need (Agent Sessions, Issues)
+Save the **Client ID** and **Client Secret**.
 
-### 2. Create a Workspace Webhook
+### 2. Set Credentials
 
-Separately from the OAuth app, create a workspace-level webhook:
+Add to your gateway's environment (systemd service or shell):
 
-1. Go to **Linear Settings > API > Webhooks**
-2. Create a new webhook pointing to `https://<your-domain>/linear/webhook`
-3. Enable these event types: **Comment**, **Issue**, **User**
+```bash
+export LINEAR_CLIENT_ID="your_client_id"
+export LINEAR_CLIENT_SECRET="your_client_secret"
+```
 
-> **Why two webhooks?** The OAuth app webhook handles `AgentSessionEvent` and `AppUserNotification` events (agent-specific). The workspace webhook handles `Comment` and `Issue` events (workspace-wide). Both must point to the same URL — the plugin routes internally.
+For systemd:
 
-### 3. Expose the Gateway via Cloudflare Tunnel
+```ini
+[Service]
+Environment=LINEAR_CLIENT_ID=your_client_id
+Environment=LINEAR_CLIENT_SECRET=your_client_secret
+```
 
-The OpenClaw gateway listens on `localhost:<port>` (default `18789`). Linear must reach it over HTTPS to deliver webhooks. A [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is the recommended approach — no open inbound ports, no self-managed TLS.
+Then reload: `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`
 
-#### Install `cloudflared`
+### 3. Expose the Gateway
+
+Linear needs to reach your gateway over HTTPS to deliver webhooks. A [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is the recommended approach — no open ports, no TLS certificates to manage.
+
+#### a. Install `cloudflared`
 
 ```bash
 # RHEL / Rocky / Alma
 sudo dnf install -y cloudflared
 
 # Debian / Ubuntu
-curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
-echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
-sudo apt update && sudo apt install -y cloudflared
+sudo apt install -y cloudflared
 
 # macOS
 brew install cloudflare/cloudflare/cloudflared
 ```
 
-#### Authenticate with Cloudflare
+#### b. Authenticate with Cloudflare
 
 ```bash
 cloudflared tunnel login
 ```
 
-This opens your browser to Cloudflare's authorization page. You must:
-
-1. Log in to your Cloudflare account
-2. **Select the domain** (zone) you want the tunnel to use (e.g., `yourdomain.com`)
-3. Click **Authorize**
+This opens your browser. Log in, select the domain you want to use, and click **Authorize**.
 
-Cloudflare writes an origin certificate to `~/.cloudflared/cert.pem`. This certificate grants `cloudflared` permission to create tunnels and DNS records under that domain. Without it, tunnel creation will fail.
-
-#### Create a tunnel
+#### c. Create a tunnel
 
 ```bash
 cloudflared tunnel create openclaw
 ```
 
-This outputs a **Tunnel ID** (a UUID like `da1f21bf-856e-...`) and writes a credentials file to `~/.cloudflared/<TUNNEL_ID>.json`.
+Note the **Tunnel ID** (a UUID) from the output.
 
-#### Create a DNS subdomain for the tunnel
+#### d. Point a subdomain at the tunnel
 
 ```bash
 cloudflared tunnel route dns openclaw linear.yourdomain.com
 ```
 
-This creates a **CNAME record** in your Cloudflare DNS:
-
-```
-linear.yourdomain.com  CNAME  <TUNNEL_ID>.cfargotunnel.com
-```
-
-You can verify it in the Cloudflare dashboard under **DNS > Records** for your domain. The subdomain (`linear.yourdomain.com`) is what Linear will use for webhook delivery and OAuth callbacks.
+This creates a DNS record so `linear.yourdomain.com` routes through the tunnel.
 
-> **Important:** Your domain must already be on Cloudflare (nameservers pointed to Cloudflare). If it's not, add it in the Cloudflare dashboard first.
-
-#### Configure the tunnel
+#### e. Configure the tunnel
 
 Create `~/.cloudflared/config.yml`:
 
 ```yaml
 tunnel: <TUNNEL_ID>
-credentials-file: /home/<user>/.cloudflared/<TUNNEL_ID>.json
+credentials-file: ~/.cloudflared/<TUNNEL_ID>.json
 
 ingress:
   - hostname: linear.yourdomain.com
@@ -122,22 +289,21 @@ ingress:
   - service: http_status:404
 ```
 
-The `ingress` rule routes all traffic for your subdomain to the OpenClaw gateway on localhost. The catch-all `http_status:404` rejects requests for any other hostname.
-
-#### Run as a systemd service
+#### f. Start the tunnel
 
 ```bash
+# Install as a system service (starts on boot)
 sudo cloudflared service install
 sudo systemctl enable --now cloudflared
 ```
 
-This installs a system-level service that starts on boot. To test without installing:
+To test without installing as a service:
 
 ```bash
 cloudflared tunnel run openclaw
 ```
 
-#### Verify end-to-end
+#### g. Verify the tunnel
 
 ```bash
 curl -s https://linear.yourdomain.com/linear/webhook \
@@ -146,228 +312,105 @@ curl -s https://linear.yourdomain.com/linear/webhook \
 # Should return: "ok"
 ```
 
-> **Note:** The hostname you choose here (`linear.yourdomain.com`) is what you'll use for the OAuth redirect URI and both webhook URLs in Linear. Make sure they all match.
+### 4. Authorize with Linear
 
-### 4. Set Environment Variables
-
-Required:
 ```bash
-export LINEAR_CLIENT_ID="your_client_id"
-export LINEAR_CLIENT_SECRET="your_client_secret"
+openclaw openclaw-linear auth
 ```
 
-Optional:
-```bash
-export LINEAR_REDIRECT_URI="https://your-domain.com/linear/oauth/callback"
-export OPENCLAW_GATEWAY_PORT="18789"  # if non-default
-```
+This opens your browser to authorize the agent. The plugin needs these OAuth scopes:
 
-### 5. Install the Plugin
+| Scope | What it enables |
+|---|---|
+| `read` / `write` | Read and update issues, post comments |
+| `app:assignable` | Agent appears in Linear's assignment menus |
+| `app:mentionable` | Users can @mention the agent in comments |
 
-If you haven't already installed via [Quick Install](#quick-install):
+After authorization, restart the gateway:
 
 ```bash
-openclaw plugins install @calltelemetry/openclaw-linear
-openclaw gateway restart
+systemctl --user restart openclaw-gateway
 ```
 
-This registers the plugin in your OpenClaw config and restarts the gateway to load it.
-
-<details>
-<summary>Manual config (advanced)</summary>
-
-If you prefer to manage config by hand, add the plugin path to `~/.openclaw/openclaw.json`:
-
-```json
-{
-  "plugins": {
-    "load": {
-      "paths": ["/path/to/linear"]
-    },
-    "entries": {
-      "linear": {
-        "enabled": true
-      }
-    }
-  }
-}
-```
-
-Then restart: `openclaw gateway restart`
-</details>
-
-### 6. Run the OAuth Flow
-
-There are two ways to authorize the plugin with Linear.
-
-#### Option A: CLI Flow (Recommended)
+Verify it's working:
 
 ```bash
-openclaw auth linear oauth
+openclaw openclaw-linear status
 ```
 
-This launches the OAuth flow interactively:
-
-1. The plugin constructs the authorization URL with the required scopes
-2. Your browser opens to Linear's authorization page
-3. You approve the permissions
-4. Linear redirects to the callback URL with an authorization code
-5. The plugin exchanges the code for access + refresh tokens
-6. Tokens are stored in `~/.openclaw/auth-profiles.json`
-
-#### Option B: Manual URL
-
-If the CLI flow doesn't work (headless server, tunnel issues), construct the URL yourself:
-
-```
-https://linear.app/oauth/authorize
-  ?client_id=YOUR_CLIENT_ID
-  &redirect_uri=https://your-domain.com/linear/oauth/callback
-  &response_type=code
-  &scope=read,write,app:assignable,app:mentionable
-  &state=random_string
-  &actor=app
-```
-
-Key parameters:
-
-| Parameter | Value | Why |
-|---|---|---|
-| `scope` | `read,write,app:assignable,app:mentionable` | `app:assignable` lets the agent appear in assignment menus. `app:mentionable` lets users @mention the agent. |
-| `actor` | `app` | Makes the token act as the **application identity**, not a personal user. Agent sessions require this. |
-| `redirect_uri` | Your callback URL | Must match what you registered in the OAuth app settings. |
-
-Click the URL, authorize in Linear, and the callback handler at `/linear/oauth/callback` will exchange the code and store the tokens automatically.
+You should see `token: profile` in the gateway logs.
 
-#### What Gets Stored
+### 5. Configure Agents
 
-After a successful OAuth flow, `~/.openclaw/auth-profiles.json` will contain:
-
-```json
-{
-  "version": 1,
-  "profiles": {
-    "linear:default": {
-      "type": "oauth",
-      "provider": "linear",
-      "accessToken": "...",
-      "refreshToken": "...",
-      "expiresAt": 1708109280000,
-      "scope": "app:assignable app:mentionable read write"
-    }
-  }
-}
-```
-
-This file should be `chmod 600` (owner-only). The plugin auto-refreshes tokens 60 seconds before expiry and persists the new tokens back to this file.
-
-### 7. Configure Agent Profiles
-
-Create `~/.openclaw/agent-profiles.json` to define role-based agents:
+Create `~/.openclaw/agent-profiles.json` to define your agent team:
 
 ```json
 {
   "agents": {
     "lead": {
       "label": "Lead",
-      "mission": "Product owner. Sets direction, makes scope decisions, prioritizes backlog.",
+      "mission": "Product owner. Sets direction, prioritizes backlog.",
       "isDefault": true,
-      "mentionAliases": ["lead", "product"],
-      "appAliases": ["myagent"],
-      "avatarUrl": "https://example.com/lead-avatar.png"
+      "mentionAliases": ["lead"],
+      "avatarUrl": "https://example.com/lead.png"
     },
     "qa": {
       "label": "QA",
-      "mission": "Test engineer. Quality guardian, test strategy, release confidence.",
+      "mission": "Test engineer. Quality guardian, test strategy.",
       "mentionAliases": ["qa", "tester"]
     },
     "infra": {
       "label": "Infra",
-      "mission": "Backend and infrastructure engineer. Performance, reliability, observability.",
+      "mission": "Backend engineer. Performance, reliability, observability.",
       "mentionAliases": ["infra", "backend"]
-    },
-    "ux": {
-      "label": "UX",
-      "mission": "User experience advocate. Accessibility, user journeys, pain points.",
-      "mentionAliases": ["ux", "design"]
-    },
-    "docs": {
-      "label": "Docs",
-      "mission": "Technical writer. Setup guides, API references, release notes.",
-      "mentionAliases": ["docs", "writer"]
     }
   }
 }
 ```
 
-| Field | Required | Description |
-|---|---|---|
-| `label` | Yes | Display name in Linear comments |
-| `mission` | Yes | Agent's role description (injected as system context when the agent is dispatched) |
-| `isDefault` | One agent | The default agent handles OAuth app events, agent sessions, and assignment triage |
-| `mentionAliases` | Yes | @mention triggers in comments (e.g., `@qa` in a comment routes to the QA agent) |
-| `appAliases` | No | Triggers via OAuth app webhook (default agent only, for app-level @mentions) |
-| `avatarUrl` | No | Avatar displayed on branded comments. Falls back to `[Label]` prefix if not set. |
+Each agent name must match an agent definition in your `~/.openclaw/openclaw.json`.
 
-#### How agent-profiles.json connects to openclaw.json
+One agent must be marked `isDefault: true` — this is the agent that handles issue assignments and the pipeline.
 
-Each key in `agent-profiles.json` (e.g., `"lead"`, `"qa"`) must have a matching agent definition in your OpenClaw config (`~/.openclaw/openclaw.json`). The Linear plugin dispatches work via `openclaw agent --agent <id>`, so the agent must actually exist.
+### 6. Configure Coding Tools
 
-Example — if `agent-profiles.json` defines `"lead"` and `"qa"`, your `openclaw.json` needs:
+Create `coding-tools.json` in the plugin root:
 
 ```json
 {
-  "agents": {
-    "lead": {
-      "model": "claude-sonnet-4-5-20250929",
-      "systemPrompt": "You are a product lead agent...",
-      "tools": ["linear_list_issues", "linear_create_issue", "linear_add_comment"]
-    },
-    "qa": {
-      "model": "claude-sonnet-4-5-20250929",
-      "systemPrompt": "You are a QA engineer agent...",
-      "tools": ["linear_list_issues", "linear_add_comment"]
-    }
+  "codingTool": "codex",
+  "agentCodingTools": {},
+  "backends": {
+    "claude": { "aliases": ["claude", "claude code", "anthropic"] },
+    "codex": { "aliases": ["codex", "openai"] },
+    "gemini": { "aliases": ["gemini", "google"] }
   }
 }
 ```
 
-#### Routing flow
+### 7. Install linearis
 
-```
-Linear comment "@qa review this test plan"
-  → Plugin matches "qa" in mentionAliases
-  → Looks up agent-profiles.json → finds "qa" profile
-  → Dispatches: openclaw agent --agent qa --message "<issue context + comment>"
-  → OpenClaw loads "qa" agent config from openclaw.json
-  → Agent runs with the qa profile's mission as context
-  → Response posted back to Linear as a branded comment with qa's label/avatar
+```bash
+npm install -g linearis
+npx clawhub install linearis
+echo "lin_api_YOUR_KEY" > ~/.linear_api_token
 ```
 
-For agent sessions (triggered by the Linear agent UI or app @mentions):
+### 8. Verify
 
+```bash
+systemctl --user restart openclaw-gateway
 ```
-Linear AgentSessionEvent.created
-  → Plugin resolves the default agent (isDefault: true)
-  → Runs the 3-stage pipeline (plan → implement → audit)
-  → Each stage dispatches via the default agent's openclaw.json config
-```
-
-#### What happens if they don't match
 
-- **Agent profile exists but no matching openclaw.json agent:** The dispatch fails and an error is logged. The webhook returns 200 (Linear requirement) but no comment is posted.
-- **openclaw.json agent exists but no profile:** The agent works for direct CLI use but won't be reachable from Linear. No @mention alias maps to it.
-- **No agent marked `isDefault`:** Agent sessions and assignment triage will fail with `"No defaultAgentId"` error.
+Check the logs for a clean startup:
 
-### 8. Verify
-
-```bash
-openclaw gateway restart
-openclaw logs | grep -i linear
-# Should show: "Linear agent extension registered (agent: default, token: profile)"
 ```
+[plugins] Linear agent extension registered (agent: default, token: profile,
+  codex: codex-cli 0.101.0, claude: 2.1.45, gemini: 0.28.2, orchestration: enabled)
+```
+
+Test the webhook:
 
-Test the webhook is reachable:
 ```bash
 curl -s -X POST https://your-domain.com/linear/webhook \
   -H "Content-Type: application/json" \
@@ -375,162 +418,93 @@ curl -s -X POST https://your-domain.com/linear/webhook \
 # Should return: "ok"
 ```
 
-## How It Works
+## Usage
 
-### Token Resolution
+Once set up, the plugin responds to Linear events automatically:
 
-The plugin resolves an OAuth token from:
-
-1. Plugin config `accessToken` (static, for testing)
-2. Auth profile store `linear:default` (from the OAuth flow — this is the normal path)
-
-OAuth is required. The plugin needs `app:assignable` and `app:mentionable` scopes to function — agent sessions, branded comments, assignment triage, and @mention routing all depend on the application identity that only OAuth provides.
-
-### Webhook Event Routing
-
-```
-POST /linear/webhook
-  |
-  +-- AgentSessionEvent.created  --> 3-stage pipeline (plan -> implement -> audit)
-  +-- AgentSessionEvent.prompted --> Resume pipeline (user approved plan)
-  +-- AppUserNotification        --> Direct agent response to mention/assignment
-  +-- Comment.create             --> Route @mention to role-based agent
-  +-- Issue.update               --> Triage if assigned/delegated to app user
-```
-
-All handlers respond `200 OK` within 5 seconds (Linear requirement), then process asynchronously.
+| What you do in Linear | What happens |
+|---|---|
+| Create a new issue | Agent triages it (estimate, labels, priority) and posts an assessment |
+| Assign an issue to the agent | Agent triages and posts assessment |
+| Trigger an agent session | 3-stage pipeline: plan, implement, audit |
+| Comment `@qa check the tests` | QA agent responds with its expertise |
+| Comment `@infra why is this slow` | Infra agent investigates and replies |
+| Ask "close this issue" | Agent runs `linearis issues update API-123 --status Done` |
+| Ask "use gemini to review" | Agent calls `code_run` with `backend: "gemini"` |
 
-### Pipeline Stages
+## Configuration Reference
 
-Triggered by `AgentSessionEvent.created`:
+### Environment Variables
 
-| Stage | Timeout | What It Does |
+| Variable | Required | Description |
 |---|---|---|
-| **Planner** | 5 min | Analyzes issue, generates implementation plan, posts as comment, waits for approval |
-| **Implementor** | 10 min | Follows the approved plan, makes changes, creates commits/PRs |
-| **Auditor** | 5 min | Reviews implementation against plan, posts audit report |
-
-The auditor stage can be disabled via plugin config: `"enableAudit": false`.
-
-### Assignment Triage
+| `LINEAR_CLIENT_ID` | Yes | OAuth app client ID |
+| `LINEAR_CLIENT_SECRET` | Yes | OAuth app client secret |
+| `LINEAR_API_KEY` | No | Personal API key (fallback if no OAuth) |
+| `LINEAR_REDIRECT_URI` | No | Override the OAuth callback URL |
+| `OPENCLAW_GATEWAY_PORT` | No | Gateway port (default: 18789) |
 
-When an issue is assigned or delegated to the app user:
+### Plugin Config
 
-1. Fetches full issue details and available team labels
-2. Dispatches the default agent with a triage prompt
-3. Agent returns JSON with story point estimate and label IDs
-4. Plugin applies the estimate and labels to the issue
-5. Posts the assessment as a branded comment
+Optional overrides in `openclaw.json` under the plugin entry:
 
-### @Mention Routing
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `defaultAgentId` | string | — | Override which agent handles pipeline/triage |
+| `enableAudit` | boolean | `true` | Run the auditor stage after implementation |
+| `enableOrchestration` | boolean | `true` | Allow agents to use `spawn_agent`/`ask_agent` |
+| `codexBaseRepo` | string | `/home/claw/ai-workspace` | Git repo path for Codex worktrees |
+| `codexModel` | string | — | Default Codex model |
+| `codexTimeoutMs` | number | `600000` | Default timeout for coding CLIs |
 
-When a comment contains `@qa`, `@infra`, or any configured `mentionAliases`:
+### Coding Tools Config (`coding-tools.json`)
 
-1. Plugin matches the alias to an agent profile
-2. Reacts with eyes emoji to acknowledge
-3. Fetches full issue context (description, recent comments, labels, state)
-4. Dispatches the matched agent with the comment context
-5. Posts the agent's response as a branded comment on the issue
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `codingTool` | string | `"claude"` | Default coding backend |
+| `agentCodingTools` | object | `{}` | Per-agent backend overrides (`agentId → backendId`) |
+| `backends` | object | `{}` | Per-backend config (aliases, etc.) |
+| `backends.*.aliases` | string[] | `[backendId]` | Alias names that resolve to this backend |
 
-The default agent's `mentionAliases` are excluded from comment routing — the default agent is reached via `appAliases` through the OAuth app webhook instead.
+### Agent Profile Fields
 
-### Comment Deduplication
-
-Webhook events are deduplicated for 60 seconds using a key based on:
-- Comment ID (for `Comment.create`)
-- Session ID (for `AgentSessionEvent`)
-- Assignment tuple (for `Issue.update`)
-
-## Plugin Config Schema
-
-Optional settings in `openclaw.json` under the plugin entry:
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "linear": {
-        "enabled": true,
-        "clientId": "...",
-        "clientSecret": "...",
-        "redirectUri": "...",
-        "accessToken": "...",
-        "defaultAgentId": "...",
-        "enableAudit": true
-      }
-    }
-  }
-}
-```
-
-All fields are optional — environment variables and auth profiles are the preferred configuration method.
-
-## HTTP Routes
-
-| Route | Method | Purpose |
+| Field | Required | Description |
 |---|---|---|
-| `/linear/webhook` | POST | Primary webhook endpoint |
-| `/hooks/linear` | POST | Backward-compatible webhook endpoint |
-| `/linear/oauth/callback` | GET | OAuth authorization callback |
-
-## Agent Tools
+| `label` | Yes | Display name shown on comments in Linear |
+| `mission` | Yes | Role description (injected as context when the agent runs) |
+| `isDefault` | One agent | Handles issue triage and the pipeline |
+| `mentionAliases` | Yes | `@mention` triggers (e.g., `["qa", "tester"]`) |
+| `avatarUrl` | No | Avatar for branded comments |
 
-Agents have access to these Linear tools during execution:
+### CLI
 
-| Tool | Description |
-|---|---|
-| `linear_list_issues` | List issues (with optional team filter) |
-| `linear_create_issue` | Create a new issue |
-| `linear_add_comment` | Add a comment to an issue |
-
-## File Structure
-
-```
-linear/
-├── index.ts              # Entry point, registers routes and provider
-├── openclaw.plugin.json  # Plugin metadata and config schema
-├── package.json          # Package definition (zero runtime deps)
-├── README.md
-└── src/
-    ├── agent.ts          # Agent dispatch via openclaw CLI
-    ├── auth.ts           # OAuth provider registration and token refresh
-    ├── client.ts         # Basic GraphQL client (for agent tools)
-    ├── linear-api.ts     # Full GraphQL API wrapper (LinearAgentApi)
-    ├── oauth-callback.ts # OAuth callback handler
-    ├── pipeline.ts       # 3-stage pipeline (plan -> implement -> audit)
-    ├── tools.ts          # Agent tools (list, create, comment)
-    ├── webhook.ts        # Webhook dispatcher (5 event handlers)
-    └── webhook.test.ts   # Tests (vitest)
+```bash
+openclaw openclaw-linear auth      # Run OAuth authorization
+openclaw openclaw-linear status    # Check connection and token status
 ```
 
 ## Troubleshooting
 
-**Plugin not loading:**
+Quick checks:
+
 ```bash
-openclaw doctor --fix
-openclaw logs | grep -i "linear\|plugin\|error"
+systemctl --user status openclaw-gateway        # Is the gateway running?
+openclaw openclaw-linear status                  # Is the token valid?
+journalctl --user -u openclaw-gateway -f         # Watch live logs
+linearis issues list -l 1                        # Is linearis authenticated?
 ```
 
-**Webhook not receiving events:**
-- Verify both webhooks (workspace + OAuth app) point to the same URL
-- Check that your tunnel/proxy is forwarding to the gateway port
-- Linear requires `200 OK` within 5 seconds — check for gateway latency
+### Common Issues
 
-**Agent sessions not working:**
-- OAuth tokens require `app:assignable` and `app:mentionable` scopes
-- Personal API keys cannot create agent sessions — use OAuth
-- Re-run `openclaw auth linear oauth` to get fresh tokens
-
-**"No defaultAgentId" error:**
-- Set `defaultAgentId` in plugin config, OR
-- Mark one agent as `"isDefault": true` in `agent-profiles.json`
+| Problem | Cause | Fix |
+|---|---|---|
+| Agent says "closing" but doesn't | No issue management tool available | Install `linearis` skill: `npx clawhub install linearis` |
+| `code_run` uses wrong backend | Default/per-agent config mismatch | Check `coding-tools.json` |
+| Claude Code "nested session" error | `CLAUDECODE` env var set | Plugin handles this automatically (unsets the var) |
+| Gateway rejects plugin config keys | Strict validator in `openclaw.json` | Custom config goes in `coding-tools.json`, not `openclaw.json` |
+| Webhook events not arriving | Wrong webhook URL | Both workspace and OAuth app webhooks must point to `/linear/webhook` |
+| OAuth token expired | Tokens expire ~24h | Auto-refreshes via refresh token; restart gateway if stuck |
 
-**Token refresh failures:**
-- Ensure `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` are set
-- Check that the refresh token in `auth-profiles.json` hasn't been revoked
-- Re-run the OAuth flow to get new tokens
+## License
 
-**OAuth callback not working:**
-- Verify the redirect URI in Linear's app settings matches your gateway URL
-- If behind a reverse proxy, ensure `X-Forwarded-Proto` and `Host` headers are forwarded
-- For local dev, the callback defaults to `http://localhost:<gateway-port>/linear/oauth/callback`
+MIT