Download MasterDeck
Get started

From install to first session.

About ten minutes, most of it ticking repositories. Everything here is also in the README.

Requirements

ToolWhy
Claude Codeclaude on your PATH and logged in. MasterDeck runs your sessions with it.
GitHub CLIgh, logged in with the project scope, for issues, PRs and boards.
Python 3.9+The master CLI that keeps the ledger, board and config (python3; python on Windows).
git and jqBranches, worktrees and the hooks.

Missing something? Setup checks each tool and can install the missing ones for you (Homebrew on macOS, winget on Windows).

Install

macOS (Apple silicon and Intel)

Run this in Terminal. It downloads the right build from the latest release, puts it in /Applications and opens it. Run it again to update.

$ curl -fsSL https://raw.githubusercontent.com/amntoppo/MasterDeck-Terminal/main/install.sh | bash
Why a script? The app is not signed by Apple. A DMG downloaded in a browser is blocked until you allow it inSystem Settings → Privacy & Security → Open Anyway; a download by curl is not.

Prefer the DMG? Get MasterDeck-<version>-arm64.dmg (Apple silicon) or MasterDeck-<version>.dmg (Intel) from the download page.

Windows

Run MasterDeck Setup <version>.exe from the download page. It is not signed, so SmartScreen asks you to confirm: More info, then Run anyway.

From source

$ git clone https://github.com/amntoppo/MasterDeck-Terminal.git
$ cd MasterDeck-Terminal/app
$ npm install
$ npm run dev

First run

MasterDeck copies its skills into ~/.claude/skills/ (it never overwrites a skill folder you already have), then opens Setup:

  1. ToolsEach of claude, gh, Python, git and jq is checked. Install now opens a Claude session that installs what is missing; you approve each step.
  2. GitHub accountsEvery account gh is logged in to, each with a switch. Connect the ones MasterDeck should use and pick a primary. Add an account… runs gh auth login --web right there.
  3. Repos & boardsTick the repositories whose issues you work on and the project boards that track them, and pick the primary repository.
  4. PreferencesThe folder your repositories are in, whether to run a master-agent, and notifications.

Skip for now leaves GitHub unset: sessions still work, and the Board and PRs views offer Connect your GitHub later. Settings (⚙) → Set up MasterDeck opens the same steps again.

Connect GitHub and a board

MasterDeck uses your own gh login. Log in once, with the project scope so it can read and move board cards:

$ gh auth login
$ gh auth refresh -s project

Then in Setup → Repos & boards, one read lists every organization gh can reach, with its repositories and project boards. MasterDeck reads each board’s statuses and guesses which means ready, in progress, PR raised and done; correct a guess if it is wrong.

No GitHub project? Tick repositories only. The Board shows their issues in Todo / In Dev / PR Raised / Done, worked out by MasterDeck, and Create a GitHub board makes a real one from them when you want it.

Several accounts

Log in to each with gh auth login and connect them in Setup. Each gets a name and email for its commits and, optionally, its own workspace folder. MasterDeck never changes gh’s active account.

Your first session

  1. Open the Board and click a ticket with no session (○).
  2. The Start dialog says where the session will start (your checkout of the ticket’s repository), the account, model, permission mode and workflow. Optionally create a worktree first.
  3. Press Start. The tab opens by itself, the session is linked to the issue and the card moves to In Dev.

If Claude Code has never been opened in that folder it asks you to trust it first: Open Claude there… shows its prompt, and the Start dialog comes back once you accept.

The master-agent (the column on the right, ⌘⇧M) can do this for you: press Start master and it sweeps your issues and PRs and proposes sessions in Needs you for you to approve.

From a browser or phone

Optional, and off by default.

  1. In the desktop app, sign in under Settings → Account, then switch on Connect to the backend under Settings → Remote.
  2. Open app.masterdeck.dev and sign in with the same account.
  3. Your Mac asks whether to allow the browser, with three words. Allow it only if the browser shows the same three.

Everything between the browser and your Mac is end-to-end encrypted. On a phone you get a tab bar and a quick-key bar under the terminal. The Mac must be on with MasterDeck running.

Where settings live

Setup writes one file, ~/.claude/master/config.json, which the app, the master CLI and the skills all read. MasterDeck’s own data (costs, tokens, notes, workflows) is under ~/.claude/masterdeck/.

# print the current config
$ ~/.claude/skills/master/master config show

Next steps

  • Features: what each part of MasterDeck does.
  • The user guide: every feature in detail, keyboard shortcuts and Windows notes.
  • Releases: builds for every version.
  • Issues: a bug, a question or an idea.