timharris707/modeldeck installation guide

Install ModelDeck on macOS Tahoe (Apple silicon)

What ModelDeck is

**Classification: standalone companion application (`runs_alongside` Claude Code), not a Claude Code extension.**

ModelDeck is a native SwiftUI menu-bar app with a bundled local Node.js daemon. It does not install a Claude Code plugin, skill, hook, or MCP server. Instead, it runs beside Claude Code and Codex CLI, reads usage and authentication state through provider-supported channels, and can activate isolated account profiles for **new** terminal sessions. Existing sessions are not stopped, logged out, or changed.

Its main purpose is to show remaining rate-limit capacity, reset times, account health, and low-capacity warnings for multiple Claude Code and Codex accounts. It can also switch which account is active for future CLI sessions.

The repository documents support for **macOS 14 or newer**, so macOS Tahoe meets the stated operating-system requirement. No Apple-silicon-specific setup or Rosetta requirement is documented. This guide therefore uses the normal signed DMG installation described by the project.

Before you begin

You need:

• A Mac running macOS Tahoe.
• At least one of the command-line tools ModelDeck can track: **Claude Code and/or Codex CLI**.
• A provider account for each profile you plan to add.
• Permission to place an app in the Applications folder and approve its bundled background service.

The supplied repository files do not document installation commands for Claude Code or Codex CLI, so this guide does not provide any. Install and sign into the CLI or CLIs you want to use through their own official instructions before setting up ModelDeck.

You do **not** need to install Node.js when using the released DMG. Node.js 24 or newer is required only for building the daemon from source.

1. Download the official release

Open the project’s public Releases page in your web browser:

<https://github.com/timharris707/modeldeck/releases>

Choose the latest signed, notarized DMG release asset and download it. The repository identifies the Releases page as the supported download source; it does not document a Homebrew installation command, so do not guess one from the presence of Homebrew uninstall instructions.

When the download finishes, find the DMG in your browser’s downloads list or in Finder’s **Downloads** folder.

2. Install the application

1. Double-click the downloaded DMG to open it.
2. In the installer window, drag **ModelDeck** to **Applications**.
3. Wait for Finder to finish copying the app.
4. Open Finder, select **Applications**, and double-click **ModelDeck**.

The project says its release DMG is signed, notarized, and self-contained. On first launch, ModelDeck asks for consent to register its bundled background service. Approve that request if you want the app to function. This local daemon performs the usage reads and listens only on `127.0.0.1:3867`, meaning the documented default listener is available from your Mac itself rather than other computers on the network.

The first launch also creates ModelDeck’s local Keychain authorization token. The normal DMG path requires one approval and no Terminal work.

If macOS presents an ordinary security or notification prompt, read it and make your own choice. The repository specifically documents lazy notification authorization: ModelDeck asks when notifications are needed rather than requiring notification access merely to install.

3. Add your first account

After ModelDeck launches, look for its icon in the macOS menu bar.

1. Open ModelDeck.
2. Go to **Settings → Accounts**.
3. Select **Add Account**.
4. Give the account a recognizable local name, such as “Work” or “Personal.”
5. Follow the provider’s own browser sign-in flow.
6. Return to ModelDeck and confirm the identity it reads back.

Repeat these steps for every Claude Code or Codex account you want to track.

ModelDeck says each added account receives an isolated profile home. Claude profiles use `CLAUDE_CONFIG_DIR`, while Codex profiles use `CODEX_HOME`. Provider credentials remain in the provider-managed profile or macOS Keychain. According to the project, ModelDeck uses those credentials in place for usage and authentication-state reads but does not copy or persist them itself.

Take care during each browser sign-in. If two profiles accidentally use the same provider credential, ModelDeck is designed to show a duplicate-token warning rather than silently treating them as independent capacity.

4. Understand account activation

ModelDeck can designate one active account per provider. Activating an account changes the isolated profile home used by **new terminal sessions**. It does not interrupt terminal sessions that are already running.

After activation, ModelDeck verifies the result and reports one of these documented states:

• `effective` — the intended identity is active.
• `identity-mismatch` — verification found a different identity.
• `identity-unverified` — ModelDeck could not verify the identity.

Do not assume a switch succeeded merely because you clicked it; check the state shown by the app. If an account displays **Sign in again**, use the account flow to restore the provider-managed sign-in.

5. Configure everyday behavior

In **Settings → General**, review the available controls. The repository documents settings for:

• Refresh cadence.
• One- or two-column layout.
• Sorting by next reset, lowest remaining capacity, or provider.
• Low-capacity notification threshold.
• Menu-bar percentage behavior.
• Launch at login.
• Update checking and automatic installation.

ModelDeck can show a plain menu-bar glyph while accounts are healthy, a gold percentage when capacity is low, and red when critical. You can also pin one account—or the currently active account—so its percentage remains visible.

Notifications are transition-based: the app alerts when remaining capacity crosses a configured threshold, then stays quiet until capacity recovers and crosses again.

Launch at login and notifications require the assembled application bundle supplied by the DMG. The repository notes that these features do not work from a bare `swift run` development binary.

6. Choose your update preference

Update checks are documented as off until you enable them. When enabled, ModelDeck checks this repository’s public release feed daily. If an update is available, **Update Now** downloads it, verifies its EdDSA and Apple signatures, installs it, and relaunches the app.

The project says an **Install updates automatically** option is on by default once update checks are enabled; it installs an available update quietly on the next relaunch. Review these settings rather than assuming the behavior you prefer. If update checks remain off, ModelDeck says it does not make those release-feed calls.

7. Confirm the installation works

A successful setup should provide these visible signs:

• ModelDeck remains available from the menu bar.
• Added accounts appear as cards in the deck.
• Each readable limit window shows a remaining percentage and reset time.
• Account health indicates **Healthy** or explains that another sign-in is required.
• Activating an account produces an honest verification state.
• Settings changes are reflected in the popover or menu-bar display.

The daemon serves cached health, state, settings, and tool information to the app. A read-only usage dashboard may also be available through the app when the `usageAnalyticsEnabled` setting is enabled; the repository describes it as the only remaining browser page.

Privacy and local data

The project describes ModelDeck as local-first, with no cloud backend and no telemetry. Its daemon stores state in an owner-only SQLite database under:

`~/Library/Application Support/ModelDeck/`

ModelDeck creates its own local Keychain token for the daemon API. If you use the managed proxy, it also creates one local client key per profile. The project says these items contain no provider credentials. Normal outbound provider calls use credentials already held by the corresponding provider profile. Optional ModelDeck-originated network activity consists of the update check and an update download you approve.

Removing an account from ModelDeck deletes its reference, not the provider’s Keychain entries or general provider authentication state. However, deleting ModelDeck’s application-support directory later also deletes the isolated managed profile homes created inside it.

If you need to uninstall

1. Right-click the ModelDeck menu-bar icon and choose **Quit ModelDeck**.
2. Open **Applications** in Finder.
3. Drag ModelDeck to the Trash.

The repository says the bundled background service and launch-at-login entry live inside the app bundle, so removing the application removes them without Terminal commands. Your ordinary `~/.claude` and `~/.codex` directories remain untouched.

To remove remaining local data, use Finder to delete the documented ModelDeck items only after deciding you do not need their settings, usage history, or managed profile homes. Keychain cleanup can be done manually in **Keychain Access** by searching for `modeldeck` and `cli-proxy-api-client`. Manual cleanup is safer for a layperson than substituting profile names into shell commands.

ModelDeck is source-visible under the PolyForm Noncommercial License 1.0.0 and is described as free for personal, noncommercial use. Commercial rights are reserved by the author.