Skip to main content
LinearVFS mounts a Linear workspace as read-only JSON files: teams, members, issues with their comments, projects, cycles and documents. Set up the API key as in Linear setup.

Install

Configure

teamIds limits the mount to some teams. baseUrl points at another GraphQL endpoint, such as a proxy.

Fields

number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
required
secret
Linear personal API key.
string[]
Only these teams are listed or readable. Unset shows every team the key can reach.
string
default:"'https://api.linear.app/graphql'"
Linear GraphQL endpoint; override to point at a fake or proxy.
Fields marked secret are redacted in snapshots.

Authentication

The mount reads with a personal API key. The key’s Read permission is enough; the linear CLI needs Write or the create permissions to change issues. A key limited to some teams sees only those teams.

Layout

  • Names: every name ends in __<id>: a team is <team-key>__<team-name>__<team-id>, an issue <issue-key>__<issue-id>, a member <display-name>__<user-id>.json, and a project, cycle or document <name>__<id>.json. The readable part is sanitized, so ls the parent instead of building a name.
  • team.json: the team’s metadata.
  • issue.json: the issue, with fields such as issue_id, issue_key, team_id, state_id and assignee_id that commands take as they are.
  • comments.jsonl: the issue’s comments, one JSON object per line, ordered by created_at. It is a Mirage format, not a Linear one.
  • Members: each file carries user_id and email, ready for commands such as linear issue assign.
  • Projects and cycles: a project lists its related issues; a cycle carries its start and end dates.
  • Documents: each file holds the title, the markdown content, the linked project and the creator.
Files hold Mirage’s JSON with snake_case keys, not Linear’s raw GraphQL response.

Behavior

  • Read only: the mount cannot change issues. Use the linear CLI to create, update, assign and comment on issues; the tree serves the same entities as JSON files.
  • Recent writes: Linear indexes a write some time after it lands, so a search can miss a recent issue change. See Integration.

Browser

The browser LinearVFS from @struktoai/mirage-browser takes the same fields.
  • The API key reaches the page, so give it only the Read permission.

Integration

Linear answers this command through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: Linear’s issue search runs for each word, and only the issues that hold every word are read, where the search names it or the listing keeps it. The listing keeps each issue’s other fields (team, project, cycle, state, people, labels, dates, link) and each title or description word the search can miss, such as one inside a link. Every issue is read when the word is a key of the issue JSON (title, priority) or a JSON literal, has a digit or only the letters a to f, or when a search fails, returns 250 issues or finds nothing. walk_limit: -1 in the mount’s "@all" command limit reads every file instead.
  • grep -r and rg on members, projects, cycles and documents: the listing keeps their whole JSON, so only the files whose text holds the pattern’s text in any case are read, whatever walk_limit is. Issues are listed once more, so a change since the last listing is still found. A file over 8 KiB, and every file for a text that is not ASCII, is read as usual. Comments are always read: they are fetched per issue, and Linear’s comment search can miss a word inside a link.

VFS.md

The VFS.md an agent reads with Linear mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • A named segment is <sanitized-name>__<id>; the id after the last __ is exact. ls the parent for exact names rather than building them.
  • Files are JSON normalized by Mirage with snake_case keys (issue_key, state_name, assignee_email, label_names), not Linear’s GraphQL shape. comments.jsonl holds one comment per line.
  • team.json lists the team’s workflow states; a project file lists its issues with their state.
  • To create, update, assign, transition or comment on issues, use the linear CLI if installed (linear --help).
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.