Linear

The Linear VFS exposes Linear workspace data as a virtual filesystem mounted at some prefix such as /linear/. For API key setup, see Linear Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.linear import LinearConfig, LinearVFS

config = LinearConfig(api_key=os.environ["LINEAR_API_KEY"])
vfs = LinearVFS(config=config)
ws = Workspace({"/linear": vfs}, mode=MountMode.READ)

Field	Description
`timeout` default `30`	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.
`api_key` required, secret	Linear personal API key.
`workspace`	Accepted for compatibility; not read.
`team_ids`	Only these teams are listed or readable. Unset shows every team the key can reach.
`base_url` default `'https://api.linear.app/graphql'`	Linear GraphQL endpoint; override to point at a fake or proxy.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Linear mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`linear`, read

`/<path>` layout

/<path>
  teams/
    <team-key>__<team-name>__<team-id>/
      team.json
      members/
        <display-name>__<user-id>.json
      issues/
        <issue-key>__<issue-id>/
          issue.json
          comments.jsonl
      projects/
        <name>__<project-id>.json
      cycles/
        <name>__<cycle-id>.json
      documents/
        <title>__<document-id>.json
  Always ls directories first to discover exact names.

  Folder/file name anatomy: every entity-named segment is
    <sanitized-human-readable>__<id>
  The human-readable part is sanitized — don't construct it; ls the
  parent dir to discover exact entry names.
  IDs are the LAST "__"-separated segment. To extract:
    /<path>/teams/STR__Strukto-ai__<team-id>/             -> <team-id>
    /<path>/teams/.../issues/STR-42__<issue-id>/          -> <issue-id>
    /<path>/teams/.../members/Alice__<user-id>.json       -> <user-id>

  All cat output is mirage-normalized (snake_case keys), NOT the raw
  Linear GraphQL response. Shapes:

  team.json:
    {
      "team_id": "...", "team_key": "STR", "team_name": "Strukto",
      "name": "...", "description": "...", "timezone": "...",
      "updated_at": "...",
      "states": [
        { "state_id": "...", "state_name": "Todo", "type": "unstarted" },
        ...                              # one element per workflow state
      ]
    }

  issue.json:
    {
      "issue_id": "...", "issue_key": "STR-42",
      "title": "...", "description": "...",
      "team_id": "...", "team_key": "...", "team_name": "...",
      "project_id": "...",   "project_name": "...",
      "cycle_id": "...",     "cycle_name": "...",   "cycle_number": 7,
      "state_id": "...",     "state_name": "In Progress",
      "assignee_id": "...",  "assignee_email": "...", "assignee_name": "...",
      "creator_id":  "...",  "creator_email":  "...", "creator_name":  "...",
      "priority": 2,         # 0=none 1=urgent 2=high 3=medium 4=low
      "label_ids":   ["..."],
      "label_names": ["bug", "frontend"],
      "created_at": "...", "updated_at": "...", "url": "..."
    }

  comments.jsonl:                      # one normalized comment per line
    { "comment_id": "...", "issue_id": "...", "issue_key": "STR-42",
      "user_id": "...", "user_email": "...", "user_name": "...",
      "body": "...", "created_at": "...", "updated_at": "...",
      "url": "..." }

  project.json:
    {
      "project_id": "...", "team_id": "...",
      "name": "...", "description": "...", "state": "started",
      "lead_id": "...", "updated_at": "...", "url": "...",
      "issue_count": 12,
      "issues": [
        { "issue_id": "...", "issue_key": "STR-42", "title": "...",
          "state_id": "...", "state_name": "In Progress", "url": "..." }
      ]
    }

  cycle.json:
    {
      "cycle_id": "...", "team_id": "...",
      "name": "...", "number": 7,
      "starts_at": "...", "ends_at": "...",
      "updated_at": "...", "url": "..."
    }

  user.json:
    {
      "user_id": "...", "name": "...", "display_name": "...",
      "email": "...", "is_active": true, "is_admin": false,
      "updated_at": "...", "url": "..."
    }

  Useful jq paths:
    .issue_key                              # issue.json
    .state_name                             # issue.json
    .assignee_email                         # issue.json
    .label_names[]                          # issue.json
    .issues[] | select(.state_name == "In Progress")   # project.json
    .states[].state_name                    # team.json
    [inputs] | length                       # comments.jsonl: count
    [inputs | select(.user_email == "x")] | length     # comments.jsonl

  document.json:
    {
      "document_id": "...", "title": "...", "content": "...",
      "project_id": "...", "project_name": "...",
      "creator_id": "...", "creator_name": "...", "creator_email": "...",
      "created_at": "...", "updated_at": "...", "url": "..."
    }

  To act on issues (list/get/create/update/assign/transition,
  comments, projects, cycles, labels, users, documents, search), use
  the linear CLI if installed: linear --help

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `linear` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `linear` answers only for `teams//issues//issue.json`, `teams//members/`, `teams//projects/`, `teams//cycles/` and `teams//documents/`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `linear`, read |

