Getting started
- Install ScriptDeck and open it. It lives in the menu bar (the notification area on Windows) and shows in the Dock only while Settings or a terminal window is open.
- Click the icon, then Add a project. In Settings, click + and choose a folder with a
package.json, or drop folders on the window.
- Click the menu bar icon again and press the play button next to a script. Click a running script to open its terminal.
Turn on Launch at login in Settings › Preferences so your scripts are a click away after a restart.
Running scripts
Every script runs in its own terminal through your login shell, so it gets the same PATH as your terminal app, and colours, prompts and interactive tools work as usual.
- Running and failed scripts are listed at the top of the menu bar window, each with how long it has run. Restart or stop one there, or click Stop all.
- Click a running script to open its terminal window: watch the output, scroll back or type into it. Cmd+F (Ctrl+F on Windows) finds text in its whole scrollback, and Cmd+click (Ctrl+click) opens a web link it printed.
- Hover a terminal tab to see the CPU and memory all of its script's processes use, with CPU as a share of the whole Mac. A script past 500 MB or 10% CPU shows it in the menu bar window too. macOS only.
- When a script prints a local address, its port appears as a link, such as
:5173, that opens it in your browser.
- If a script can't start because its port is taken, its row names what holds the port, another script or a leftover process. Free port stops that and restarts yours. macOS only.
- To add arguments such as
--watch, Option-click a script's Run button (Alt-click on Windows). ScriptDeck adds the -- npm needs and remembers them for next time.
- Stopping a script escalates from Ctrl-C to SIGTERM to SIGKILL on its whole process tree, so no stray child keeps a port busy.
- Quitting ScriptDeck stops every script it started. With Reopen running scripts on in Settings › Preferences, the ones still running start again the next time ScriptDeck opens, after an update too.
- The menu bar icon shows how many scripts are running. Right-click it for Open ScriptDeck, Settings…, Stop All Scripts and Quit ScriptDeck.
Restart on crash
Click the pulse icon on a script's row in its project's settings (Restart if it crashes). It stays lit while it's on. When the script dies on its own, it comes back after 1 second, then 2, 4, 8 and 16. If all five restarts crash within a minute of starting, it stays down. Stopping it yourself never restarts it.
Notifications
With Notify when a script fails on in Settings › Preferences, you get a system notification when a script exits with an error on its own. Stopping a script yourself doesn't count, and neither does a failure you're watching in its terminal. A script that restarts on crash notifies once as it starts restarting, and again if it gives up.
Notify when a long script finishes tells you when one that ran for 30 seconds or more, such as an install or a build, is done.
Notify when tests pass or fail covers any script with test, tests, e2e, vitest, jest, mocha or cypress in its name or command, however quick it was. Test runners in watch mode never exit, so they don't notify.
If macOS is blocking ScriptDeck's notifications, Settings › Preferences shows an Allow button above the switches. macOS asks only once, so after a Don't Allow the button opens System Settings instead.
Search, pins and the shortcut
Start typing in the menu bar window to search every script in every project, by project, package, script name or command.
- ↑ ↓ pick a result and Enter runs it. If it's already running, Enter opens its terminal.
- Shift+Enter opens a field for arguments, such as
--watch, before it runs.
- Groups show up in the results too. Enter starts the scripts in one that aren't running yet.
- Esc clears the search. Press it again to close the window.
- Star a script to pin it. A project shows its pinned and custom scripts, or its root
package.json scripts until you pin something. Everything else is one search away.
- To open ScriptDeck from any app, record a shortcut under Open ScriptDeck in Settings › Preferences. It must include Ctrl, Option or Cmd, so it can't take over a plain key everywhere.
Package managers and workspaces
ScriptDeck reads the packageManager field in package.json, or else looks for a lockfile: pnpm-lock.yaml, yarn.lock, bun.lock or bun.lockb, or package-lock.json. It checks parent folders too, so a package added on its own still uses its monorepo's package manager. With neither, it uses npm.
Workspace packages come from pnpm-workspace.yaml or the workspaces field, and their scripts run with the package manager's own filter:
| Package manager | Runs a workspace script as |
| pnpm | pnpm -F @acme/app run start |
| yarn | yarn workspace @acme/app run start |
| npm | npm run start -w @acme/app |
| bun | bun run --filter @acme/app start |
Custom scripts
For commands that aren't in any package.json, like one package's Storybook or a database container, add a name and a command under Custom scripts in the project's settings. Custom scripts always show in the menu bar window.
Branches and worktrees
A project in a git repository shows its branch beside its name, with a dot for uncommitted changes and ↓2 when there's something to pull. Click it to open the switcher:
- Pick a branch to check it out. Type a name that isn't one yet to make it here, or to make a new worktree for it.
- Switch the project to another worktree of the repository. Its scripts then run in that folder, and what's already running keeps running, so the same
dev can run on two branches at once, each in its own terminal named after its branch.
- Pull fast-forwards the branch. Git never waits on a password prompt: it uses your credential helper or SSH agent, or says why it can't.
- A new worktree or a fresh clone with no
node_modules shows its install command, like pnpm install.
Manage worktrees… at the foot of the switcher opens the project's settings at its worktrees, each with what's running in it, Use and Remove, and a form for a new one from a new or existing branch. New worktrees go beside the repository, so app and feature/x make app-feature-x. A worktree is never removed while it has uncommitted or untracked files, another worktree inside it, or scripts running in it.
To clone a repository, click the button beside + in Settings, then give a URL or owner/repo and a folder. The clone opens as a project. Committing and pushing stay in your terminal or editor.
Node versions
Each project runs with its own Node version. By default ScriptDeck follows the project's .nvmrc, .node-version or Volta pin, looking in parent folders too.
- To use a different one, pick any version installed with nvm, fnm or Volta under Node version in the project's settings.
- If the version a project wants isn't installed, an Install button runs your version manager's install command.
- The project's Node is set after your shell's rc files run, so it wins over your version manager's default.
- Settings shows the
engines range from package.json beside the version your scripts will use.
- Without nvm, fnm or Volta, scripts use whatever
node your shell finds.
Editing package.json scripts
A project's settings list the scripts of its root package.json and of every workspace package, with a filter to find one fast.
- Add a script with +, change its name or command with the pencil, or delete it with ×. A renamed script keeps its pin.
- ScriptDeck changes only the entry you edit. Key order, indentation and line endings stay as they were, so your diffs stay small.
AI agents (MCP)
ScriptDeck has an MCP server, so Claude Code or another AI agent can list your scripts, read and search their output, and start, restart or stop them. It's off by default, and not on Windows yet.
- Turn on Let AI agents read and restart scripts (MCP) in Settings › Preferences.
- Click Copy beside Add to Claude Code and run the command in your terminal. Another agent needs a stdio server that runs the same app path with
--mcp.
Agents never type into a terminal. They reach ScriptDeck through a socket only your user can open, only while the switch is on, and no network port is opened. An agent can read everything your scripts print, so leave the switch off if that includes secrets.
Settings
Open Settings from the gear in the menu bar window, or right-click the menu bar icon.
- Projects. Add folders with + or by dropping them on the window, or clone a repository with the button beside +. Rename a project by editing its name, or remove it from ScriptDeck; your files aren't touched.
- Groups. Under Groups in a project's settings, click +, name the group and pick its scripts from Add script. The group gets a row in the menu bar window that starts or stops them all, and you can run it from Settings too.
- Toolkit. Install, Outdated, Update, Audit and Clean reinstall run with the project's package manager, each in its own terminal like a script. Clean reinstall deletes
node_modules first, so it asks before it runs.
- Preferences. Launch at login, reopening running scripts, the global shortcut, failure, test and long-script notifications, a system, light or dark theme, the terminal font size, AI agent access, and Check for Updates. While macOS blocks ScriptDeck's notifications, an Allow button sits above their switches.
How it works
ScriptDeck is a Tauri 2 app: Rust for the processes, plain HTML and JS for the windows.
src-tauri/src/sessions.rs owns the PTYs: scrollback, stop escalation and URL detection.
src-tauri/src/project.rs reads and edits package.json and finds workspaces. node.rs resolves Node versions across nvm, fnm and Volta.
ui/ has no framework and no build step. The terminal is xterm.js, vendored in ui/vendor/.
src-tauri/src/update.rs updates the app from the latest GitHub release with the Tauri updater.
src-tauri/src/git/ runs the git command line, never through a shell, with your login shell's PATH and the project's Node, so hooks such as husky's work as in a terminal. Pulls are fast-forward only.
src-tauri/src/permission.rs asks macOS whether ScriptDeck may post notifications.
src-tauri/src/mcp.rs is the MCP server for AI agents. ScriptDeck --mcp, which an agent launches, pipes its stdio to a Unix socket the app opens in its config folder while the switch is on.
- Projects and settings live in
config.json in the app's config folder: ~/Library/Application Support/com.scriptdec.desktop/ on macOS, %APPDATA%\com.scriptdec.desktop\ on Windows. The bundle identifier keeps the app's old name, ScriptDec: changing it would move this folder, and installed apps would lose their projects and settings.
No telemetry. ScriptDeck has no account and no analytics. On its own it only fetches the latest release's latest.json from GitHub, at most every six hours, and it installs only updates signed with the release key. It only opens localhost links found in script output.
Build from source
You need Rust, Node.js with pnpm, and the Tauri prerequisites for your OS.
git clone https://github.com/svichas/ScriptDeck.git
cd ScriptDeck
pnpm install
pnpm dev | Runs the app with your changes. Reload a window from its right-click menu to pick up UI changes; Rust changes rebuild and restart the app. |
pnpm test | Runs the Rust tests. |
pnpm build | Builds ScriptDeck.app (an NSIS installer on Windows) into src-tauri/target/release/bundle/. |
pnpm dmg | Builds the app and a disk image, macOS only. It skips the Finder step that arranges the icons, the usual reason DMG builds fail. |
Troubleshooting
macOS says ScriptDeck can't be opened
The app is ad-hoc signed, not notarized by Apple, so macOS blocks the first launch. Open it once, then click Open Anyway in System Settings › Privacy & Security.
I installed it with Homebrew: how do I update or remove it?
ScriptDeck updates itself, so brew upgrade leaves it alone. To remove it, run brew uninstall --cask scriptdeck. Add --zap to delete its settings and caches too.
Windows SmartScreen warns about the installer
The installer isn't signed. Click More info, then Run anyway.
A script works in my terminal but not in ScriptDeck
Scripts run through your login shell, so they get the same PATH. Check which Node version the project uses in its settings: a project's .nvmrc wins over your default. If it still fails, open a bug report with the script's command and package manager.
My global shortcut doesn't work
It needs Ctrl, Option or Cmd. If another app already uses the combination, ScriptDeck says it can't use it: record a different one.
I don't get notifications
Open Settings › Preferences. While macOS blocks ScriptDeck's notifications, an Allow button sits above the switches. After an earlier Don't Allow, it opens System Settings › Notifications, where you can switch ScriptDeck back on. Nothing is posted while ScriptDeck's terminal window is in front, since you're already watching.