Skip to main content
Connect Linear so your team can hand issues to Capy without leaving Linear. Delegating an issue starts a Capy thread, and everything the agent does streams back into the issue as native agent session activity: progress, responses, the plan, and a link to the thread.

​
Connect Linear

1

Install the workspace connection

Go to Settings → Integrations → Linear and click Install. Any org member can connect; one Linear workspace connects to one Capy org.
2

Configure routing

Map Linear teams to Capy projects and set a default project. Changing these settings requires an org admin or owner.
3

Link your Linear identity

Each person links their Linear account to their Capy account once. Capy prompts unlinked users in Linear the first time they delegate; nothing is matched by email or name automatically, so the link is always explicit.

​
How delegation works

Assigning or delegating an issue to the Capy agent creates a native Linear agent session, and that session maps one-to-one to a Capy thread. Later prompts and comments inside the agent session continue the same thread. The session is the boundary: a comment on an ordinary issue with no Capy agent session does nothing. If you want Capy on an issue, delegate it; mentioning or commenting won’t start anything. When a session starts, Capy may move the issue into the team’s first started state and set itself as the assignee when nobody else is assigned. The first prompt carries the issue identifier, title, description, URL, and requester, so the thread starts with real context; later prompts carry only the new comment.

​
Project routing

A new session picks its Capy project deterministically:
  1. The Linear team’s mapping, when one exists.
  2. Otherwise the connection’s default project.
  3. Otherwise a persistent error in Linear pointing at Capy’s connection settings; Capy never guesses a project.
Routing fails closed: a stale mapping, or a mapping the delegating user can’t access, produces a visible configuration error instead of silently landing in a different project. An existing session keeps its project even if mappings change later.

​
Default branches

Set per-repository default branches for Linear-origin threads in the connection settings. A repository without an entry falls back to its project default. These apply only to repositories already attached to the selected project.

​
What Capy posts back

Capy projects thread activity into the agent session as native Linear activity:
  • Short thought and action updates while the agent works.
  • Persistent responses for each message the agent sends you.
  • A persistent error activity when a run fails.
  • A selection prompt when the agent needs a clarifying answer.
  • The agent’s current todo list as the session plan.
  • The Capy thread URL as the session’s external link, so you can jump into the full transcript any time.
Markdown and file attachments are lowered to what Linear supports, with files as attachment links.

​
Stopping a session

Linear’s stop signal interrupts the thread’s current run. It doesn’t archive the thread or break the session mapping; a later prompt in the same session starts a fresh run.

​
Permissions and scope

  • The connection is org-level: one Linear workspace per Capy org, per environment.
  • Any enabled member can install, reconnect, or disconnect the connection; team mappings, the default project, and branch defaults require an admin or owner.
  • Every inbound action re-checks the actor’s identity link and current org membership: leaving the org revokes access immediately, and links don’t grandfather.
  • If Linear revokes the app’s authorization, the connection flips to a reconnect state that preserves your mappings; reconnecting restores everything.

​
Troubleshooting

Expected unless the issue has a Capy agent session. Delegate or assign the issue to the Capy agent first; comments inside that session then reach the thread.
Your Linear account isn’t linked to a Capy account yet. Follow the authentication prompt Capy posts in Linear; it’s a one-time link, and your original prompt is delivered automatically once you complete it.
Check the team mapping for the issue’s team; without one, Capy uses the default project. An already-running session keeps its original project even after you fix the mapping.
The mapped or default project is missing, or you don’t have access to it. Capy deliberately refuses rather than picking another project; fix the mapping or your project access in Capy settings.
Linear revoked or invalidated the authorization. Reinstall from Settings → Integrations → Linear; mappings and identity links survive the reconnect.