Linear - Pome

A deterministic, resettable, in-process digital twin of Linear’s GraphQL API. It reproduces the same query and mutation shapes and error semantics as Linear without touching the live service. Each instance starts from a task seed and resets between runs, so the same task produces the same state every time. Unlike the REST-shaped twins, it speaks GraphQL at /graphql.

By use case

These are the workflows agents actually run against this twin, each naming the MCP tools and GraphQL surfaces involved. Anything named here that is not fully modelled says so in place.

Triage an issue

List backlog issues, read one, move it through workflow states, and update its assignee, priority, or estimate. save_issue omits dueDate and milestone over MCP; issueUpdate over raw GraphQL can set dueDate directly. MCP: list_issues, get_issue, save_issue. GraphQL: issues, issue, issueCreate, issueUpdate.

Comment and label an issue

Reply in a comment thread and attach a label to flag it for follow-up. MCP: list_comments, save_comment, delete_comment, list_issue_labels. GraphQL: comments, comment, commentCreate, commentDelete, issueAddLabel, issueRemoveLabel, issueLabels.

Browse projects and cycles

Read what a team is working on and when. MCP: list_projects, get_project, save_project, list_cycles, list_teams. GraphQL: projects, project, cycles, cycle, teams, workflowStates.

Read and write documents

List a team’s documents and create or update one. save_document omits initiative parents, and there is no GraphQL-layer document surface in this twin — document access is MCP-only. MCP: list_documents, get_document, save_document.

Run agent sessions and webhooks

Create an agent session on an issue or comment, log an activity against it, and register a webhook for delivery. GraphQL only, and there is no external delivery beyond logged attempts — no live Linear network calls. GraphQL: agentSessions, agentSession, agentSessionCreateOnIssue, agentSessionCreateOnComment, agentSessionUpdate, agentActivityCreate, webhooks, webhookCreate, webhookDelete.

Authenticate as an OAuth client

Exercise the same authorization-code flow a real Linear OAuth app would. The twin also accepts a seeded personal token for client parity without the round trip. GraphQL: GET /oauth/authorize, POST /oauth/authorize/callback, POST /oauth/token, POST /oauth/revoke.

What you can rely on

Each surface below carries two rulings that are deliberately kept apart: heat is how deep it should be, ruled per milestone; state is how deep it is today, measured by the twin’s own tests. Neither moves because the other did. A surface is in exactly one state, and the four below are different answers to “can I write a task against this”:

State	What it means
Verified	the behaviour is implemented and test-covered. Code written against the real API runs here unchanged.
Shape only	the response shape matches the real API, but the values and the side effects behind it are not asserted. Read it; do not grade on it.
Out of scope	a loud 501, and it stays one. Ruled off an agent’s task chain, so the 501 is the answer rather than a gap.
Vendor-only tool	the vendor declares it and the twin answers `unknown_tool`. An agent doing the right thing is marked down for it.

@pome-sh/twin-linear declares 22 MCP tools and 45 GraphQL surfaces, read from the twin’s own fidelity.inventory.json (last updated 2026-07-22):

State	MCP tools	GraphQL surfaces
Verified	17	34
Shape only	5	11

Shape only

Read these; do not grade on them. The response shape is right and the behaviour behind it is not asserted, so a criterion that checks a value here can pass for the wrong reason.

Surface	Heat
`get_team`	warm
`get_user`	warm
`get_issue_status`	warm
`create_issue_label`	warm
`search_documentation`	cold
`organization`	warm
`user`	warm
`team`	warm
`workflowState`	warm
`issueLabel`	warm
`issueDelete`	warm
`issueArchive`	warm
`issueUnarchive`	warm
`commentUpdate`	warm
`issueLabelUpdate`	warm
`issueLabelDelete`	warm

Out of scope

The MCP families outside the tools above — initiatives, milestones, releases, attachments, git diffs and PR review, status updates, and agent skills — are not modelled, and GraphQL fields outside this inventory are refused with a loud GraphQL validation error (HTTP 400). Nothing outside that is given a named row here: a call to it reaches the twin’s catch-all and is refused loudly, never answered with a faked success.

