Skip to Content
SimulatorsLinearOverview

Simulators

Linear simulator

linear-twin is a local, stateful simulator of Linear’s GraphQL API for agents that work in a workspace. Issues, comments, labels, relations, projects with milestones and status updates, documents and attachments share one POST /graphql endpoint. It behaves as Linear does unless a Differs from Linear line says otherwise, and “unconfirmed” marks behavior not yet checked against Linear. It never calls Linear and sends no email, so no test issue lands in a real workspace. It also serves webhooks, and delivers them only when you turn delivery on.

Quickstart

Install the CLI, sign in and boot the simulator with RYSTIC_URL pointing at it.

On Free or Pro you sign in with an API key from your account .

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…   # your API key
export RYSTIC_URL=$(rystic run linear-twin -d --port 0 --scenario linear_sprint_board --json | jq -r .data.url)
curl -s "$RYSTIC_URL/_rystic/version"
# -> {..."product":"linear-twin"...}

On Enterprise, the licensed edition signs in with a license file in place of the key: rystic login ./rystic-license.json (licensing ).

First calls

Read the first issue on the default scenario’s board, file a new one in the Todo state and read it back:

curl -s "$RYSTIC_URL/graphql" -H 'Authorization: lin_placeholder' -H 'Content-Type: application/json' \
  -d '{"query":"{ issues(first: 1) { nodes { identifier title state { name } assignee { name } } } }"}' | jq -c '.data.issues.nodes[0]'
# -> {"identifier":"ENG-106","title":"Upgrade pg driver to 8.13","state":{"name":"Done"},"assignee":{"name":"Yuki Sato"}}
curl -s "$RYSTIC_URL/graphql" -H 'Authorization: lin_placeholder' -H 'Content-Type: application/json' \
  -d '{"query":"mutation { issueCreate(input: {teamId: \"5b0a4d00-7ea0-4a00-8b00-000000000001\", stateId: \"5b0a4d00-57a7-4a00-8b00-000000000002\", title: \"First issue\"}) { success issue { id identifier title } } }"}' | jq -c '.data.issueCreate'
# -> {"success":true,"issue":{"id":"554dd3a1-3e25-42f1-8000-000000000001","identifier":"ENG-1","title":"First issue"}}
curl -s "$RYSTIC_URL/graphql" -H 'Authorization: lin_placeholder' -H 'Content-Type: application/json' \
  -d '{"query":"{ issue(id: \"ENG-1\") { identifier title state { name } } }"}' | jq -c '.data.issue'
# -> {"identifier":"ENG-1","title":"First issue","state":{"name":"Todo"}}

Connect your client

Set @linear/sdk’s apiUrl to $RYSTIC_URL/graphql and use any placeholder key:

import { LinearClient } from "@linear/sdk";

const linear = new LinearClient({
  apiKey: "lin_placeholder",
  apiUrl: `${process.env.RYSTIC_URL}/graphql`,
});
const me = await linear.viewer;

Any other GraphQL client works the same way: POST a JSON body of query, variables and optionally operationName to $RYSTIC_URL/graphql. The simulator serves POST only, so a GET returns the simulator’s own 404. Linear’s hosted MCP server at mcp.linear.app can’t be pointed at a simulator, so drive the simulator with the SDK or plain GraphQL.

No client has been checked against this simulator yet.

Auth

The simulator accepts any non-empty Authorization value, so send any placeholder. Send a personal API key bare, as Linear takes it, or an OAuth token as Bearer <token>. A personal key sent under Bearer, one starting lin_api_, is refused with Linear’s 400 INPUT_ERROR “It looks like you’re trying to use an API key as a Bearer token.”

A token the simulator issued to an OAuth application is refused with Linear’s 401 once it expires or is revoked; see OAuth applications.

Differs from Linear: any other non-empty value is accepted, so the simulator can’t exercise the branch of your code that handles a wrong personal key.

A request with no Authorization header, or an empty or blank one, is refused with 401 and an AUTHENTICATION_ERROR error before any field resolves, so a refused mutation writes nothing:

