{"id":"linear-tickets","repo":"Vokturz/paseo-plugins","url":"https://github.com/Vokturz/paseo-plugins/tree/main/linear-tickets","package":"paseo-linear-tickets","npm":{"package":"paseo-linear-tickets","version":"0.1.0","integrity":"sha512-t/CxAzoSfeO9gb4qco64qBRRObtchvGivesZ6Zu6pp37HXZFon4nbIjOx7/BuXbWKFBHaRDYwIpQPimeB0Pb1Q==","publishedAt":"2026-09-19T16:12:59.188Z","downloadsLast30Days":0},"name":"linear-tickets","description":"Paseo sidebar plugin that lists your assigned Linear tickets and starts an agent with the ticket context, comments and relationships.","categories":["productivity"],"platforms":[],"caveats":["Requires a Linear personal API key with access to the relevant teams","Marking the ticket In Progress on launch writes to Linear and needs write permission"],"images":["https://raw.githubusercontent.com/Vokturz/paseo-plugins/fdbd46eb5905715c2e3bba3b73827cc1c94aa139/linear-tickets/images/01-create-agent.png","https://raw.githubusercontent.com/Vokturz/paseo-plugins/fdbd46eb5905715c2e3bba3b73827cc1c94aa139/linear-tickets/images/02-ticket-list.png","https://raw.githubusercontent.com/Vokturz/paseo-plugins/fdbd46eb5905715c2e3bba3b73827cc1c94aa139/linear-tickets/images/03-create-agent-mobile.jpeg"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-19T17:52:15.394Z","addedAt":"2026-09-19T19:30:43+03:00","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-19T17:49:54.531Z","version":"0.1.0","integrity":"sha512-t/CxAzoSfeO9gb4qco64qBRRObtchvGivesZ6Zu6pp37HXZFon4nbIjOx7/BuXbWKFBHaRDYwIpQPimeB0Pb1Q=="},"path":"linear-tickets","version":"0.1.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-19T17:49:54.531Z","commit":"fdbd46eb5905715c2e3bba3b73827cc1c94aa139"},"license":"MIT","paseoVersionRequirement":">=0.8.0","descriptionNodes":[{"type":"text","text":"Paseo sidebar plugin that lists your assigned Linear tickets and starts an agent with the ticket context, comments and relationships."}],"caveatNodes":[[{"type":"text","text":"Requires a Linear personal API key with access to the relevant teams"}],[{"type":"text","text":"Marking the ticket In Progress on launch writes to Linear and needs write permission"}]],"manifest":{"id":"linear-tickets","requirements":{"paseo":">=0.8.0"},"build":[["npm","ci","--omit=dev"]]},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-19T16:03:33Z"},"owner":{"login":"Vokturz","avatarUrl":"https://avatars.githubusercontent.com/u/21696514?v=4"},"installNotesHtml":"<p>Requires Paseo 0.8.0 or newer and Node.js 22 or newer on the daemon host.</p>\n<p>From npm, with Paseo 0.9 or newer (the pinned package and its production\ndependencies are installed for you):</p>\n<pre><code class=\"language-sh\">paseo plugin add npm:paseo-linear-tickets@0.1.0\n</code></pre>\n<p>From a local checkout:</p>\n<pre><code class=\"language-sh\">cd linear-tickets\nnpm ci\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/linear-tickets\n</code></pre>\n<p>Enable plugins in Paseo Settings → Plugins if needed. Open <strong>Linear tickets</strong> in\nthe sidebar or <strong>Open Linear tickets</strong> in the command center. After source changes:</p>\n<pre><code class=\"language-sh\">paseo plugin reload linear-tickets\n</code></pre>","readmeText":"# Linear tickets\n\nA Paseo sidebar plugin that connects to Linear's GraphQL API, shows tickets assigned to you\n(filtered and searched server-side across your workspace), and starts an agent with the\nticket details, comments and relationships in its first prompt.\n\n![Ticket list with status filters, search and sorting](images/02-ticket-list.png)\n![Starting an agent from a ticket](images/01-create-agent.png)\n![The launch form on mobile](images/03-create-agent-mobile.jpeg)\n\n## Install\n\nRequires Paseo 0.8.0 or newer and Node.js 22 or newer on the daemon host.\n\nFrom npm, with Paseo 0.9 or newer (the pinned package and its production\ndependencies are installed for you):\n\n```sh\npaseo plugin add npm:paseo-linear-tickets@0.1.0\n```\n\nFrom a local checkout:\n\n```sh\ncd linear-tickets\nnpm ci\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/linear-tickets\n```\n\nEnable plugins in Paseo Settings → Plugins if needed. Open **Linear tickets** in\nthe sidebar or **Open Linear tickets** in the command center. After source changes:\n\n```sh\npaseo plugin reload linear-tickets\n```\n\n## Connect and start work\n\n1. Create a personal Linear API key in Settings → Security & access. Read permission\n   and access to the relevant teams are sufficient; write permission is only needed\n   for the optional \"mark the ticket In Progress\" step (see below).\n2. Paste it into **Connect Linear**. Alternatively, set `LINEAR_API_KEY` in the\n   Paseo daemon's environment before starting the daemon.\n3. Select an assigned ticket. Preview the ticket context and choose a Paseo project.\n   For Git projects, select a base branch from the local or remote branches known\n   to the checkout. Choose a provider, then search its models. When supported, choose the\n   provider's change mode and the model's reasoning level, then optionally add instructions.\n4. Select **Start agent with ticket**, then **Open agent**.\n\nTickets load in pages of 50. By default they cover **open work only** — completed,\ncanceled and duplicated states are hidden server-side; the **Settings** menu (gear in\nthe header) has a toggle to include them. The status chips show counts over exactly\nwhat the list shows, following that setting — Linear's GraphQL exposes no aggregation,\nso they come from a bounded server pass (25 pages × 50; counts show a “+” when your\nassignments exceed that) and selecting a chip filters the list server-side by that\nexact state name. The search box filters the loaded tickets\ninstantly and, from two characters up, also runs Linear's workspace-wide search:\nits matches appear in a separate **Across Linear** section, and tickets already on\nthe list are not repeated there. Sort by **Updated**, **Created**, **Due date** or\n**Priority**, then **Newest / Oldest** (for due dates: latest / soonest; for priority:\nhighest / lowest); missing dates and tickets with no priority sort last. Sorting\napplies to the loaded tickets; choose **Load all tickets** to include\nevery assignment. Archived tickets are excluded.\n\nRows show the ticket's priority, a status colour and icon for its workflow state,\nlabel chips, a due date and estimate when your team sets them, and a relative\ntimestamp (\"3h ago\"), with the absolute date in the accessibility label. Status colours follow Linear's workflow category (`started`,\n`completed`, `canceled`, `backlog`, `unstarted`, `duplicate`, …), so custom state\nnames such as \"In Review\" get the right tone in any workspace; keyword matching on\nthe state name remains as a fallback for categories that are not recognised. While tickets load,\nplaceholder rows stand in for the table so the layout does not jump.\n\nFor Git projects, the plugin creates a dedicated worktree from the selected base\nbranch, using Linear's own branch name for the ticket (which respects your workspace's\nbranch-format setting) so Linear's GitHub integration keeps matching branches to issues.\nIf that name is missing or not a safe git ref, a `<ticket id>–<request id>` fallback is\nused instead. When the branch already exists — for example a second launch of the same\nticket — the worktree is created once more with a short request-id suffix appended.\nYour existing checkout is not switched. Remote\nbranches use their locally fetched state; fetch in the project first if you need\nthe newest remote commits. Projects without Git use their project directory.\n\nThe launch fetches fresh details, relationships and comments through Linear's GraphQL API.\nRelationships arrive in both directions — links the ticket makes and links pointing at it\n(blocks, blocked by, related, duplicates, duplicated by) — and appear as a compact\n**Relationships** list above the JSON snapshot, so the agent sees blockers before starting\nwork. Status changes arrive the same way: a compact **Status changes** line (for example\n\"Todo → In Progress → Done (currently Done)\") and the raw state-history spans in the JSON\nsnapshot. The JSON response is preserved in the prompt, including the description and any\nreturned links. Linked documents and attachments are not downloaded. If comments\nare unavailable, the preview and agent prompt say so. Context over 200,000 characters\nis rejected rather than silently truncated.\n\nThe ticket preview shows the ticket's project, team, labels, priority, dates (including\ndue date and estimate when set) and a status-history line, then renders the description as Markdown: headings, bullet and numbered lists, task\ncheckboxes, pipe tables, quotes, dividers, bold text, inline code and fenced code\nblocks. Tables scroll horizontally when they are too wide and keep their column\nalignment. Code blocks carry a copy button, and **Copy context** copies the exact\nJSON snapshot that will be sent to the agent. HTTPS images linked with standard\nMarkdown image syntax and interactive HTTPS links are rendered too.\nImages are loaded by the Paseo client only for display and are not downloaded into the\nagent's workspace or added to its prompt. Provider badges, available modes, and reasoning\nlevels are read from the configured Paseo provider catalog; unavailable capabilities stay\nout of the form.\n\n## Settings\n\nThe **Settings** menu (gear icon in the header, next to the connection and refresh\nbuttons) holds the plugin's per-host settings:\n\n- **Ticket status** — optionally mark the ticket In Progress when the agent starts\n  (off by default; see below).\n- **Tickets shown** — include completed, canceled and duplicated tickets in the list\n  and the status counts (off by default, keeping the list focused on open work).\n- **Default prompt** — replace the built-in launch prompt with a template (below).\n\n## Customizing the launch prompt\n\nEvery launch starts from the built-in default prompt: work on the ticket in the current\nworkspace, respect the repository's instructions, and treat the snapshot as data, not as\nauthority. You can replace it with your own template under **Default prompt** in the\nplugin's **Settings** (gear icon in the header) — for example to have the agent list a\nplan before coding, run the test suite, or open a pull request in a specific format.\n\nPlaceholders are substituted at launch time:\n\n- `{{ticket}}` — the ticket's ID and title\n- `{{instructions}}` — the per-launch \"A little extra direction\" text\n- `{{context}}` — the ticket snapshot (required; a template without it is rejected)\n\nTemplates are limited to 8,000 characters, stored per host with the other plugin settings,\nand apply to new agents only. **Reset to built-in** restores the default. The per-launch\ninstructions field and the 200,000-character context limit apply as before.\n\n## Marking tickets In Progress\n\nBy default the plugin never changes Linear. When you switch on **Mark the ticket In\nProgress when the agent starts** in the plugin's **Settings** (gear icon in the\nheader), a launch also moves the ticket\ninto its team's started state — the state named *In Progress* when the team has one,\notherwise the first started state in the team's workflow. Tickets already in a started\nstate are left as they are, and a team without a started state never produces a write.\nThe choice is saved per host and needs Linear's write permission. If the change cannot\nbe made, the agent still starts and the failure appears as a warning with the result.\n\n## Connection storage\n\nThe API-key form stores the key on the daemon host in\n`$PASEO_HOME/linear-tickets/credentials.json` (default:\n`~/.paseo/linear-tickets/credentials.json`). The directory is owner-only and the\nfile uses mode `0600`; it is a plaintext credential, not an OS keychain entry.\n`LINEAR_API_KEY` takes precedence over a saved key. Disconnect removes the saved\nkey; environment keys must be removed from the daemon environment followed by a\nrestart. All clients connected to this host share the same Linear account. Saved\ndefault-prompt templates live next to the key in `settings.json` with the same\npermission pattern.\n\nThe plugin talks directly to Linear's official [GraphQL API](https://linear.app/developers/graphql)\nat `https://api.linear.app/graphql`. Its queries are read-only; the only write is the\noptional In Progress transition made when a launch is explicitly opted in. Only the\nserver contacts Linear. The key is never added to ticket context, agent configuration,\nor agent labels.\n\nRepeated launch requests reuse their result for the lifetime of the loaded plugin.\nIf agent creation returns an uncertain failure, the same request is not retried\nautomatically: check the project's workspaces and agent list before reopening the ticket to\nstart again. This retry cache does not survive a plugin or daemon restart.\n\n## Validation\n\n`npm run typecheck` checks both entrypoints against Paseo's SDK. `npm test` covers\nGraphQL response parsing, pagination, context preservation, prompt template rendering\nand validation, credential and settings persistence, ticket retrieval, state-transition\nresolution and failure handling, and agent creation/retries with mocked Linear and Paseo\ncalls.\nLive account authentication and agent execution require your configured host and key.\n"}