Skip to main content
Connect Yellowhammer to your Linear workspace, choose the human who receives questions, and select the Linear project that will hold the 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 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 · Troubleshoot setup and connections