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

# Connect Linear

> Understand the Linear connection and Project board used by Yellowhammer.

Connect Yellowhammer to your Linear workspace, choose the human who receives questions, and select the Linear project that will hold the [Project](https://yellowhammer.dev/docs/reference/statuses-and-glossary.md#project)'s Features and Work Cards.

## Before you begin

Identify the intended workspace and team. A workspace admin must approve the Yellowhammer app. If you are not an admin, use the remote approval option. Complete [agent setup](https://yellowhammer.dev/docs/setup/connect-orca-and-agent-clis.md) first if the Add Project steps are locked by **Before You Start**.

## Connect the workspace

1. Open **Settings → Boards**. If a workspace is already connected, choose **Connect a Linear Workspace…** to add another; otherwise the connection form is already visible. You can also connect from the **Board** step while adding a Project.
2. Optionally enter a **Local name**. This name identifies the workspace on this Mac and cannot be changed later. Leave it empty to use the workspace's URL key.
3. Choose **Install Here as a Workspace Admin…** to approve in the browser on this Mac. Alternatively, choose **Request Approval from an Admin…**, use **Copy Link**, and send that approval link to a workspace admin.
4. Wait for the installed state. It identifies the workspace where Yellowhammer was installed. A workspace connected in the wizard remains connected if you cancel adding the Project.

## Choose your Operator identity

In the wizard, select the connected workspace. If it has no Operator identity yet, choose your human account under **You in Linear**. The choice saves immediately and applies to every Project using this workspace connection.

When work needs your decision, Yellowhammer moves the issue to **Waiting on You** and assigns it to this user. Changing the identity later does not reassign issues already waiting on you.

## Select the Linear project

In the wizard's **Board** step, choose one of these options:

* **Existing Linear project:** select a listed project, or paste its ID from Linear's URL or settings and choose **Verify**. Check the displayed name and teams. A successful result says Yellowhammer can read it.
* **New Linear project:** select the team where Yellowhammer should create a project named after your Yellowhammer Project.

Planned screenshot

**Linear connection and Project board**

Show the verified connection state and how the chosen Linear project scopes a Yellowhammer Project.

Planned screenshot: current app connection state with workspace and Project context visible.

**Screenshot instructions:** Use an illustrative Acme Checkout Project in the Add Project sheet. Open **Board**, select an installed workspace and **Existing Linear project**, then select or verify the intended Linear project. Capture the workspace selection, project name/team, and successful read confirmation together. Use a sample workspace and omit approval links or personal member details.

## Confirm it worked

The installation reports the intended workspace. Your Operator identity is selected, and the existing project verification names the expected project and team, or the new-project option names the intended team.

## Common problems

* **The project does not exist in this workspace:** check both the workspace selection and the pasted project ID, then verify again.
* **Yellowhammer cannot access the team:** ask a team admin to add Yellowhammer in the team's settings, then verify again.
* **Remote approval expired or was rejected:** choose **New link**, or **Install here instead** if an admin can sign in on this Mac.
* **The local approval ports are busy:** use the displayed port information to resolve the conflict, then choose **Retry**.

## Jira

**TBD — not yet implemented.** Jira choices in the wizard are disabled.

## Next steps

[Connect GitHub](https://yellowhammer.dev/docs/setup/connect-github.md) · [Troubleshoot setup and connections](https://yellowhammer.dev/docs/reference/troubleshoot-setup-and-connections.md)


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