Vendor-only tool

The vendor declares it and the twin answers unknown_tool. An agent doing the right thing is marked down for it.

Tools	Registered as	Why it is accepted
`get_attachment`, `create_attachment`, `create_attachment_from_upload`, `prepare_attachment_upload`, `delete_attachment`, `extract_images`	`LINEAR-MCP-001`	Out of modeled scope: twin-linear models no attachments. There is no upload endpoint, no blob store and no file identity behind an issue, so every one of these six reads or writes an object that does not exist here. One entry because they are one absence — modelling any member means building the blob layer all six sit on. Real tools, not scope artifacts: the 2026-08-10 capture holds read+write, and `read` alone returns 36 tools against 58 for both.
`list_agent_skills`, `get_agent_skill`	`LINEAR-MCP-002`	Out of modeled scope: Linear’s agent-skill registry belongs to Linear’s own agent platform, not to the issue tracker this twin models. An examinee enumerating skills is exercising the vendor’s agent product rather than the API surface a Pome exam is about.
`list_release_pipelines`, `list_releases`, `get_release`, `save_release`, `list_release_notes`, `get_release_note`, `save_release_note`	`LINEAR-MCP-003`	Out of modeled scope: the twin models no releases, release pipelines or release notes. Nothing in its schema associates an issue with a shipped version, so there is no object for any of the seven to read or write.
`get_diff`, `list_diffs`, `get_diff_threads`, `save_diff_comment`, `resolve_diff_thread`, `delete_diff_comment`, `submit_diff_review`, `merge_diff`	`LINEAR-MCP-004`	Out of modeled scope: Linear’s code-review surface. The twin models no diffs, no review threads and no merge. Worth stating rather than assuming, because an examinee reviewing code is exercising a capability Pome DOES have — it lives in twin-github, on a different vendor. The absence here is a scope boundary between two twins, not a gap in the product.
`list_milestones`, `get_milestone`, `save_milestone`	`LINEAR-MCP-005`	Out of modeled scope: project milestones are not modeled. The twin’s projects carry issues directly, with no milestone layer between them, so there is nothing for these three to list, read or write.
`list_initiatives`, `get_initiative`, `save_initiative`, `list_initiative_labels`, `create_initiative_label`	`LINEAR-MCP-006`	Out of modeled scope: initiatives are the layer ABOVE projects and the twin’s hierarchy stops at project. Modelling one member means adding that layer and everything that hangs off it, including the initiative-scoped label namespace the last two read.
`get_status_updates`, `save_status_update`, `delete_status_update`	`LINEAR-MCP-007`	Out of modeled scope: project and initiative status updates are not modeled. The twin has no periodic-update object attached to either, and the initiative half additionally has no initiative to attach to (LINEAR-MCP-006).
`get_workspace`	`LINEAR-MCP-008`	Out of modeled scope: the twin serves ONE implicit workspace and has no workspace object to read. Its own entry because it is the root the other absences hang from — modelling initiatives or status updates without a workspace to scope them to would be modelling half a hierarchy.
`list_project_labels`	`LINEAR-MCP-009`	Out of modeled scope: labels on PROJECTS are a separate taxonomy from labels on issues, which the twin does model (`list_issue_labels`, `create_issue_label`). Adding this is a second label namespace with its own storage and its own attach edges, not a second endpoint on the first.

Where it runs. Both doors serve the same twin: pome twin start linear boots it as a local process, and pome sandbox create --twin linear starts a hosted sandbox running the same image. The states above are properties of the twin, so they hold on either. Everything above is what the twin declares. What it was measured to do is a different number: the comparison against real Linear runs daily and publishes, surface by surface, how many matched, which drifted, and which are ruled exceptions with the reason written out in full — at status.pome.sh/twin/linear, which also states when it last ran and how old the captured baseline it compares against is. No count is copied onto this page, because copying one is how it goes stale. Read from FIDELITY.md, fidelity.inventory.json, LIMITS.md and REFERENCE-DIVERGENCES.md in pome-sh/digital-twins, at the commit .github/twins-ref pins (2e41939). LIMITS.md is the one to read before writing a task that pages, batches or attaches — every bound it names is enforced and fails loudly rather than truncating. REFERENCE-DIVERGENCES.md records which oracle each ruling was measured against.