{"errors":[{"extensions":{"code":"AUTHENTICATION_ERROR","statusCode":401,"type":"authentication error","userError":true,"userPresentableMessage":"You need to authenticate to access this operation."},"message":"Authentication required, not authenticated"}]}

Differs from Linear: Linear’s 401 for a missing header also carries extensions.http and extensions.meta, which the simulator leaves out.

Refusing an empty or blank header with the same 401 is unconfirmed.

viewer is the person a scenario seeds under the key member. A key acts as member unless the boot file’s credentials bind it to someone else. linear_sprint_board binds four keys:

KeyActs as
lin_api_hanaHana Lindqvist
lin_api_tomasTomas Reyes
lin_api_yukiYuki Sato
lin_api_deploybotDeploy Bot
any other keyMira Okafor, the scenario’s member

A binding matches only the key sent bare; another value under Bearer acts as Mira Okafor. With no scenario loaded, viewer returns a placeholder user with an empty name.

API version

Linear’s GraphQL API takes no version in the request, and the simulator serves one schema: Linear’s published schema cut to the operations Coverage lists. It adds no version header to a response and ignores any version header you send.

Querying an operation or field outside that cut, such as administrableTeams, returns 400 GRAPHQL_VALIDATION_FAILED with Cannot query field "…" on type "Query".

Differs from Linear: a field Linear serves but the simulator doesn’t gets the error Linear gives a field that doesn’t exist.

Errors and limits

Error format

A refused request returns a GraphQL errors list, each error having message and extensions with its code. The other fields and the status depend on the refusal:

The requestStatusEach error has
can’t be parsed or validated400, no datamessage, locations and extensions with code (such as GRAPHQL_PARSE_FAILED or GRAPHQL_VALIDATION_FAILED), type, userError and http
passes a filter the simulator doesn’t read200, data nullmessage, locations and extensions with code GRAPHQL_VALIDATION_FAILED, type, userError and http with status 400 (Filters)
names a record that doesn’t exist200, data nullmessage (Entity not found: Issue), locations, path, and extensions with code INPUT_ERROR, statusCode, type, userError and userPresentableMessage
passes an argument out of range, such as first: -1200, data nullmessage (Argument Validation Error), locations, path, and extensions with code INVALID_INPUT, type, userError, userPresentableMessage and validationErrors
costs more than 10,000 complexity points400, no datamessage (Query too complex) and extensions with code INPUT_ERROR, http, statusCode, type, userError and userPresentableMessage
runs past a rate-limit budget429, no datamessage (Rate limit exceeded) and extensions with code RATELIMITED

Some invalid inputs are accepted where Linear refuses them; Limitations lists them under Known issues.

Rate limits

The simulator enforces two hourly budgets and returns 429 RATELIMITED with Retry-After once either runs out:

BudgetSizeResponse headers
requests2,500 an hourx-ratelimit-requests-limit, x-ratelimit-requests-remaining, x-ratelimit-requests-reset
query complexity3,000,000 points an hourx-complexity, x-ratelimit-complexity-limit, x-ratelimit-complexity-remaining, x-ratelimit-complexity-reset

Both refill on wall time, not the simulator’s clock, and POST /_rystic/reset fills them again.

Every key and OAuth token shares the two budgets, a known issue (Limitations). Network profiles send a 429 you shape when a test needs one sooner.

Pagination

Every list is a Relay connection, paged with first and after or last and before, as on Linear. issues, documents and projects return 50 when you pass neither first nor last. Every other list returns all its rows, nested lists such as team.issues included.

Page sizes that differ from Linear’s are a known issue (Limitations).

A cursor is a position in a list, not a record. A cursor from one list works on another, and a well-formed cursor past the end returns empty nodes. Only text that doesn’t decode as a cursor returns INVALID_INPUT. What Linear returns for a cursor it didn’t issue is unconfirmed.

Idempotency

Not applicable: POST /graphql reads no idempotency key. issueCreate takes your own id in its input and files the issue under it. Sending that id again is a known gap (Limitations).

