Linear

Connect a Linear workspace, sync a team or project into the board, and choose automatic or manual triage.

The Linear integration installs hlix as an agent in your Linear workspace. Assign it an issue or mention it, and it opens an agent session — a conversation in which it reports what it is doing and what it decided, and in which you can send it a message or stop it.

You can also select a team, project and label to receive matching issues automatically, without assigning the agent to each issue.

Prerequisites

Agency owner or admin in the hlix Workspace
Permission to authorize an OAuth application in the target Linear workspace
A Hlix project for the issues you want to work on — see issue context

Connect it

Start the install. From the dashboard’s integrations screen, or directly:

curl -sS -i "$HLIX_BASE_URL/v1/api/integrations/linear/install" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected result: a 302 to Linear’s authorization page.

Authorize in Linear. Hlix requests read, write, app:assignable, and app:mentionable, and appears as an app user you can assign or mention on issues.
Land back on hlix. hlix completes the authorization and saves the installation to your Workspace.

Expected result: a redirect to …/integrations/linear?installed=1.
Verify.
Terminal window
```
curl -sS "$HLIX_BASE_URL/v1/api/integrations/linear" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"
```
Then, in Linear, assign the hlix agent to a test issue. A thought activity — “Received — gathering context…” — should appear in the session within seconds.

Sync issues into a project

Open Workspace → Integrations → Linear and connect the Linear workspace. This account is shared by projects in the hlix Workspace.
Choose a hlix project and open Configure project. Select the Linear team, an optional Linear project, and an optional label. All projects includes issues in the team with no Linear project.
Choose Start automatically to send new matching issues to the project manager for triage, or Start manually to keep them on the board until you select Start.
Save the settings. Sync existing issues separately imports the current matching backlog in the background; saving the settings alone starts watching future arrivals.

The source includes open, non-archived issues. Changing a label or moving an issue into the selected team/project can bring it into scope. A source cannot overlap another hlix project’s source in the same Linear installation; narrow the selected projects to remove the overlap.

Imported issues appear in Cycles → Board → Waiting and in the project’s integration settings. Open an issue to read its description, comments, attachments, parent and sub-issues, labels and project brief. The project manager uses this context to plan cycles and checklist tasks.

Manual arrivals keep their manual policy if you later switch to automatic. Changing or unlinking the source does not delete imported work. Completed, cancelled, archived or out-of-scope issues cannot start new work. Work already handed to the project manager keeps its existing identity, including an earlier Linear delegation.

Settings show the last received event, completed synchronization and any recoverable errors. Existing-issue import runs in the background. Webhooks provide ongoing updates, with an automatic recovery pass every 30 minutes.

Source synchronization is inbound from Linear. Issues delegated to the Linear agent also receive the session activities described below.

What hlix writes back

Hlix posts agent activities in the Linear session:

Activity	Meaning
`thought`	a progress update or acknowledgement
`action`	a concrete step it took, with its parameter and result
`response`	its answer for this turn — a plan summary, a status, or the outcome
`elicitation`	a question for you. With options attached, Linear renders them as choices
`error`	the run failed, with the message

The session’s own status moves alongside: awaitingInput when it needs an answer, complete when the turn is finished, error when it is not. A session stays open only while something is actually going to report back.

What it needs from an issue

hlix resolves each issue to a project and, for projects with several repositories, a repository. If the context is insufficient, the session enters awaitingInput and asks you to choose from the candidates.

Two cases produce that question:

No matching project context. The issue has no signal tying it to a hlix project.
The project has several repositories and the issue needs a repository selected.

Answer in the conversation and the session continues.

Messaging a running session

Prompt it again by replying in the session. The agent reads the prior activity history, so the reply is a continuation rather than a fresh start.
Stop it with Linear’s stop signal. hlix honours it immediately, records the stop, replies “Stopped as requested.”, and closes the session.

Queued work is reported in the session.

Permissions and security

Hlix acts as its own app user, so actions are attributed to Hlix.
Webhook signatures are verified before messages are processed.
Linear access tokens are short-lived, and hlix refreshes them automatically.
Revoking authorization in Linear disconnects the installation in Hlix.

Disconnect

curl -sS -X POST "$HLIX_BASE_URL/v1/api/integrations/linear/$INSTALL_ID/revoke" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

owner or admin only. Also revoke the OAuth application in Linear to remove its access there.

If Linear does not connect

Authorization expired or failed: restart from Integrations → Linear. Contact support if it continues.
Installation shows as revoked: reconnect from the dashboard.
Assigning or mentioning the agent produces no activity: reconnect to grant the required read, app:assignable and app:mentionable scopes.
The conversation asks which project or repository — reply in it to select the target.