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:
| Key | Acts as |
|---|---|
lin_api_hana | Hana Lindqvist |
lin_api_tomas | Tomas Reyes |
lin_api_yuki | Yuki Sato |
lin_api_deploybot | Deploy Bot |
| any other key | Mira 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 request | Status | Each error has |
|---|---|---|
| can’t be parsed or validated | 400, no data | message, 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 read | 200, data null | message, locations and extensions with code GRAPHQL_VALIDATION_FAILED, type, userError and http with status 400 (Filters) |
| names a record that doesn’t exist | 200, data null | message (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: -1 | 200, data null | message (Argument Validation Error), locations, path, and extensions with code INVALID_INPUT, type, userError, userPresentableMessage and validationErrors |
| costs more than 10,000 complexity points | 400, no data | message (Query too complex) and extensions with code INPUT_ERROR, http, statusCode, type, userError and userPresentableMessage |
| runs past a rate-limit budget | 429, no data | message (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:
| Budget | Size | Response headers |
|---|---|---|
| requests | 2,500 an hour | x-ratelimit-requests-limit, x-ratelimit-requests-remaining, x-ratelimit-requests-reset |
| query complexity | 3,000,000 points an hour | x-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.
| Resource | Operations |
|---|---|
| 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.
| Operation | Event types |
|---|---|
Mutation.commentCreate | Comment |
Mutation.commentDelete | Comment |
Mutation.commentUpdate | Comment |
Mutation.issueArchive | Issue |
Mutation.issueCreate | Issue |
Mutation.issueDelete | Issue |
Mutation.issueLabelCreate | IssueLabel |
Mutation.issueLabelDelete | IssueLabel |
Mutation.issueUnarchive | Issue |
Mutation.issueUpdate | Issue |
Mutation.projectCreate | Project |
Mutation.projectDelete | Project |
Mutation.projectUpdate | Project |
Scenarios
The simulator ships 5 scenarios; the quickstart boots linear_sprint_board.
| Scenario | What it is for | What it seeds | Clock |
|---|---|---|---|
linear_archive_vault | A workspace of archived and trashed records, for soft-delete reads and restores | comment 1, document 2, issue 3, organization 1, project 1, project_update 1, team 1, user 2, workflow_state 2 | 2026-02-10T00:00:00Z |
linear_roadmap_quarter | A planning workspace with no issues, for roadmap reads | document 2, organization 1, project 3, project_milestone 6, project_update 4, team 2, user 4 | 2026-03-02T00:00:00Z |
linear_solo_workspace | A new workspace with nothing in it yet, for a client’s first write | organization 1, team 1, user 1, workflow_state 4 | 2026-01-06T00:00:00Z |
linear_sprint_board (default) | One engineering team on the day cycle 7 closes, for board, cycle and issue reads | attachment 2, comment 3, cycle 2, issue 8, issue_label 3, issue_relation 2, organization 1, team 1, user 6, workflow_state 6 | 2026-02-02T00:00:00Z |
linear_triage_inbox | A support team’s untriaged queue, for assignment and prioritization writes | attachment 5, comment 2, issue 5, issue_label 2, issue_relation 1, organization 1, team 1, user 2, workflow_state 3 | 2026-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_boardhas three labels and two cycles. -
No live issue with a null
archivedAt.Differs from Linear: a seeded live issue reads
""forarchivedAt, where Linear returns null. -
No team and no person on an empty boot, so
issueCreatereturnsEntity not found: Teamuntil 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):
| After | Who | What happens |
|---|---|---|
| 30 minutes | Hana | replies on ENG-103 |
| 1 hour | Hana | moves ENG-103 to Done |
| 2 hours | Deploy Bot | attaches a production deploy to ENG-103 |
| 3 hours | Tomas | starts ENG-102 |
| 4 hours | Yuki | files 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):
| Records | Registers |
|---|---|
| Workspace | state_organization, state_team, state_user, state_workflow_state, state_cycle |
| Issues | state_issue, state_comment, state_issue_label, state_issue_relation, state_attachment |
| Projects and documents | state_project, state_project_milestone, state_project_update, state_document |
| Webhooks and OAuth | state_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
parentIdgiven as an identifier is dropped byissueUpdate, so the issue reads back no parent, thoughissueCreatetakes either form. SelectingProject.status,Team.visibilityor a user’sorganizationfails the whole response withCannot return null for non-nullable field, so leave them out of a selection. - An issue filed without a
stateIdhas no workflow state, so selecting itsstatefails the response. Apriorityabove 4, an emptytitleand a second label with an existing name are accepted where Linear refuses them. - An input field Linear does not define, or a
projectCreatewithoutteamIds, is accepted where Linear returns 400. issues(first:)lists oldest first where Linear lists newest first. Every list acceptsfirst: 251where Linear caps a page at 250. Given nofirstorlast, every list butissues,documentsandprojectsreturns all its rows where Linear returns 50.- An
issueCreaterepeating a client-suppliedidoverwrites the existing issue where Linear refuses it. - An issue’s
attachmentsfield returns an empty list; queryattachmentsorattachmentsForURLon 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,reactionsCycle:completedIssueCountHistory,completedScopeHistory,currentProgress,inProgressScopeHistory,isActive,isFuture,isNext,isPast, … and 4 moreDocument:sortOrderIssue:boardOrder,branchName,customerTicketCount,inheritsSharedAccess,previousIdentifiers,priorityLabel,prioritySortOrder,reactionData, … and 2 moreOrganization:agentAutomationEnabled,aiAddonEnabled,aiDiscussionSummariesEnabled,aiTelemetryEnabled,aiThreadSummariesEnabled,allowedAiProviders,allowedAuthServices,authSettings, … and 39 moreProject:completedIssueCountHistory,completedScopeHistory,currentProgress,facets,frequencyResolution,inProgressScopeHistory,issueCountHistory,labelIds, … and 13 moreProjectMilestone:currentProgress,progressHistoryProjectUpdate:bodyData,commentCount,isDiffHidden,isStale,reactionData,reactionsTeam:aiDiscussionSummariesEnabled,aiThreadSummariesEnabled,ancestors,autoArchivePeriod,children,currentProgress,cycleCalenderUrl,cycleCooldownTime, … and 38 moreUser: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:
| Operation | Status | Why |
|---|---|---|
Mutation.documentCreate | 200 | no known request reaches it |
Mutation.issueLabelCreate | 200 | no known request reaches it |
Mutation.issueRelationCreate | 200 | no known request reaches it |
Mutation.projectCreate | 200 | no known request reaches it |
Mutation.projectMilestoneCreate | 200 | no test could build the request it needs |
Mutation.projectMilestoneDelete | 200 | no test could build the request it needs |
Mutation.projectMilestoneUpdate | 200 | no test could build the request it needs |
Mutation.projectUpdate | 200 | no test could build the request it needs |
Mutation.projectUpdateArchive | 200 | no test could build the request it needs |
Mutation.projectUpdateCreate | 200 | no test could build the request it needs |
Mutation.webhookCreate | 200 | no request a client sends provokes it |
Query.cycle | 200 | no test could build the request it needs |
Query.document | 200 | no test could build the request it needs |
Query.issue | 400 | no known request reaches it |
Query.project | 200 | no test could build the request it needs |
Query.projectMilestone | 200 | no test could build the request it needs |
Query.projectUpdate | 200 | no test could build the request it needs |
Query.searchIssues | 400 | no known request reaches it |
Query.workflowState | 200 | no 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
hashargument is used instead ofid. (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:
Record Fields that resolve Issue team,state,assignee,parent,cycle,project,labels,children,comments,documents,relations,inverseRelationsComment, attachment issueRelation issue,relatedIssueTeam issues,states,cycles,labels,projectsWorkflow state, cycle, label issues,teamProject issues,teams, its milestones, updates and documentsUser assignedIssuesOrganization teams,usersDiffers from Linear:
team.membersreturns an empty list, andcomment.userreturns null, since comments have no author. -
A new issue in a scenario is numbered from 1.
Differs from Linear: filing into
linear_sprint_board’sENGreturnsENG-1, notENG-109. -
URLs are placeholders, so don’t parse them.
Differs from Linear:
issue(id:)returnshttps://linear.app/issue/<identifier>, with no workspace or title slug.issuesand theissueCreatepayload return an emptyurl, and a new comment’surlhas the placeholder workspaceexample. -
No whole-schema introspection. Query
__typefor one type instead. It returns the type’sfieldswith theirtypeandargs, an input object’sinputFieldsand an enum’senumValues.Differs from Linear:
__schemais refused, so a code generator can’t read the schema from the simulator. Point it at Linear’s published schema instead.
Release notes: Changelog