Quickstart

pome run tasks/24-linear-issue-triage.md \
  --agent "<your agent command>"

That task boots the Linear twin, seeds a world from the task, hands your agent a base URL and a token, and scores the run once the agent exits.

Point your agent at it

For interactive development without a full task run, start the standalone twin:

pome twin start linear

The command prints env-var lines you can paste into your agent’s environment:

POME_LINEAR_REST_URL=http://127.0.0.1:3337/s/standalone
POME_LINEAR_MCP_URL=http://127.0.0.1:3337/s/standalone/mcp
POME_AUTH_TOKEN=<jwt>
POME_LINEAR_TOKEN=<jwt>

POME_LINEAR_REST_URL is the GraphQL root — the twin exposes it at /graphql. POME_LINEAR_MCP_URL is the MCP transport endpoint. POME_AUTH_TOKEN is the Pome JWT, and POME_LINEAR_TOKEN is an alias of it. The default local user is admin@pome-twin.test, and the seed also provisions a personal token lin_test_admin. The twin accepts the Pome JWT, seeded Linear tokens, or lin_pome_* provider tokens as bearers. Since it speaks GraphQL, point requests at /graphql with a query in the body:

curl "$POME_LINEAR_REST_URL/graphql" \
  -H "Authorization: Bearer $POME_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id name email } }"}'

GraphQL still exposes issueCreate/issueUpdate for SDK parity, even though the MCP surface uses save_issue.

To check whether the twin is alive, use the unauthenticated root health endpoint:

curl http://127.0.0.1:3337/healthz

Task seed shape

Linear task seeds are flat, with organization, users, teams, labels, projects, cycles, issues, comments and documents, plus oauthApps, tokens and webhooks. Each team carries its own states, and an issue’s state names one of them. Generate it; do not copy it. The block below is what the twin starts with, printed by the CLI from the twin’s own declared state — so it parses against the twin you are about to seed, today and after the twin changes:

pome twin new-seed linear > linear.seed.json

A seed replaces the twin’s starting state. It does not merge into it. Seed your own world and everything below is gone — drop a team and ENG-1 does not resolve.