Coverage

Out of scope: workspace administration (creating teams, inviting users, workflow and cycle settings), integrations, creating and managing OAuth applications, billing, initiatives and subscriptions. Teams, users, workflow states, cycles and the organization are read-only: they have what a scenario or your seed put there.

4 routes, counted from the simulator’s route table.

Show all operations

GraphQL fields are served at POST /graphql.

ResourceOperations
Attachment (6)Mutation.attachmentCreate; Mutation.attachmentDelete; Mutation.attachmentLinkURL; Query.attachment; Query.attachments; Query.attachmentsForURL
Comment (5)Mutation.commentCreate; Mutation.commentDelete; Mutation.commentUpdate; Query.comment; Query.comments
Cycle (2)Query.cycle; Query.cycles
Document (6)Mutation.documentCreate; Mutation.documentDelete; Mutation.documentUpdate; Query.document; Query.documents; Query.searchDocuments
Issue (8)Mutation.issueArchive; Mutation.issueCreate; Mutation.issueDelete; Mutation.issueUnarchive; Mutation.issueUpdate; Query.issue; Query.issues; Query.searchIssues
Issue Label (4)Mutation.issueLabelCreate; Mutation.issueLabelDelete; Query.issueLabel; Query.issueLabels
Issue Relation (4)Mutation.issueRelationCreate; Mutation.issueRelationDelete; Query.issueRelation; Query.issueRelations
Organization (workspace) (1)Query.organization
Project (6)Mutation.projectCreate; Mutation.projectDelete; Mutation.projectUpdate; Query.project; Query.projects; Query.searchProjects
Project Milestone (5)Mutation.projectMilestoneCreate; Mutation.projectMilestoneDelete; Mutation.projectMilestoneUpdate; Query.projectMilestone; Query.projectMilestones
Project Update (status post) (4)Mutation.projectUpdateArchive; Mutation.projectUpdateCreate; Query.projectUpdate; Query.projectUpdates
Team (2)Query.team; Query.teams
User (3)Query.user; Query.users; Query.viewer
Webhook (5)Mutation.webhookCreate; Mutation.webhookDelete; Mutation.webhookUpdate; Query.webhook; Query.webhooks
Workflow State (2)Query.workflowState; Query.workflowStates

Also served, outside the model: GET /oauth/authorize, POST /oauth/revoke, POST /oauth/token.

Feed effects. Each operation below can put an effect event on the event feed (/_rystic/events) for each event type beside it, when what the call does produces that event. Any other call puts only its request event there.

OperationEvent types
Mutation.commentCreateComment
Mutation.commentDeleteComment
Mutation.commentUpdateComment
Mutation.issueArchiveIssue
Mutation.issueCreateIssue
Mutation.issueDeleteIssue
Mutation.issueLabelCreateIssueLabel
Mutation.issueLabelDeleteIssueLabel
Mutation.issueUnarchiveIssue
Mutation.issueUpdateIssue
Mutation.projectCreateProject
Mutation.projectDeleteProject
Mutation.projectUpdateProject

Scenarios

The simulator ships 5 scenarios; the quickstart boots linear_sprint_board.

ScenarioWhat it is forWhat it seedsClock
linear_archive_vaultA workspace of archived and trashed records, for soft-delete reads and restorescomment 1, document 2, issue 3, organization 1, project 1, project_update 1, team 1, user 2, workflow_state 22026-02-10T00:00:00Z
linear_roadmap_quarterA planning workspace with no issues, for roadmap readsdocument 2, organization 1, project 3, project_milestone 6, project_update 4, team 2, user 42026-03-02T00:00:00Z
linear_solo_workspaceA new workspace with nothing in it yet, for a client’s first writeorganization 1, team 1, user 1, workflow_state 42026-01-06T00:00:00Z
linear_sprint_board (default)One engineering team on the day cycle 7 closes, for board, cycle and issue readsattachment 2, comment 3, cycle 2, issue 8, issue_label 3, issue_relation 2, organization 1, team 1, user 6, workflow_state 62026-02-02T00:00:00Z
linear_triage_inboxA support team’s untriaged queue, for assignment and prioritization writesattachment 5, comment 2, issue 5, issue_label 2, issue_relation 1, organization 1, team 1, user 2, workflow_state 32026-01-20T00:00:00Z

