Raycast Extension

What you need

• Mach Triage desktop app installed, running, and signed in.
• Raycast on macOS (stable) or Windows (beta).
• The Mach Triage extension installed from the Raycast Store.

Setup (30 seconds)

1. In the desktop app, open Settings → Raycast Integration and flip the Enable toggle. This starts a local HTTP bridge on 127.0.0.1:17847.
2. Click Generate Token and copy the token that appears.
3. In Raycast, go to Extensions → Mach Triage → Preferences and paste the token into Bridge Token. The Bridge URL defaults to http://127.0.0.1:17847—only change it if you changed the port in Settings.
4. Run Mach Triage Status in Raycast. It should show Connected with your app version and workspace info.

Commands

• Search Tickets — full-text search across your active workspace by key, title, or description. Results come from the local SQLite database, so they are instant.
• Today Board — your Active / Stuck / Next / Done lanes, same layout as the desktop palette. Navigate with the keyboard; actions are available on every row.
• Mach Triage Status — health check confirming the bridge is running and authenticated. Useful for first-time setup and troubleshooting.

Ticket actions

These actions are available from any ticket in Search or the Today Board.

• View Detail (Enter) — full description, comments, worklogs, and metadata rendered as Markdown.
• Open in Mach Triage (⌘O) — deep-links to the ticket in the desktop app.
• Change Status (⌘⇧S) — transition between To Do, In Progress, Done, Backlog, or Canceled.
• Add Comment (⌘⇧M) — post a Markdown comment with an optional toggle to sync it to the provider (Jira, Linear, or GitHub).
• Log Work (⌘⇧W) — record hours and minutes. Jira worklogs push to the provider; Linear and GitHub track time locally in Mach Triage.
• Copy Key (⌘C) — copies the issue key (e.g. PA-42) to the clipboard.

Workspace filtering

If you have multiple workspaces connected, the extension defaults to your active workspace. A workspace picker lets you switch context without going back to the desktop app.

Settings reference

• Enable / Disable — starts or stops the localhost bridge. Disabling also revokes the current token.
• Port — defaults to 17847. Change it in both the desktop app and Raycast preferences if you need a different port.
• Generate / Regenerate Token — creates a new bearer token. The old token is invalidated immediately, so paste the new one into Raycast preferences right away.
• Pinned Armory side — choose left or right for the Armory dock strip (separate from Raycast, but visible in the same Settings panel when Pro is active).

How the bridge works (high level)

The extension sends HTTP requests to 127.0.0.1 only—never to Mach Triage cloud services. The desktop app runs an Axum HTTP server bound to the loopback interface. Every request carries a bearer token that the app verifies with constant-time comparison. Provider credentials (Jira OAuth, Linear API keys, GitHub tokens) stay in the desktop app's encrypted storage and are never exposed to Raycast.

When something goes wrong

• "Mach Triage is not reachable" — launch the desktop app. The bridge only runs when the app is running.
• "Bridge token rejected" — regenerate in Settings → Raycast Integration → Generate Token and paste the new one into Raycast preferences.
• "Raycast bridge is disabled" — flip the Enable toggle in Settings.
• Search returns nothing — confirm your active workspace has synced tickets. Try Sync Now from the desktop triage palette.
• Worklog says "local only" — Linear and GitHub do not have worklog APIs. Time is tracked locally in Mach Triage. Jira worklogs push to Atlassian normally.
• Pro required (403) on a specific action — the bridge itself is free, but endpoints tied to Pro-only desktop features (e.g. Armory) return 403 without an active subscription. Upgrade from your dashboard if you need those features.