Niteshift for Raycast

A Raycast extension for the Niteshift background-agent platform. Run, monitor, and prompt agent tasks from anywhere with a keystroke.

Status: v1, ready for coworker sideload and Raycast Store submission — see Publishing below.

Prerequisites

• macOS with Raycast 1.83+
• The Niteshift CLI: npm install -g niteshift
• For the developer install path: Node.js 22.14+ and git

Installation

There are three ways to install the extension. Pick the one that matches your situation.

Option A — Sideload a pre-built bundle (no dev server required)

Use this path if you just want the extension to work — no Node process running in the background, survives reboots. This is also the path for non-technical coworkers and customers: they only need a pre-built dist/ folder.

1. Produce a dist/ folder. Either build it yourself:

   npm install
   npm run build   # runs `ray build -e dist -o dist` — writes an optimized production bundle to ./dist

   …or grab a dist/ zip someone else built and unzip it.
2. In Raycast, open the Import Extension command and pick the dist/ folder. Raycast copies it into its own extensions directory and registers the commands under the extension title.
3. Authenticate the CLI in your terminal (one time):

   niteshift auth

4. Done. The commands keep working with no terminal, no dev server, no ray develop process. They survive Raycast restarts and system reboots.

To update after code changes: re-run npm run build, then run Import Extension again on the same dist/ folder (Raycast overwrites the previous import).

Why this works: ray build emits a fully-bundled JS file plus package.json and assets into dist/. Raycast's Import Extension command accepts any folder containing a valid package.json + built entry, so pointing it at dist/ installs the production bundle directly — no store round-trip needed. This is the same mechanism used for dev imports (Option B), just pointed at the built output instead of the source tree.

Option B — Developer install (live reload)

Best if you want to edit the code or contribute fixes.

1. Clone the repo:

   git clone https://github.com/niteshiftdev/niteshift-raycast.git ~/code/niteshift-raycast
   cd ~/code/niteshift-raycast
   npm install

2. In Raycast, run Import Extension and select the ~/code/niteshift-raycast folder.
3. Start the dev server and keep it running:

   npm run dev

   Raycast picks up source changes automatically while npm run dev is alive. If you stop it, the commands stop working — Raycast will say "Could not find command's executable JS file." Restart npm run dev or build the dist bundle (Option A).
4. Authenticate the CLI:

   niteshift auth

Option C — Public Raycast Store (coming soon)

Once the extension lands in the Raycast Store, you'll be able to install with one click from inside Raycast: search for "Niteshift" in the Store command, click Install, done. Auto-updates handled by Raycast.

This path is not live yet — the submission PR is still open. See Publishing for the flow.

Commands

Command	What it does
Run New Task	Opens a form with a multi-line prompt field. ⌘↵ submits — the task is created against your inferred default repo and model, and the task page opens in your browser. Defaults: the extension queries the API for your most recent task and reuses its repo and model, so a change made anywhere (web UI, CLI, another Raycast run) is reflected on the next run. If your most recent task's repo is no longer linked, it falls back to the first repo alphabetically. If you have no prior tasks, it falls back to claude-opus-4-7. There's no in-extension UI to pick a different repo/model — the rich selection still lives in the Niteshift web UI for the rare times you need a different combination.
List Tasks	Searchable list of recent tasks across your repos. Open the action menu (⌘K) on any task to Watch Stream, Send Follow-up Prompt (⌘⇧F), Copy Pickup Command, copy the URL/ID, or refresh.

Action menu (⌘K) on a task

Once you're on a task in List Tasks, press ⌘K to see all available actions:

• Open in Browser (⏎) — opens the task page in the Niteshift web UI.
• Watch Stream — pushes a Detail view that backfills the task's messages and follows new ones live via SSE.
• Send Follow-up Prompt (⌘P) — pushes a form for typing a follow-up prompt to the task.
• Copy Task URL (⌘C) and Copy Task Id (⌘⇧C).
• Copy Pickup Command (⌘⇧P) — only shown for tasks the niteshift CLI can pick up locally (suspended/running tasks with a synced session). Copies niteshift pickup <id> (or the env-prefixed variant) to the clipboard so you can paste it in a terminal. There's also a Copy Pickup --resume Command sibling for resuming inside the agent.
• Refresh (⌘R) — re-fetches the task list.