What each scenario holds:

  • linear_archive_vault:
    • An archived issue.
    • A trashed issue.
    • A trashed project with an archived update.
    • An archived document.
    • A trashed document.
    • A deactivated member.
  • linear_roadmap_quarter:
    • Three projects across two teams.
    • Six milestones covering every status.
    • Four project updates covering every health value.
    • Two project documents.
  • linear_solo_workspace:
    • One admin who is also the caller.
    • One team.
    • Four workflow states.
  • linear_sprint_board:
    • Eight issues over six workflow states.
    • Three labels.
    • Two issue relations.
    • A threaded comment.
    • Two integration attachments.
  • linear_triage_inbox:
    • Five issues in a triage state, with no assignee or priority.
    • Five intake attachments, one on each issue.

Boot one by name, or load one into a running simulator:

rystic run linear-twin -d --port 0 --scenario linear_sprint_board
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"linear_sprint_board"}'

What the scenarios do not hold

  • No label or cycle on any issue, though linear_sprint_board has three labels and two cycles.

  • No live issue with a null archivedAt.

    Differs from Linear: a seeded live issue reads "" for archivedAt, where Linear returns null.

  • No team and no person on an empty boot, so issueCreate returns Entity not found: Team until you seed a team or load a scenario.

The sprint board’s timeline

linear_sprint_board plays four hours of work after its pinned clock. Each step is a POST /graphql call made with one of the scenario’s lin_api_* keys (Auth):

AfterWhoWhat happens
30 minutesHanareplies on ENG-103
1 hourHanamoves ENG-103 to Done
2 hoursDeploy Botattaches a production deploy to ENG-103
3 hoursTomasstarts ENG-102
4 hoursYukifiles a Backlog follow-up, ENG-1, or the next number if you filed one first

The clock is manual on a scenario boot, so nothing happens until you move it. POST /_rystic/clock with {"advance_seconds": 14400} plays all of it, and rystic run linear-twin --scenario linear_sprint_board --speed 1 plays it in real time.

Seeding state

Each resource is one register, and each record is keyed by its id (an OAuth code by its code):

RecordsRegisters
Workspacestate_organization, state_team, state_user, state_workflow_state, state_cycle
Issuesstate_issue, state_comment, state_issue_label, state_issue_relation, state_attachment
Projects and documentsstate_project, state_project_milestone, state_project_update, state_document
Webhooks and OAuthstate_webhook, state_oauth_application, state_oauth_code, state_oauth_token

Records keep Linear’s field names, and Registers lists each register’s fields. Seed a team, a person and a workflow state into a reset simulator, then file an issue in them:

curl -s -X POST "$RYSTIC_URL/_rystic/reset"
curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d '{"state_team": {"team-web": {"id": "team-web", "key": "WEB", "name": "Web Platform"}}, "state_user": {"member": {"id": "user-ada", "name": "Ada Park", "email": "ada@example.test", "active": true}}, "state_workflow_state": {"state-todo": {"id": "state-todo", "name": "Todo", "type": "unstarted", "teamId": "team-web", "position": 1}}}'
curl -s "$RYSTIC_URL/graphql" -H 'Authorization: lin_placeholder' -H 'Content-Type: application/json' \
  -d '{"query":"mutation { issueCreate(input: {teamId: \"team-web\", stateId: \"state-todo\", title: \"Seeded\"}) { issue { identifier title } } }"}' | jq -c '.data.issueCreate.issue'
# -> {"identifier":"WEB-1","title":"Seeded"}
curl -s "$RYSTIC_URL/graphql" -H 'Authorization: lin_placeholder' -H 'Content-Type: application/json' \
  -d '{"query":"{ viewer { id name } }"}' | jq -c '.data.viewer'
