A VS Code extension that syncs Linear issues down into local markdown files — one folder per ticket, with screenshots and attachments downloaded alongside.
This is a one-way sync (Linear → local). It never writes back to Linear, and the API key only needs read access.
How it works
You pick a root folder (default: linear/ in your workspace). Inside it, you
create one subfolder per ticket, named by the Linear identifier:
linear/
eng-730/ ← you create this empty folder
eng-742/
On each sync pass the extension scans those direct subfolders, looks up the matching Linear issue, and fills each folder:
linear/eng-730/
issue.md ← YAML frontmatter + the issue description
images/ ← screenshots embedded in the description
attachments/ ← non-image uploaded files
Images and file links that point at uploads.linear.app are downloaded and the
markdown links are rewritten to the local relative paths, so everything renders
in VS Code's markdown preview. Links to external services (GitHub, Figma, etc.)
are left as-is.
Change detection
issue.md stores the issue's updatedAt timestamp in its frontmatter. On the
next pass the extension compares it against Linear; a folder is only rewritten
when the issue actually changed (or when you run Sync Now, which forces a
refresh). The images/ and attachments/ folders are treated as managed —
they are rebuilt from scratch on each update so deleted assets don't linger.
Setup
- In Linear, go to Settings → Security & access → Personal API keys and create a read-only key.
- In VS Code, run
Linear Markdown Sync: Set Personal API Keyfrom the command palette and paste it. The key is stored in VS Code SecretStorage, not in settings or on disk. - Create a
linear/folder and add a ticket subfolder (e.g.eng-730). - Run
Linear Markdown Sync: Sync Now.
Commands
| Command | Description |
|---|---|
Linear Markdown Sync: Sync Now |
Force a full sync of every ticket folder. |
Linear Markdown Sync: Set Personal API Key |
Store / replace the API key. |
Linear Markdown Sync: Clear API Key |
Remove the stored key. |
Settings
| Setting | Default | Description |
|---|---|---|
linearMarkdownSync.rootFolder |
linear |
Folder containing the per-ticket subfolders. Relative to the first workspace folder, or an absolute path. |
linearMarkdownSync.syncOnStartup |
true |
Run a sync when the extension activates. |
linearMarkdownSync.syncIntervalMinutes |
0 |
Auto-sync interval in minutes (0 disables). |
linearMarkdownSync.watchForNewFolders |
true |
Sync a ticket folder automatically when it's created. |
linearMarkdownSync.includeComments |
false |
Append comments to issue.md (and download their images). |
Develop
npm install
npm run compile # bundle with esbuild
npm run watch # rebuild on change
npm run typecheck # tsc --noEmit
npm run vsix # produce a .vsix
Press F5 in VS Code to launch an Extension Development Host.
Notes & limits (MVP)
- Only
uploads.linear.appassets are downloaded; other hosts stay as links. - The
images/andattachments/directories are managed by the extension and rebuilt on each update — don't store your own files there. - One-way only; local edits are never pushed back to Linear and are overwritten when the issue changes upstream.