# Linear

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

Ren works as a [Linear agent](https://linear.app/docs/agents-in-linear). Assign it an issue or mention it in a comment, and it posts its progress and answer on the issue.

## Install Ren in Linear

Connect Linear once for your organization. You need:

- **A Ren organization admin** to start the install.
- **A Linear workspace admin** to approve it. Linear only lets workspace admins install agents.

<SurfaceTabs>
<Fragment slot="app">

1. Go to **Settings → Mentions**.
2. In the **Task management** section, select **Install Ren on Linear**.
3. Approve the install in Linear.

<Screenshot shot="channels/linear/install" alt="Settings Mentions with the Linear row showing Connected" />

</Fragment>
<Fragment slot="cli">

```sh
ren linear install
```

Open the Linear authorization URL it prints and approve the install.

</Fragment>
</SurfaceTabs>

Once installed, Ren appears in Linear's assignee and mention menus. The app manages one Linear workspace per organization.

## When to use Linear

Use Linear when the request is already an issue. Ren posts progress and responses there, so the team can follow the work.

## How a Linear issue maps to Ren

Each assignment or mention starts a Linear agent session. Each session creates a Ren [chat](/docs/concepts/chats/) in the mapped project, and replies within that session continue it.

Ren doesn't create a Ren [task](/docs/concepts/tasks/) for the issue. If an open Ren task already links the issue and is assigned to a project, the agent session goes to that task's chat instead.

## Map Linear projects to Ren projects

Each Linear project maps to one Ren project, and a Ren project can accept several Linear projects. Each mapping needs a **fallback sender**, the account Ren uses when the sender has no matching Ren account or doesn't belong to the project's space.

<SurfaceTabs>
<Fragment slot="app">

1. Open the project's **@Ren** tab.
2. On the **Linear** card, pick a Linear project.
3. Pick a fallback sender. The mapping isn't saved until you do.

You can also open **Settings → Mentions → Linear**, select a Ren project and a Linear project, choose a **Session sender**, and select **Route here**. Use **All issues (no project)** for issues outside a Linear project.

<Screenshot
  shot="channels/linear/map-project"
  frame="detail"
  alt="The Linear integration dialog with a Linear project selected and the session sender list open"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Map the Mobile Linear project to this project, with me as the session sender." />

Mapping needs an organization admin, so ask from an admin account.

</Fragment>
<Fragment slot="cli">

```sh
ren linear projects
ren linear mappings create --ren-project-id <project-id> --linear-project-id <linear-project-id> --sender-user-id <user-id>
```

</Fragment>
</SurfaceTabs>

## Assign an issue to Ren

Assign the issue to Ren in Linear. Ren starts an agent session, posts "Working on it…", and then posts its response on the issue. Ren reads the issue as its prompt.

## Mention Ren in a comment

Mention Ren in a comment on an issue in a mapped Linear project. The comment is Ren's prompt:

```text
@Ren check whether this crash also happens on Android 14 and suggest a fix.
```

A mention with no other text asks Ren to review the issue and offer help.

## FAQ

<details>
<summary>Who can hand work to Ren in Linear?</summary>

Anyone in the Linear workspace who can assign issues or comment can send requests. Ren matches senders by their Linear account email. If no account matches, or the sender is outside the project's space, Ren uses the mapping's fallback sender.

</details>

<details>
<summary>What happens in a Linear project that isn't mapped?</summary>

Ren posts on the issue that no Ren project is mapped to it and doesn't start a chat. Map the Linear project, or map **All issues (no project)** for issues outside any Linear project.

</details>

<details>
<summary>What happens when Ren needs permission?</summary>

Linear chats deny actions that need approval and continue without them. Configure [project permissions](/docs/concepts/projects/#permissions) before sending requests.

</details>