# -> {"id":"user-ada","name":"Ada Park"}

Key the person your client acts as member in state_user, and give the record its own id: viewer returns that record. A boot file’s credentials bind a key to a seeded person by id, as linear_sprint_board binds its four keys (Auth). Seeding covers how a seed lands and what it refuses.

Features

Each feature has its own page:

  • Filters: The filter argument on issues, users and workflow states: comparators and connectives, plus one hop into related records on issues and workflow states.
  • GraphiQL explorer: GraphiQL in your browser over the schema the simulator serves, with each query run against the simulator.
  • OAuth applications: OAuth2 sign-in for a seeded application: consent, the authorization_code, refresh_token and client_credentials grants, 24-hour expiry on the simulator clock, refresh replay for 30 minutes and revocation.
  • Webhooks: Webhook subscriptions through webhookCreate and its siblings; Linear’s data change events on the egress log; signed delivery with retries and disabling.

Determinism and reset

New ids are UUID-shaped counters, each family in its own range: 554dd3a1-3e25-42f1-8000-000000000001 is the first issue you file and 925e28d1-dad3-4fd4-8000-000000000001 the first comment. Issue numbers count per team. Every write and each read of viewer or organization moves the clock one millisecond. Four deletes leave it where it is: attachmentDelete, webhookDelete, issueRelationDelete and projectMilestoneDelete. Reset and determinism covers reset, the clock and the RNG.

Limitations

Known issues.

  • A parentId given as an identifier is dropped by issueUpdate, so the issue reads back no parent, though issueCreate takes either form. Selecting Project.status, Team.visibility or a user’s organization fails the whole response with Cannot return null for non-nullable field, so leave them out of a selection.
  • An issue filed without a stateId has no workflow state, so selecting its state fails the response. A priority above 4, an empty title and a second label with an existing name are accepted where Linear refuses them.
  • An input field Linear does not define, or a projectCreate without teamIds, is accepted where Linear returns 400.
  • issues(first:) lists oldest first where Linear lists newest first. Every list accepts first: 251 where Linear caps a page at 250. Given no first or last, every list but issues, documents and projects returns all its rows where Linear returns 50.
  • An issueCreate repeating a client-supplied id overwrites the existing issue where Linear refuses it.
  • An issue’s attachments field returns an empty list; query attachments or attachmentsForURL on their own.
  • Every API key and OAuth token shares one request budget and one complexity budget, at the API-key sizes. Linear counts each user separately and gives an OAuth app 5,000 requests and 2,000,000 points an hour.

Beyond the known issues, 575 of the 638 operations in the published spec are not served, 10 GraphQL types may leave out non-null fields, 19 documented responses have no test yet and 224 behaviors are not modeled. The details follow.

Show all limitations

Not served. 575 of the 638 operations in the published spec are not served.

  • Mutation, 29 of 380 served: Mutation.agentActivityCreate, Mutation.agentActivityCreatePrompt, Mutation.agentActivityDeleteQueued, Mutation.agentActivitySendQueued, Mutation.agentSessionCreate, Mutation.agentSessionCreateOnComment, Mutation.agentSessionCreateOnIssue, Mutation.agentSessionRestartWithDefaultModel, … and 343 more
  • Query, 34 of 173 served: Query.administrableTeams, Query.agentActivities, Query.agentActivity, Query.agentSession, Query.agentSessionSandbox, Query.agentSessionSshAddress, Query.agentSessions, Query.agentSkill, … and 131 more
  • Not served at all: Subscription (85)