{
  "clock": "2026-07-21T00:00:00.000Z",
  "defaultSid": "standalone",
  "baseUrl": "http://127.0.0.1:3337",
  "strictScopes": false,
  "organization": {
    "id": "org_pome",
    "name": "Pome Twin",
    "urlKey": "pome-twin"
  },
  "users": [
    {
      "id": "user_admin",
      "email": "admin@pome-twin.test",
      "name": "Admin User",
      "displayName": "Admin",
      "active": true,
      "admin": true,
      "app": false
    },
    {
      "id": "user_dev",
      "email": "dev@pome-twin.test",
      "name": "Developer",
      "displayName": "Dev",
      "active": true,
      "admin": false,
      "app": false
    },
    {
      "id": "user_agent",
      "email": "agent@pome-twin.test",
      "name": "Pome Agent",
      "displayName": "Pome Agent",
      "active": true,
      "admin": false,
      "app": true
    }
  ],
  "teams": [
    {
      "id": "team_eng",
      "key": "ENG",
      "name": "Engineering",
      "description": "Default engineering team",
      "private": false,
      "states": [
        {
          "id": "state_backlog",
          "name": "Backlog",
          "type": "backlog",
          "position": 0
        },
        {
          "id": "state_todo",
          "name": "Todo",
          "type": "unstarted",
          "position": 1
        },
        {
          "id": "state_progress",
          "name": "In Progress",
          "type": "started",
          "position": 2
        },
        {
          "id": "state_done",
          "name": "Done",
          "type": "completed",
          "position": 3
        },
        {
          "id": "state_canceled",
          "name": "Canceled",
          "type": "canceled",
          "position": 4
        }
      ]
    }
  ],
  "labels": [
    {
      "id": "label_bug",
      "name": "Bug",
      "color": "#d92d20",
      "description": "Defect",
      "team": "ENG"
    },
    {
      "id": "label_feature",
      "name": "Feature",
      "color": "#2563eb",
      "description": "New work",
      "team": "ENG"
    },
    {
      "id": "label_agent",
      "name": "Agent",
      "color": "#0f766e",
      "description": "Agent triage",
      "team": "ENG"
    }
  ],
  "projects": [
    {
      "id": "project_local",
      "name": "Local Twin",
      "description": "Agent evaluation workspace",
      "state": "started",
      "team": "ENG"
    }
  ],
  "cycles": [
    {
      "id": "cycle_1",
      "team": "ENG",
      "name": "Cycle 1",
      "number": 1,
      "startsAt": "2026-07-14T00:00:00.000Z",
      "endsAt": "2026-07-28T00:00:00.000Z"
    }
  ],
  "issues": [
    {
      "id": "issue_backlog",
      "team": "ENG",
      "title": "Triage inbox for agent eval",
      "description": "Backlog item waiting for triage.",
      "priority": 2,
      "state": "Backlog",
      "assignee": "dev@pome-twin.test",
      "creator": "admin@pome-twin.test",
      "project": "Local Twin",
      "cycle": "Cycle 1",
      "labels": [
        "Agent"
      ],
      "createdAt": "2026-07-20T10:00:00.000Z",
      "updatedAt": "2026-07-20T10:00:00.000Z"
    },
    {
      "id": "issue_todo",
      "team": "ENG",
      "title": "Ship Linear twin GraphQL surface",
      "description": "Implement issue CRUD + comments for agent testing.",
      "priority": 3,
      "state": "Todo",
      "assignee": "dev@pome-twin.test",
      "creator": "admin@pome-twin.test",
      "project": "Local Twin",
      "cycle": "Cycle 1",
      "labels": [
        "Feature"
      ],
      "createdAt": "2026-07-20T12:00:00.000Z",
      "updatedAt": "2026-07-20T14:00:00.000Z"
    },
    {
      "id": "issue_progress",
      "team": "ENG",
      "title": "Wire MCP tools to commands",
      "description": "Keep GraphQL and MCP on the same LinearDomain layer.",
      "priority": 2,
      "state": "In Progress",
      "assignee": "admin@pome-twin.test",
      "creator": "admin@pome-twin.test",
      "project": "Local Twin",
      "cycle": "Cycle 1",
      "labels": [
        "Feature",
        "Agent"
      ],
      "createdAt": "2026-07-20T16:00:00.000Z",
      "updatedAt": "2026-07-21T00:00:00.000Z"
    },
    {
      "id": "issue_done",
      "team": "ENG",
      "title": "Seed multi-issue agent world",
      "description": "Default seed covers backlog/todo/progress/done.",
      "priority": 1,
      "state": "Done",
      "assignee": "dev@pome-twin.test",
      "creator": "admin@pome-twin.test",
      "project": "Local Twin",
      "labels": [
        "Bug"
      ],
      "createdAt": "2026-07-19T09:00:00.000Z",
      "updatedAt": "2026-07-20T18:00:00.000Z"
    }
  ],
  "comments": [
    {
      "id": "comment_1",
      "issue": "Ship Linear twin GraphQL surface",
      "body": "Starting with viewer + issues queries.",
      "user": "admin@pome-twin.test",
      "createdAt": "2026-07-20T13:00:00.000Z"
    },
    {
      "id": "comment_2",
      "issue": "Wire MCP tools to commands",
      "body": "MCP list_issues should match GraphQL issues.",
      "user": "dev@pome-twin.test",
      "createdAt": "2026-07-20T17:00:00.000Z"
    },
    {
      "id": "comment_3",
      "issue": "Triage inbox for agent eval",
      "body": "@Pome Agent please prioritize this.",
      "user": "admin@pome-twin.test",
      "createdAt": "2026-07-20T11:00:00.000Z"
    }
  ],
  "documents": [],
  "oauthApps": [
    {
      "id": "oauth_app_1",
      "clientId": "lin_example_client_id",
      "clientSecret": "example_client_secret",
      "name": "Pome Linear App",
      "redirectUris": [
        "http://localhost:3000/api/auth/callback/linear"
      ],
      "scopes": [
        "read",
        "write",
        "issues:create",
        "comments:create",
        "admin"
      ],
      "actor": "user",
      "assignable": true,
      "mentionable": true,
      "appUserId": "user_agent"
    }
  ],
  "tokens": [
    {
      "token": "lin_test_admin",
      "type": "personal",
      "user": "admin@pome-twin.test",
      "scopes": [
        "read",
        "write",
        "issues:create",
        "comments:create",
        "admin"
      ],
      "actor": "user",
      "sid": "standalone"
    }
  ],
  "webhooks": [
    {
      "id": "webhook_1",
      "label": "Sample webhook",
      "url": "http://127.0.0.1:9999/linear-hooks",
      "resourceTypes": [
        "Issue",
        "Comment"
      ],
      "team": "ENG",
      "allPublicTeams": false,
      "secret": "whsec_test_linear",
      "enabled": true
    }
  ]
}

