Linear

Connecting Linear makes your issue tracker a signal source: new issues, the comments on them and Linear customer requests arrive in nima as evidence, each linked back to the Linear issue it came from. Optionally, nima can also post replies on Linear issues, always after a person approves them.

Connect Linear

Connecting Linear takes a nima owner or admin and one Linear authorization. Members cannot manage integrations.

1. Sign in to the nima admin panel and open Integrations.
2. Open the Linear card and start the connection. nima sends you to Linear's authorization screen.
3. Pick the Linear workspace and authorize.

nima requests the four OAuth scopes below, as the authorizing user (actor=user), so anything nima later writes to Linear appears as that person.

A nima workspace connects one Linear workspace; connecting again replaces the existing connection. Two nima workspaces may connect the same Linear workspace, and each receives its own copy of the events. nima refreshes Linear's 24-hour access tokens on its own. If Linear reports the authorization revoked, the connection is marked as needing attention and you reconnect from the card.

What arrives from Linear

Linear creates become signals; nothing else does. nima ingests only create events of three types: Issue, Comment and CustomerRequest.

Each signal deep-links to the Linear issue, and its source channel reads linear:<workspace>/<team key>. To read the original text again, or to learn whether it changed since ingest, call get_signal_source (owners and admins only). Customer-request signals cannot report a change: their original is the issue, not the request.

What Linear ingestion does not do:

• Edits, status changes, deletes, projects, cycles and reactions are ignored. An edited title is not new evidence.
• No backfill. nima sees events from the moment you connect.
• Every new issue becomes a signal, and each one costs an extraction pass. There is no label or team filter yet. Tell the nima team first if your workspace opens many issues a week.

Replying on Linear through nima

Replying on Linear means nima posts a comment on a Linear issue as the person who connected Linear, and only after a person approves it. This is outbound dispatch; the one tool is reply_on_linear_issue, and its policy is capped at ask: every reply waits for a person to approve it, and it can never be set to run automatically.

To enable it, an owner or admin calls POST /v1/integrations/linear/writer (MCP tool connect_linear_writer) with acknowledged: true; optional enabled: false pauses the writer. The acknowledgement records that replies appear as the connecting person and that every reply waits for approval.

The request and response are documented in Enable the Linear writer and connect_linear_writer. The response never contains a credential; a 404 Linear is not connected means connect Linear first.

• Status: GET /v1/integrations/linear/writer returns the writer status (including enabled: false for a paused writer), or 404 when no Linear writer has been set up.
• Access: owner or admin, either a signed-in session or a key with the integrations:write scope. A default API key does not carry that scope; an admin gets one from Slack with /nima mcp-key integrations, which creates a 30-day key shown once.

Every reply carries a footer naming who nima acts for, and every action is recorded in the audit trail.

Enabling the writer does not yet make nima comment on Linear by itself. No workspace rule or conversation can propose reply_on_linear_issue today, and Linear does not emit ticket events into rules. The adapter is in place for when one does.

Linear limits

• One Linear workspace per nima workspace.
• Only create events for Issue, Comment and CustomerRequest are read; no edits, no status sync, no backfill.
• No label or team filter: every issue is extracted.
• nima writes only comments. It does not create or edit Linear issues or sync status.
• Replies always wait for approval and appear as the connecting person. An app-level identity for replies is not available yet.
• The enable and pause toggle on the card is a label. It does not stop signals from arriving.
• Linear's own rate limits apply.
• nima posts at most one reply per Linear issue every 10 minutes and 20 replies per minute per connected Linear workspace; an approved reply over either limit waits and is sent later. Because every Linear reply waits for approval, a reply body is held to 8,000 characters so the approver can read all of it; a longer body is shortened with a visible marker before it reaches the approval card.
• nima acknowledges webhook deliveries immediately and processes them on a queue. A failed event is tried up to three times with backoff. An authorization failure, or an issue deleted before processing, is dropped without a retry.

Disconnect Linear

Disconnecting Linear removes the connection and revokes nima's tokens at Linear. An owner or admin disconnects from the Linear card in Integrations. The card calls DELETE /v1/integrations/linear, which accepts only a signed-in session, not an API key. nima revokes both the access and refresh token at Linear on a best-effort basis, then deletes the stored installation and the integration state.

Signals already collected stay in nima with their links, but nima can no longer re-fetch the originals. Revoking nima's authorization inside Linear has a similar effect: nima marks the connection as needing attention and drops further deliveries until you reconnect.