Missing non-null fields. Selecting one can fail the whole response with Cannot return null for non-nullable field:

  • Comment: bodyData, hideInLinear, isArtificialAgentSessionRoot, reactionData, reactions
  • Cycle: completedIssueCountHistory, completedScopeHistory, currentProgress, inProgressScopeHistory, isActive, isFuture, isNext, isPast, … and 4 more
  • Document: sortOrder
  • Issue: boardOrder, branchName, customerTicketCount, inheritsSharedAccess, previousIdentifiers, priorityLabel, prioritySortOrder, reactionData, … and 2 more
  • Organization: agentAutomationEnabled, aiAddonEnabled, aiDiscussionSummariesEnabled, aiTelemetryEnabled, aiThreadSummariesEnabled, allowedAiProviders, allowedAuthServices, authSettings, … and 39 more
  • Project: completedIssueCountHistory, completedScopeHistory, currentProgress, facets, frequencyResolution, inProgressScopeHistory, issueCountHistory, labelIds, … and 13 more
  • ProjectMilestone: currentProgress, progressHistory
  • ProjectUpdate: bodyData, commentCount, isDiffHidden, isStale, reactionData, reactions
  • Team: aiDiscussionSummariesEnabled, aiThreadSummariesEnabled, ancestors, autoArchivePeriod, children, currentProgress, cycleCalenderUrl, cycleCooldownTime, … and 38 more
  • User: app, avatarBackgroundColor, canAccessAnyPublicTeam, createdIssueCount, hasGitHubCodeAccess, initials, inviteHash, isAssignable, … and 3 more

Not tested. 135 tests compare the simulator with the real service. 19 documented responses have no test yet:

OperationStatusWhy
Mutation.documentCreate200no known request reaches it
Mutation.issueLabelCreate200no known request reaches it
Mutation.issueRelationCreate200no known request reaches it
Mutation.projectCreate200no known request reaches it
Mutation.projectMilestoneCreate200no test could build the request it needs
Mutation.projectMilestoneDelete200no test could build the request it needs
Mutation.projectMilestoneUpdate200no test could build the request it needs
Mutation.projectUpdate200no test could build the request it needs
Mutation.projectUpdateArchive200no test could build the request it needs
Mutation.projectUpdateCreate200no test could build the request it needs
Mutation.webhookCreate200no request a client sends provokes it
Query.cycle200no test could build the request it needs
Query.document200no test could build the request it needs
Query.issue400no known request reaches it
Query.project200no test could build the request it needs
Query.projectMilestone200no test could build the request it needs
Query.projectUpdate200no test could build the request it needs
Query.searchIssues400no known request reaches it
Query.workflowState200no test could build the request it needs

Not modeled. Behavior the simulator does not model, by operation:

  • Behavior when unarchiving an issue that is already active. (Mutation.issueUnarchive)
  • Duplicate-name behavior within a project (whether milestone names must be unique) is unknown. (Mutation.projectMilestoneCreate)
  • Behavior when the hash argument is used instead of id. (Query.comment)
  • Edges { cursor node } is part of ProjectConnection but is not in the documented selection; only nodes and pageInfo are modeled. (Query.projects)
  • … and 220 more

By design.

  • Some related records don’t resolve. These fields resolve, and another relation field can return null or an empty list:

    RecordFields that resolve
    Issueteam, state, assignee, parent, cycle, project, labels, children, comments, documents, relations, inverseRelations
    Comment, attachmentissue
    Relationissue, relatedIssue
    Teamissues, states, cycles, labels, projects
    Workflow state, cycle, labelissues, team
    Projectissues, teams, its milestones, updates and documents
    UserassignedIssues
    Organizationteams, users

    Differs from Linear: team.members returns an empty list, and comment.user returns null, since comments have no author.

  • A new issue in a scenario is numbered from 1.

    Differs from Linear: filing into linear_sprint_board’s ENG returns ENG-1, not ENG-109.

  • URLs are placeholders, so don’t parse them.

    Differs from Linear: issue(id:) returns https://linear.app/issue/<identifier>, with no workspace or title slug. issues and the issueCreate payload return an empty url, and a new comment’s url has the placeholder workspace example.

  • No whole-schema introspection. Query __type for one type instead. It returns the type’s fields with their type and args, an input object’s inputFields and an enum’s enumValues.

    Differs from Linear: __schema is refused, so a code generator can’t read the schema from the simulator. Point it at Linear’s published schema instead.

Release notes: Changelog

Last updated on