Set twins: ["linear"] in the task’s ## Config block and name the file <task>.seed.json, beside the task’s .md. That ## Config is the only place the twin gets named: the file above is flat, so it carries no twin id of its own.

Seed file

A task is not the only way in. pome twin start and pome sandbox create take that very same file — no wrapper, no second shape, nothing to convert — and each takes the twin’s name beside it, since the file cannot supply one:

pome twin start linear --seed linear.seed.json
pome sandbox create --twin linear --seed linear.seed.json

Omit the name and neither door guesses; both stop and say the seed is flat. Add a second twin and the file becomes a per-twin envelope instead, one key each — pome twin new-seed linear slack writes it:

{ "linear": { /* exactly the world above */ }, "slack": { /* that twin's world */ } }

One twin, one flat file: the twin’s own world with no wrapper, which means it says nothing about which twin it is for. That is why twin start and sandbox create want the name as well, and why a task’s sidecar does not — the ## Config beside it already named the twin. From two twins up the file is a per-twin envelope { <twin>: <seed> }, which does name its twins, though twin start still has to be told which one of them to boot. Replace, not merge, applies wherever the file lands. Build your own world is that job end to end — generating the file, editing it down, both doors, and how to tell whether every field you wrote actually landed.

Example tasks

Ready-made examples you can run or copy to see the twin in action:

pome tasks linear
pome tasks linear --copy

Catalog

#	Task	What it exercises
24	Issue triage (`24-linear-issue-triage.md`)	List backlog issues, move one into progress, and leave a triage comment.
25	Comment & label triage (`25-linear-comment-label-triage.md`)	Reply in a comment thread, attach a “Needs triage” label, and set an estimate.

There is also a cross-twin handoff task, 26-github-linear-handoff.md, cataloged under GitHub.

Run one

pome run tasks/24-linear-issue-triage.md --agent "<your agent command>"

Or let the coach pick and run a matching task for you — the pome-suggest-tasks and pome-run-task skills, installed by the graded capstone.

​By use case

​Triage an issue

​Comment and label an issue

​Browse projects and cycles

​Read and write documents

​Run agent sessions and webhooks

​Authenticate as an OAuth client

​What you can rely on

​Shape only

​Out of scope

​Vendor-only tool

​Quickstart

​Point your agent at it

​Task seed shape

​Seed file

​Example tasks

​Catalog

​Run one

By use case

Triage an issue

Comment and label an issue

Browse projects and cycles

Read and write documents

Run agent sessions and webhooks

Authenticate as an OAuth client

What you can rely on

Shape only

Out of scope

Vendor-only tool

Quickstart

Point your agent at it

Task seed shape

Seed file

Example tasks

Catalog

Run one