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

# Linear

> Manage Linear without leaving Mantle — create issues from conversations, automate workflows, and keep channels in sync

Connect your Linear API key and unlock these capabilities: create and link issues from any chat message, keep channels
updated with real-time notifications, give AI agents 31 built-in tools to act across your workspace, and fire tasks
automatically when issues change.

***

## What you unlock

<CardGroup cols={2}>
  <Card title="Issue actions in chat" icon="arrow-pointer">
    Create a Linear issue, link an existing one, or add a comment — directly from any chat message, without switching
    tabs.
  </Card>

  <Card title="Channel notifications" icon="bell">
    Subscribe any channel to a Linear team or project and receive instant notifications when issues are created,
    updated, or commented on.
  </Card>

  <Card title="31 agent tools" icon="wrench">
    Give your AI agent full read/write access to Linear — issues, projects, milestones, teams, documents, comments, and
    more.
  </Card>

  <Card title="Automated triggers" icon="bolt">
    Start an agent task automatically when something changes in Linear — new issue, status change, comment, priority
    update, or assignment.
  </Card>
</CardGroup>

***

## Connect Linear

<Steps>
  <Step title="Open Settings → Integrations">
    In any workspace go to **Settings → Integrations** and select **Linear**.
  </Step>

  <Step title="Get your API key">
    Open [linear.app/settings/api](https://linear.app/settings/api), create a personal API key, and copy it — it starts with `lin_api_`.
  </Step>

  <Step title="Paste and connect">
    Paste the key into the **API Key** field and click **Connect**.

    <img src="https://mintcdn.com/mantlechat/0u3xKFxBtOxmoFe-/images/integrations/linear-settings.png?fit=max&auto=format&n=0u3xKFxBtOxmoFe-&q=85&s=238d60351e267a13ae1b7d4442270bc3" alt="Linear integration settings panel" width="3432" height="2404" data-path="images/integrations/linear-settings.png" />
  </Step>
</Steps>

<Note>
  One API key unlocks agent tools, issue actions in chat, and channel notifications — all three. Triggers require an
  additional one-time event authorization, described below.
</Note>

***

## Issue actions in chat

Once connected, every chat message gets a **More actions** menu (···) with three Linear shortcuts.

### Create an issue from a message

Turn any message into a Linear issue in seconds — no copy-pasting required.

1. Hover over the message and click **More actions (···) → Create Linear issue…**
2. A panel slides in with the title and description pre-filled from the message.
3. Set the team, status, priority, assignee, project, and labels.
4. Click **Create Issue** — the issue is created and you get a confirmation with the link.

### Link an existing issue

Attach a reference to an existing Linear issue so the conversation stays connected to the work.

1. Click **More actions → Link Linear issue…**
2. Search by title or identifier (e.g. `NUL-123`).
3. Select the issue and click **Link Issue**.

Enable **Sync comments** when linking — you'll receive a chat notification whenever a new comment is added to that issue
in Linear.

### Add a comment to an issue

Post the message content directly as a comment on any Linear issue.

1. Click **More actions → Add comment to issue…**
2. Search for and select the target issue.
3. Click **Add Comment** — the message is posted as a comment in Linear.

***

## Channel notifications

Subscribe a channel to a Linear team or project to receive system messages when issues change.

<Steps>
  <Step title="Open the channel menu">
    Right-click any channel in the sidebar and select **Integrations**.
  </Step>

  <Step title="Set up a subscription">
    Choose a Linear team (and optionally a specific project), then pick which events to follow.

    | Event | Default |
    | - | - |
    | Issue created | On |
    | Status changed | On |
    | Comment added | On |
    | Priority changed | Off |
    | Issue assigned | Off |
  </Step>

  <Step title="Start receiving updates">
    Linear delivers a system message to the channel in real time whenever a matching event occurs.
  </Step>
</Steps>

***

## Agent tools

You can enable the available Linear tools on agents that need them. Keep write and delete actions off agents that only
need to read issues.

### Issues

| Tool | Description |
| - | - |
| Get issue | Retrieve detailed information about an issue, including attachments and git branch name |
| List issues | List issues in the workspace. Use `"me"` for your own issues; `"null"` for unassigned |
| Save issue | Create or update an issue. Provide `id` to update; `title` and `team` are required when creating |
| List issue statuses | List available workflow statuses in a team |
| Get issue status | Retrieve a status by name or ID |
| List issue labels | List labels in a workspace or team |
| Create issue label | Create a new issue label |

### Comments

| Tool | Description |
| - | - |
| List comments | List comments on a specific issue |
| Save comment | Create or update a comment. Provide `id` to update; `issueId` and `body` are required when creating |
| Delete comment | Delete a comment from an issue |

### Projects & Milestones

| Tool | Description |
| - | - |
| List projects | List projects in the workspace |
| Get project | Retrieve details of a specific project |
| Save project | Create or update a project. Provide `id` to update; `name` and at least one team are required when creating |
| List project labels | List available project labels |
| List milestones | List all milestones in a project |
| Get milestone | Retrieve a milestone by ID or name |
| Save milestone | Create or update a milestone. Provide `id` to update; `name` is required when creating |

### Documents

| Tool | Description |
| - | - |
| Get document | Retrieve a document by ID or slug |
| List documents | List documents in the workspace |
| Create document | Create a new document |
| Update document | Update an existing document |
| Extract images | Extract and return images embedded in markdown content (issue descriptions, comments, documents) |

### Attachments

| Tool | Description |
| - | - |
| Get attachment | Retrieve an attachment's content by ID |
| Create attachment | Upload content as a new attachment on an issue |
| Delete attachment | Delete an attachment by ID |

### Teams, Users & More

| Tool | Description |
| - | - |
| List teams | List teams in the workspace |
| Get team | Retrieve details of a specific team |
| List users | List users in the workspace |
| Get user | Retrieve details of a specific user |
| List cycles | Retrieve cycles for a specific team |
| Search documentation | Search Linear's own documentation |

***

## Triggers

Triggers start an agent task automatically when something changes in Linear. They require a one-time event authorization
separate from the API key.

<Steps>
  <Step title="Create a task with a Linear trigger">
    Open any agent, go to the **Tasks** tab, and add a new task. In the trigger picker, choose **Integration → Linear**.
  </Step>

  <Step title="Choose which events to watch">
    Pick one or more of the five available events.

    | Event | When it fires |
    | - | - |
    | Issue created | A new issue is created in your workspace |
    | Status changed | An issue moves to a different workflow state |
    | Priority changed | An issue's priority is updated |
    | Issue assigned | An issue is assigned or unassigned |
    | Comment added | A new comment is posted on an issue |
  </Step>

  <Step title="Authorize events">
    The first time you save a Linear trigger task, Mantle asks you to approve the event connection in Linear.
  </Step>
</Steps>

***

## Example use cases

<AccordionGroup>
  <Accordion title="Turn a message into an issue in one click">
    Someone reports a bug in chat. Instead of switching to Linear and re-typing everything, click **More actions → Create Linear issue** — the title and description are already filled in from the message. Add the team and priority, click Create.
  </Accordion>

  <Accordion title="Keep a channel updated on your team's Linear work">
    Subscribe your #engineering channel to a Linear team. Every new issue, status change, and comment shows up as a system message — the whole team stays in sync without anyone having to watch Linear directly.
  </Accordion>

  <Accordion title="Auto-triage new issues with an agent">
    **Trigger:** Issue created

    When a new issue is created, an agent reads the title and description, labels it, sets priority, assigns it to the right person, and posts a triage summary to the team channel.
  </Accordion>

  <Accordion title="Get notified when work moves to review">
    **Trigger:** Status changed

    When an issue moves to "In Review", the agent posts a message in the relevant channel with a summary and a direct link — no manual status updates needed.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="My API key isn't working">
    Make sure the key starts with `lin_api_` and was created at
    [linear.app/settings/api](https://linear.app/settings/api). Personal keys give access to all teams your account
    belongs to. If it still fails, delete the key in Linear, generate a fresh one, and paste it again.
  </Accordion>

  <Accordion title="Create / Link issue options don't appear in the message menu">
    These actions only show for users with a valid Linear API key. Go to **Settings → Integrations → Linear** and
    connect your key.
  </Accordion>

  <Accordion title="I can't see the channel notification panel">
    The notification panel needs a valid Linear API key to fetch your teams and projects. Connect one under **Settings →
    Integrations → Linear** first.
  </Accordion>

  <Accordion title="Trigger tasks aren't firing">
    1. Confirm the task is **active** (green indicator on the Tasks tab). 2. Check that the trigger is set to **Linear**
       with the right events selected. 3. Re-authorize the event connection if Mantle shows that it expired.
  </Accordion>

  <Accordion title="The agent can see issues but can't create them">
    Personal API keys have write access by default. If creation fails, check that your Linear account has permission to
    create issues in the target team.
  </Accordion>
</AccordionGroup>

***

<Card title="Back to Integrations" icon="plug" href="/integrations/overview">
  View all available integrations
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.