Setup
- Go to Organization → Integrations
- Find Linear and click Install
- Authorize Replicas for your Linear workspace
Personal Account Connection
Connect your Linear account from Personal → Connections to link your Linear user ID to your Replicas account. Replicas then uses your personal defaults and credentials even when your Linear email differs from your Replicas email. Email matching remains a fallback for members who have not connected an account. This identity connection is separate from the organization integration used by agents to create and update issues. A disconnected personal account does not mean organization access has been lost.Creating Issues from a Workspace
Ask your workspace agent to create a Linear ticket. All new workspaces keep organization credentials on the server and refresh them through the gateway; a separate Linear MCP server is not required. Usereplicas.linear.graphql() for API calls and replicas.linear.download(url) for protected attachments.
If an agent reports a rejected workspace token, ask it to retry through the gateway. Reconnect under Organization → Integrations only if the gateway reports missing credentials or an unrecoverable authentication failure. Reconnect as well if an agent cannot read initiatives; organizations connected before initiative access was added need to grant it.
Workspaces created before the gateway retain compatibility with their existing tokens, including token refresh. Agents should use the SDK when available. Customer-defined tokens remain separate from the organization integration.
How It Works
When you assign an issue to Replicas or mention it in a comment:- Replicas Agent (an AI orchestrator) analyzes the issue
- If clarification is needed, it asks follow-up questions in a thread
- Once ready, it spawns a workspace with your chosen coding agent
- The agent works autonomously, streaming progress to the thread
- As work progresses, session links (workspace and PRs) appear in the Agent Session panel
- The agent’s final response completes the Linear session
Workspaces that take over an issue
A workspace started another way, such as from Slack, the dashboard, or a Mothership subagent, attaches itself when its agent starts working on a Linear issue. The issue gets a Replicas agent session for that workspace, just like a delegated issue: progress streams into it, and replies there reach the workspace. Agents attach only issues they own, not ones they just read or file.Agent Selection
Replicas uses the triggering user’s agent defaults when their Linear account is connected or its email matches a Replicas user. Admins can also open Linear Configure under Integrations to set Linear-specific defaults before falling back to the organization defaults. Follow-up comments wake sleeping workspaces and keep using the workspace’s selected coding agent and model. Follow-up comments also restore archived workspaces.Environment Selection
If your organization has multiple environments, Replicas uses the same order as Slack: an inline[env:name] tag in the comment, then the personal default of the matching Replicas user, then the organization default, then a pick from the issue context (repo names, file paths, issue title) when confident. Otherwise it prompts in the agent session.
To route tickets automatically instead, an admin can turn on Route Linear tickets in Linear Configure under Integrations. Replicas reads the ticket, your environments, and an optional routing skill (a SKILL.md picked from any connected repository, or uploaded) and instructions, then starts the ticket in an environment or hands it to a Mothership that takes Linear tickets. An [env:name] tag still wins, and when it isn’t sure, you pick from a list in the agent session.
Context
The context provided to the agent are listed below:- Issue title
- Issue description (including images)
- Parent issue content
- Previous comments on the issue
- User message (if triggering using @Replicas in a comment), which scopes what the agent implements; start it with
/planfor a planning-only session
Issue State Automation
Replicas keeps the Linear issue state in sync with what the agent is doing:- In Progress when a workspace is created or the agent re-engages on a new comment.
- In Review when the agent’s turn completes with a PR open.
- Blocked when waiting on human input (env picker), a workspace fails, or a security policy denies the request.
Closing the workspace
When you mark an issue as Done, Canceled, or Duplicate in Linear, Replicas automatically archives the associated workspace. Archived workspaces keep their conversation history and can be explicitly restored.Triage
Replicas can also triage new issues in the Triage state of teams you choose. Ask @Replicas in Slack, such as@Replicas triage new issues in the Mobile team, and give each team a preset or instructions like a Slack channel. Only admins can add a team.
Intended Usage
Replicas works best with concise but direct instructions. Agents can typically crawl and search codebases well, so it is best to only provide a handful of sentences. Describe:- Where to look
- Functionality
- Any considerations
/plan to request a planning-only response with a plan link. See Plan Mode.