@context-fs/linear

Virtual filesystem that exposes your Linear workspace as files and directories. Browse issues, teams, and users with standard filesystem tools.

Installation

``bash
npm install -g @context-fs/linear
`

Or run directly:

`bash
npx @context-fs/linear --mount /tmp/linear
`

Quick Start

`bash


Mount your Linear workspace

npx @context-fs/linear --mount /tmp/linear

Browse issues

ls /tmp/linear/issues/by-id/
cat /tmp/linear/issues/by-id/ENG-123/content.md

Search

ls /tmp/linear/issues/search/authentication\ bug/

View team issues

ls /tmp/linear/teams/ENG-engineering/issues/active/
`

Authentication

The CLI will prompt for your Linear API key on first run. Get one from Linear Settings > API.

API keys are stored securely in your system keychain:

- macOS: Keychain Access (via security CLI)
- Linux: Secret Service API (GNOME Keyring, KWallet, etc. via secret-tool)

Alternatively, set the LINEAR_API_KEY environment variable:

`bash
LINEAR_API_KEY=lin_api_xxx npx @context-fs/linear --mount /tmp/linear
`

To reset stored credentials:

`bash
npx @context-fs/linear --reset
`

Filesystem Structure

`
/
├── user.json # Current authenticated user
├── organization.json # Workspace organization info
├── ctl/
│ └── refresh-cache # Read to clear all caches
│
├── issues/
│ ├── by-id/
│ │ └── / # By UUID or identifier (e.g., ENG-123)
│ │ ├── content.md # Issue content (read/write)
│ │ ├── team # Symlink to team
│ │ ├── assignee # Symlink to assignee
│ │ └── creator # Symlink to creator
│ └── search/
│ └── / # Search results as symlinks
│
├── teams/
│ └── / # e.g., ENG-engineering
│ ├── info.json # Team metadata
│ └── issues/
│ ├── new # Write here to create issue
│ ├── all/ # All team issues
│ ├── active/ # Started/unstarted issues
│ └── triage/ # Triage issues (if enabled)
│
└── users/
└── / # e.g., john-doe
├── info.json # User metadata
└── issues/
├── assigned/ # Open assigned issues
├── completed/ # Completed issues
└── created/ # Issues created by user
`

Reading Issues

Issue content is served as Markdown with YAML frontmatter:

`bash
cat /tmp/linear/issues/by-id/ENG-123/content.md
`

`markdown
---
id: abc-123-def
identifier: ENG-123
title: Fix authentication bug
state: In Progress
priority: 2
assignee: john-doe
team: ENG
labels:
- bug
- security
url: https://linear.app/myorg/issue/ENG-123
createdAt: 2024-01-15T10:30:00.000Z
updatedAt: 2024-01-16T14:22:00.000Z
---

Users are unable to log in after password reset.

Steps to reproduce

1. Request password reset
2. Click link in email
3. Set new password
4. Try to log in

Expected behavior

User should be able to log in with new password.
`

Writing Issues

$3

Modify content.md to update the title or description:

`bash


Edit with your favorite editor

vim /tmp/linear/issues/by-id/ENG-123/content.md

Or programmatically

cat > /tmp/linear/issues/by-id/ENG-123/content.md << 'EOF'
---
title: Fix authentication bug (updated)
---

Updated description here.
EOF
`

Only title and the body (description) are writable. Other frontmatter fields are read-only.

$3

Write to the new file in a team's issues directory:

`bash
cat > /tmp/linear/teams/ENG-engineering/issues/new << 'EOF'
---
title: Implement dark mode
---

Add dark mode support to the settings page.
EOF
`

Searching

URL-encode your search query in the path:

`bash


Simple search

ls /tmp/linear/issues/search/login%20bug/

Results are symlinks to actual issues

cat /tmp/linear/issues/search/login%20bug/ENG-123/content.md
`

Symlinks

Issues include symlinks to related entities:

`bash


Follow team symlink

cat /tmp/linear/issues/by-id/ENG-123/team/info.json

Follow assignee symlink

cat /tmp/linear/issues/by-id/ENG-123/assignee/info.json

Check where a symlink points

readlink /tmp/linear/issues/by-id/ENG-123/team

/teams/ENG-engineering

`

Caching

Data is cached to minimize API calls. To refresh:

`bash
cat /tmp/linear/ctl/refresh-cache
`

CLI Options

`
Usage: linear-fs [options]

Options:
--mount Mount point directory
--host Server bind address (default: 127.0.0.1)
--port Server port (default: 2049)
--reset Clear stored API key
-h, --help Show help
`

Programmatic Usage

`typescript
import { createLinearFileSystem } from "@context-fs/linear";
import { mount } from "@context-fs/nfs";

const vfs = await createLinearFileSystem(process.env.LINEAR_API_KEY!);

await using handle = await mount(vfs, {
mountPoint: "/tmp/linear",
});

// Filesystem is now mounted
`

Use Cases

- AI/LLM context: Give AI assistants access to your issue tracker
- Scripting: Automate issue management with shell scripts
- Search: Use grep, find, ripgrep across your issues
- Backup: Copy issues to local files
- Integration: Pipe issue content to other tools

Related Packages

- @context-fs/core - Virtual filesystem core
- @context-fs/cli - CLI framework
- @context-fs/nfs` - NFS server

License

MIT