## `/<path>` layout

```text
/<path>
  teams/
    <team-key>__<team-name>__<team-id>/
      team.json
      members/
        <display-name>__<user-id>.json
      issues/
        <issue-key>__<issue-id>/
          issue.json
          comments.jsonl
      projects/
        <name>__<project-id>.json
      cycles/
        <name>__<cycle-id>.json
      documents/
        <title>__<document-id>.json
  Always ls directories first to discover exact names.

  Folder/file name anatomy: every entity-named segment is
    <sanitized-human-readable>__<id>
  The human-readable part is sanitized — don't construct it; ls the
  parent dir to discover exact entry names.
  IDs are the LAST "__"-separated segment. To extract:
    /<path>/teams/STR__Strukto-ai__<team-id>/             -> <team-id>
    /<path>/teams/.../issues/STR-42__<issue-id>/          -> <issue-id>
    /<path>/teams/.../members/Alice__<user-id>.json       -> <user-id>

  All cat output is mirage-normalized (snake_case keys), NOT the raw
  Linear GraphQL response. Shapes:

  team.json:
    {
      "team_id": "...", "team_key": "STR", "team_name": "Strukto",
      "name": "...", "description": "...", "timezone": "...",
      "updated_at": "...",
      "states": [
        { "state_id": "...", "state_name": "Todo", "type": "unstarted" },
        ...                              # one element per workflow state
      ]
    }

  issue.json:
    {
      "issue_id": "...", "issue_key": "STR-42",
      "title": "...", "description": "...",
      "team_id": "...", "team_key": "...", "team_name": "...",
      "project_id": "...",   "project_name": "...",
      "cycle_id": "...",     "cycle_name": "...",   "cycle_number": 7,
      "state_id": "...",     "state_name": "In Progress",
      "assignee_id": "...",  "assignee_email": "...", "assignee_name": "...",
      "creator_id":  "...",  "creator_email":  "...", "creator_name":  "...",
      "priority": 2,         # 0=none 1=urgent 2=high 3=medium 4=low
      "label_ids":   ["..."],
      "label_names": ["bug", "frontend"],
      "created_at": "...", "updated_at": "...", "url": "..."
    }

  comments.jsonl:                      # one normalized comment per line
    { "comment_id": "...", "issue_id": "...", "issue_key": "STR-42",
      "user_id": "...", "user_email": "...", "user_name": "...",
      "body": "...", "created_at": "...", "updated_at": "...",
      "url": "..." }

  project.json:
    {
      "project_id": "...", "team_id": "...",
      "name": "...", "description": "...", "state": "started",
      "lead_id": "...", "updated_at": "...", "url": "...",
      "issue_count": 12,
      "issues": [
        { "issue_id": "...", "issue_key": "STR-42", "title": "...",
          "state_id": "...", "state_name": "In Progress", "url": "..." }
      ]
    }

  cycle.json:
    {
      "cycle_id": "...", "team_id": "...",
      "name": "...", "number": 7,
      "starts_at": "...", "ends_at": "...",
      "updated_at": "...", "url": "..."
    }

  user.json:
    {
      "user_id": "...", "name": "...", "display_name": "...",
      "email": "...", "is_active": true, "is_admin": false,
      "updated_at": "...", "url": "..."
    }

  Useful jq paths:
    .issue_key                              # issue.json
    .state_name                             # issue.json
    .assignee_email                         # issue.json
    .label_names[]                          # issue.json
    .issues[] | select(.state_name == "In Progress")   # project.json
    .states[].state_name                    # team.json
    [inputs] | length                       # comments.jsonl: count
    [inputs | select(.user_email == "x")] | length     # comments.jsonl

  document.json:
    {
      "document_id": "...", "title": "...", "content": "...",
      "project_id": "...", "project_name": "...",
      "creator_id": "...", "creator_name": "...", "creator_email": "...",
      "created_at": "...", "updated_at": "...", "url": "..."
    }

  To act on issues (list/get/create/update/assign/transition,
  comments, projects, cycles, labels, users, documents, search), use
  the linear CLI if installed: linear --help
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `linear` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `linear` answers only for `teams/*/issues/*/issue.json`, `teams/*/members/*`, `teams/*/projects/*`, `teams/*/cycles/*` and `teams/*/documents/*`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

/linear/
  teams/
    <team-key>__<team-name>__<team-id>/
      team.json
      members/
        <display-name>__<user-id>.json
        ...
      issues/
        <issue-key>__<issue-id>/
          issue.json
          comments.jsonl
        ...
      projects/
        <name>__<project-id>.json
        ...
      cycles/
        <name>__<cycle-id>.json
        ...
      documents/
        <title>__<document-id>.json
        ...

Example:

/linear/
  teams/
    ENG__Engineering__abc123def/
      team.json
      members/
        alice__usr_001.json
        bob__usr_002.json
      issues/
        ENG-123__iss_001/
          issue.json
          comments.jsonl
        ENG-124__iss_002/
          issue.json
          comments.jsonl
      projects/
        Mirage__proj_001.json
      cycles/
        Sprint-12__cyc_001.json
      documents/
        Search-Architecture__doc_001.json

Directory and file names embed the Linear ID after __ so that VFS-specific commands can reference the correct VFS without extra lookups.

Teams

Each team directory is named:

<team-key>__<team-name>__<team-id>

Inside the team directory:

team.json is the normalized team metadata
members/ contains one JSON file per member
issues/ contains one directory per issue
projects/ contains one JSON file per project, including lightweight related issue references
cycles/ contains one JSON file per cycle

Issues

Each issue directory is named:

<issue-key>__<issue-id>

Each issue directory contains:

issue.json — normalized issue metadata with command-aligned fields such as issue_id, issue_key, team_id, state_id, and assignee_id
comments.jsonl — normalized comment stream ordered by created_at

comments.jsonl is a Mirage representation chosen for shell-friendly workflows. It is not a native Linear file format.

Members

Each member file is named:

<display-name>__<user-id>.json

Member JSON includes command-aligned identifiers such as user_id and email so the value can be reused directly in commands like linear issue assign.

Projects and Cycles

Project and cycle files are named:

<name>__<id>.json

Project JSON includes lightweight related issue references. Cycle JSON includes cycle metadata such as start and end dates.

Documents

Each team has a documents/ folder with one JSON file per Linear document:

<title>__<document-id>.json

Document JSON includes the title, markdown content, the linked project, and the creator.

Integration

What Linear answers through its own API, so fewer files are read. Integration explains each command.

Command	On Linear
`grep -r`, `rg`	Issues: Linear search, for whole words. Other files: the text the listing keeps. It can miss recent issue writes.

grep -rw and rg -w ask Linear’s issue search for each word and read only the issues that hold every word, where the search names it or the listing keeps it. The listing keeps the 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, which an id can hold, and when a search fails, returns 250 issues or finds nothing. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Linear indexes a write some time after it lands. Members, projects, cycles and documents are listed with their whole JSON, so grep -r and rg list them once more and read only the files whose text holds the pattern’s text in any case, whatever walk_limit is. The issues are listed once more too, 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.

Cache

The Linear VFS uses IndexCacheStore (same as Discord and other mounts). File bytes go through the workspace file cache.

Example

See examples/python/vfs/linear/linear.py for the full working example.

# List teams
ls /linear/teams/

# Read team metadata
cat /linear/teams/ENG__Engineering__abc123/team.json

# List issues
ls /linear/teams/ENG__Engineering__abc123/issues/

# Read an issue
cat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/issue.json

# Read issue comments
cat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/comments.jsonl

# Extract issue ID with jq
cat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/issue.json \
  | jq '.issue_id'

# Read last 5 comments
tail -n 5 /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/comments.jsonl

# List members
ls /linear/teams/ENG__Engineering__abc123/members/

# Read a project with its issues
cat /linear/teams/ENG__Engineering__abc123/projects/Mirage__proj_001.json \
  | jq '.issues'

# Tree view
tree -L 2 /linear/teams/

Finding IDs

IDs are embedded in directory and file names after __:

# Team ID -- embedded in directory name
ls /linear/teams/
# -> ENG__Engineering__abc123   <- team_id = abc123

# Issue ID -- embedded in issue directory name
ls /linear/teams/ENG__Engineering__abc123/issues/
# -> ENG-123__iss_001   <- issue_id = iss_001

# Member ID -- embedded in member file name
ls /linear/teams/ENG__Engineering__abc123/members/
# -> alice__usr_001.json   <- user_id = usr_001

# Use stat for structured metadata
stat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/issue.json

# Extract fields with jq
cat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/issue.json \
  | jq '{issue_id, issue_key, team_id, state_id, assignee_id}'

Shell Commands

Standard commands available on the mounted Linear tree:

Command	Notes
`ls`	List teams, issues, members, projects
`cat`	Read .json metadata or .jsonl comments
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`basename`	Extract file name from path
`dirname`	Extract directory from path
`realpath`	Resolve path to absolute form

Acting on Linear

Reads and writes on Linear entities (issues, comments, projects, cycles, labels, users, documents, search) go through the linear CLI when installed; the mounted tree serves the same entities as normalized JSON files.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Teams

Issues

Members

Projects and Cycles

Documents

Integration

Cache

Example

Finding IDs

Shell Commands

Acting on Linear

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Teams

​Issues

​Members

​Projects and Cycles

​Documents

​Integration

​Cache

​Example

​Finding IDs

​Shell Commands

​Acting on Linear

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Teams

Issues

Members

Projects and Cycles

Documents

Integration

Cache

Example

Finding IDs

Shell Commands

Acting on Linear