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
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.
Linear GraphQL endpoint; override to point at a fake or proxy.
Authentication
The mount reads with a personal API key. The key’s Read permission is enough; thelinear 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, solsthe parent instead of building a name. team.json: the team’s metadata.issue.json: the issue, with fields such asissue_id,issue_key,team_id,state_idandassignee_idthat commands take as they are.comments.jsonl: the issue’s comments, one JSON object per line, ordered bycreated_at. It is a Mirage format, not a Linear one.- Members: each file carries
user_idandemail, ready for commands such aslinear 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.
Behavior
- Read only: the mount cannot change issues. Use the
linearCLI 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 browserLinearVFS 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 -rwandrg -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: -1in the mount’s"@all"command limit reads every file instead.grep -randrgon 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, whateverwalk_limitis. 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>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- A named segment is
<sanitized-name>__<id>; the id after the last__is exact.lsthe 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.jsonlholds one comment per line. team.jsonlists 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
linearCLI if installed (linear --help).
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.