The list also archives-out: archived tasks are excluded from the API call (and from a defensive client-side filter), so the view only shows active work.

Environment switching

The extension defaults to Production. To use staging or dev:

1. Authenticate against that environment from the terminal first:

   niteshift --env staging auth
   niteshift --env dev auth

2. In Raycast, open the extension's preferences (⌘ ⇧ ,) and switch the Environment dropdown.

If the env preference doesn't match an env you've authenticated against, the extension will show a "CLI Auth Required" view with the exact command to run.

Limitations

• No file attachments in Send Follow-up Prompt (v1 — see future work below).
• No menu bar command (v1).
• Pickup is a discovery surface, not a local executor — the action copies the right niteshift pickup command for you to paste in a terminal; the CLI does the actual local checkout.
• Requires the CLI for authentication. There is no in-Raycast device-code or OAuth flow yet.

Building the dist bundle (for distribution)

npm install
npm run build

That writes a self-contained, importable extension to ./dist/. Zip it and share with coworkers who don't want to deal with Node and npm run dev.

cd dist && zip -r ../niteshift-raycast-dist.zip . && cd ..

Publishing

• Coworker / customer sideload — ready. Build the dist/ bundle and share it.
• Public Raycast Store — ready to submit. npm run lint passes; the author in package.json matches a live Raycast.com profile.

To submit, run:

npm run lint    # Store submission CI runs this — make sure it's clean first
npm run publish

npm run publish (which wraps npx @raycast/api@latest publish) opens a guided flow that:

• Forks raycast/extensions to your GitHub account
• Drops the extension into extensions/niteshift/ in that fork
• Opens a PR
• The Raycast team reviews; on merge it's live in the Store

Manual test plan

After any non-trivial change, run through this:

1. npm install && npm run dev (or import a fresh dist/ build)
2. With CLI authed against prod: open List Tasks → see real tasks (no archived tasks should appear)
3. Switch env preference to an unauthed env: List Tasks shows the AuthGate view; copy command works
4. Switch back. Run New Task → form opens with a multi-line prompt field; typing a prompt and pressing ⌘↵ creates the task against your most-recently-used (or first alphabetical) repo
5. Submit a task end-to-end → browser opens task URL
6. In List Tasks, select a task → ⌘K → Watch Stream → push detail view → messages stream → pop the view → no leaked SSE connection (lsof -i | grep niteshift)
7. Same task → ⌘K → Send Follow-up Prompt (⌘P) → submit a prompt → it appears in the web UI
8. UI-created task with sessionSync → ⌘K → Copy Pickup Command → paste in terminal → real pickup runs
9. Type running (or any status name) into the search bar → only matching tasks show

Troubleshooting

• "Could not find command's executable JS file. You might need to rebuild the extension." — You're on Option B (dev install) and npm run dev isn't running. Restart it, OR switch to Option A by importing a built dist/ folder.
• "Niteshift CLI Auth Required" but I'm authed: check the Environment preference matches what you authed against. Each env has its own auth file.
• Watch Stream never streams new events: the SSE connection may not work in your Raycast Node runtime. The task state panel on the right of the Detail view still polls, so status stays current even if messages don't.
• List Tasks is empty: verify with niteshift list in a linked repo. Note that archived tasks are filtered out by default.

Future work

• Menu bar command with running task count
• File attachments in Send Prompt
• Real OAuth via @raycast/utils (so non-CLI users can install from the Store without first running niteshift auth)
• Shared @niteshift/api-client package consumed by both CLI and extension
• Raycast AI extension tools (@niteshift create_task etc.)

Contributing

This is a personal/team extension during v1; improvements are welcome but expect breaking changes between versions until v1.0.