---
title: Linear tracker
description: Linear issues. Direct API key or Composio-mediated — AO picks the right transport automatically.
---

<div style={{ display: "flex", alignItems: "center", gap: "0.75rem", margin: "0.5rem 0 1.25rem" }}>
  <Logo name="linear" size={28} color />
  <span style={{ fontSize: "0.8125rem", color: "var(--color-fd-muted-foreground)" }}>Slot: <code>tracker</code> · Name: <code>linear</code></span>
</div>

<PlatformSupport macos="full" linux="full" windows="full" />

The Linear tracker supports two transports and auto-picks between them:

- **Composio-mediated** — when `COMPOSIO_API_KEY` is set. Takes priority.
- **Direct API** — when `LINEAR_API_KEY` is set.

## Setup

### Direct Linear API

1. [Create a personal API key](https://linear.app/settings/api) in Linear.
2. Export it:
   ```bash
   export LINEAR_API_KEY=lin_api_...
   ```
3. Configure AO:
   ```yaml
   tracker: linear
   projects:
     api:
       tracker: linear
       trackerConfig:
         teamId: TEAM-123          # required for issue creation
         workspaceSlug: myteam     # optional, used to build issue URLs
   ```

### Composio-mediated

If you already use the [Composio toolkit](https://composio.dev):

```bash
export COMPOSIO_API_KEY=...
export COMPOSIO_ENTITY_ID=...      # optional; defaults to "default"
```

AO detects this and routes Linear calls through Composio — no separate Linear token needed. `COMPOSIO_ENTITY_ID` is optional; if omitted it defaults to `"default"`.

## Per-project config

| Key | Required | What it does |
|---|---|---|
| `teamId` | ✓ (for `createIssue`) | Linear team the issue lives in |
| `workspaceSlug` | optional | Used to render `https://linear.app/{slug}/issue/{id}` URLs |

## Branch names

Linear issues expose a `branchName` field — the string shown in the **Copy git branch name** button in the Linear UI (formatted according to your workspace settings in **Settings → Integrations → GitHub → Branch format**).

When AO spawns an agent for a Linear issue it:

1. Reads the issue's `branchName` field from the Linear API (if present and git-safe).
2. Falls back to `feat/<issue-id>` if `branchName` is absent or contains characters that aren't valid in a branch name.

You can customise the format globally via Linear's branch format settings — AO will pick up whatever Linear generates automatically.

## Issue identifiers

Linear uses `TEAM-42`-style identifiers, not numbers. `ao spawn TEAM-42` works as you'd expect.