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

# Linear Automation (Auto-Pickup)

> Configure Genesis to automatically claim Linear issues delegated to an agent, start a stable orchestrator thread, and keep the Linear lifecycle synchronized through review or clarification.

## Overview

This page is the **second step** in the Linear setup flow:

1. [Linear](/docs/Setup/Linear) — save a shared API-key connection.
2. **Linear Automation (Auto-Pickup)** — *this page* — have Genesis automatically claim matching Linear issues and dispatch coding work.
3. [Linear Connector Tools](/docs/Genbot-Toolkit/Linear-Connector-Tools) — for ad-hoc, manual Linear operations from inside an agent thread.

Genesis polls Linear for issues delegated to the configured **Linear delegate name or ID** (default `Eve`) across all accessible teams, regardless of their current state. When a match is found, Genesis transitions the issue to the **working state** before dispatch so two workers cannot claim the same ticket, opens or resumes a stable orchestrator thread, and keeps the Linear workflow aligned through **review** and **needs info** states.

<Note>
  All Linear automation controls are admin-scoped. You need Genesis admin access or `manage_all_connections` to see the **Automation** tab in the Linear connection modal on **Config -> Connections**. Open **+ New Connection**, choose **Linear** under **Dev Tools**, or edit an existing Linear connection to switch tabs.
</Note>

<Warning>
  Linear automation requires a **shared** `api_key` connection. Personal connections and `user_oauth` connections are not supported for automation — the poller runs as a system principal and must continue work without the setup user's OAuth session. The Automation tab lists only shared connections; a previously saved personal connection appears as unsupported.
</Warning>

## Prerequisites

Before configuring automation, make sure all of the following are true:

1. A **shared** Linear `api_key` connection has been saved in Genesis. See [Linear](/docs/Setup/Linear).
2. Your Linear teams use workflow states that match the lifecycle mapping you plan to configure (defaults: `Agent-Working`, `HumanReview`, `Clarify`).
3. You have decided which Linear delegate name or ID should identify issues for pickup. The default is `Eve`.
4. The selected coding backend is enabled and supports concurrent runs. Cursor's local single-worktree adapter cannot safely run concurrent ticket claims, so the poller stays gated for that adapter. You can save intended settings before the gate opens; polling starts once a capable backend is active.

## How pickup works

On each poll Genesis:

1. Lists issues assigned to the configured **Linear delegate name or ID** across all accessible teams, regardless of status.
2. For each candidate, transitions the issue to **State on pickup** before dispatch so concurrent pollers cannot double-claim.
3. Opens or resumes a stable thread (`linear-<connection>-<issue-key>`) for the configured **Genesis orchestrator**.
4. Dispatches a kickoff or resume prompt into that thread.
5. Records every claim, dispatch, duplicate suppression, and provider status change in the Genesis observation ledger (visible on [Requests](/docs/User-Guide/Work-Center) when enabled).

Genesis resolves the delegate by name or ID and applies the configured state names in each issue's team. Removing the delegate stops the attempt on the next poll.

## Setup workflow

<Steps>
  <Step title="Save a shared Linear connection">
    In **Config -> Connections**, create or edit a Linear connection with **Connection scope** set to **Shared connection** and auth mode **API Key**. Test and save. See [Linear](/docs/Setup/Linear).
  </Step>

  <Step title="Configure automation rules">
    Open the Linear connection modal, select the **Automation** tab, and set:

    * **Enable Linear automation**: on.
    * **Linear connection**: the shared connection (for example `linear.shared`).
    * **Linear delegate name or ID**: the delegate whose assigned issues Genesis should handle across all teams (default `Eve`).
    * **Genesis orchestrator**: usually `Eve`.
    * **Poll interval (seconds)**: between `30` and `3600` (default `60`).
    * **Lifecycle mapping**: working, review, and needs-info state names.

    Save automation settings.
  </Step>

  <Step title="Verify the runtime gate">
    When the selected coding backend is disabled or cannot run concurrent tickets, the panel shows **Automation runtime is gated** with the reason. Settings can be saved; **Poll now** stays disabled until polling is allowed. Enable a capable backend, then use **Poll now** or wait for the next interval.
  </Step>

  <Step title="Verify end-to-end">
    Assign a test issue to the configured delegate in Linear. Within one poll interval, Genesis should claim it, transition it to the working state, and start orchestrator work in the linked thread.
  </Step>
</Steps>

## Automation parameter reference

These fields are saved on the **Automation** tab.

| **Field** | **Type** | **Default** | **Notes** |
| - | - | - | - |
| **`enabled`** | Boolean | `false` | Master switch. When off, Genesis ignores delegated issues. |
| **`connection_name`** | String | empty | Saved connection id such as `linear.shared`. Must reference a **shared** `api_key` connection. |
| **`agent_identity`** | String | `Eve` | Linear delegate name or ID. Assigned issues are handled across all accessible teams, regardless of status. |
| **`orchestrator_bot_id`** | String | `Eve` | Genesis bot that receives the kickoff or resume prompt. |
| **`poll_interval_seconds`** | Integer | `60` | Polling cadence. Minimum `30`, maximum `3600`. |
| **`working_state`** | String | `Agent-Working` | State applied on claim, before dispatch. |
| **`review_state`** | String | `HumanReview` | State used when work is ready for human review. |
| **`needs_info_state`** | String | `Clarify` | State used when the agent needs input. |

Read-only telemetry returned by `GET /api/config/linear/automation`:

| **Field** | **Meaning** |
| - | - |
| **`feature_enabled`** | Whether the selected coding backend is enabled and its concurrent-run capability allows polling. |
| **`gating_reason`** | Human-readable explanation when `feature_enabled` is `false`. |
| **`last_poll_started_at`** | Start time of the most recent poll attempt. |
| **`last_successful_poll_at`** | Start time of the most recent successful poll. |
| **`last_poll_error`** | Last poll error message, or empty when the most recent run succeeded. |

## Troubleshooting

### Automation saves but never claims issues

1. **Enable Linear automation** is on and a shared connection is selected.
2. The issue's state exactly matches **Trigger state** in the configured team scope.
3. **`feature_enabled`** is `true` (the selected coding backend is enabled and supports concurrent runs). The UI blocks **Poll now** while gated.
4. The shared API key can read and transition issues in the target team.

### Personal connection appears in the dropdown

Automation requires a shared connection. Create or migrate to a shared `api_key` connection and re-select it on the Automation tab. Personal selections are shown as unsupported and cannot be saved while automation is enabled.

### Two workers claimed the same issue

Genesis transitions to **State on pickup** before dispatch specifically to prevent this. If it still happens, verify only one Genesis deployment polls the same Linear workspace and that state names are unique within the team workflow.

## Observing automation activity

See [Requests](/docs/User-Guide/Work-Center) for Linear issue activity.

The **Automation** tab in the Linear connection modal includes a **View requests →** link to the Requests page.

## Related pages

* [Linear](/docs/Setup/Linear)
* [Linear Connector Tools](/docs/Genbot-Toolkit/Linear-Connector-Tools)
* [Connections](/docs/Setup/Connections)
* [Requests](/docs/User-Guide/Work-Center)
* [Coding Agent Controls](/docs/User-Guide/Coding-Agent-Controls)