{"slug": "tokendeck-coding-agents-usage-management-consol", "title": "TokenDeck – Coding Agents Usage Management Consol", "summary": "Stigg released TokenDeck, a free desktop app for macOS 12+ and Windows 10/11 that maps Claude Code, Codex and OpenCode sessions onto a Stream Dock N3 deck's six screen keys, three metal buttons and three knobs, letting users jump to the session that needs attention and see how much of their 5-hour and weekly usage limits they have consumed. The app runs from the menu bar or system tray, connects to the deck over USB, requires no account and collects no telemetry, and installs via a curl script or unsigned disk images and an unsigned Windows .exe that trigger macOS quarantine and SmartScreen warnings. TokenDeck adds its hooks and status line to ~/.claude/settings.json with a backup, and on macOS requires Accessibility and Automation permissions so the deck can bring windows to the front.", "body_md": "Token Deck is the free desktop app for the deck in the After Tokens box: a Stream Dock N3 with six screen keys, three metal buttons and three knobs. It puts your Claude Code, Codex and OpenCode sessions on the keys and takes you to the one that needs you. It also sets the model, effort and permission your next session starts with, and shows how much of your 5-hour and weekly limits you've used.\n\nIt runs on macOS and Windows, lives in the menu bar (the system tray on Windows) and talks to the deck over USB. There's no account and no telemetry.\n\n**Download:** [usage.stigg.io](https://usage.stigg.io) (`io.stigg.io/usage`, the address printed on the box and the deck, leads there) · [All releases](https://github.com/stiggio/token-deck/releases)\n\nmacOS 12 or later, on Apple silicon or Intel. Paste this into Terminal:\n\n```\n/bin/bash -c \"$(curl -fsSL https://usage.stigg.io/install.sh)\"\n```\n\nThe [script](https://github.com/stiggio/token-deck/blob/main/site/install.sh) downloads the build for your Mac from the latest release, checks its SHA-256, quits Token Deck if it's running, installs it in `/Applications` (or `~/Applications` when `/Applications` isn't writable) and opens it. It doesn't use `sudo`.\n\nToken Deck isn't notarized by Apple yet. The install command works anyway, because `curl` doesn't mark the download as quarantined. The disk images ([Apple silicon](https://github.com/stiggio/token-deck/releases/latest/download/TokenDeck-mac-arm64.dmg), [Intel](https://github.com/stiggio/token-deck/releases/latest/download/TokenDeck-mac-x64.dmg)) are quarantined, so macOS refuses to open the app or says it's damaged. After you drag it to Applications, run this and open it again:\n\n```\nxattr -d com.apple.quarantine \"/Applications/Token Deck.app\"\n```\n\nWindows 10 or 11, 64-bit. Download and run [TokenDeck-win-x64.exe](https://github.com/stiggio/token-deck/releases/latest/download/TokenDeck-win-x64.exe). The installer isn't code-signed yet, so SmartScreen says \"Windows protected your PC\": choose **More info**, then **Run anyway**.\n\nIf the deck maker's StreamDock or VSD Craft app is running, quit it before you plug in the deck. Only one program can use the deck at a time.\n\nThe first time Token Deck starts, it offers three steps. You can skip any of them and do it later in the app's window, which opens from the menu bar or tray icon: Claude Code and the macOS permissions are on its This Mac page, and starting at login is on its About page.\n\n1. Connect Claude Code. Token Deck adds its hooks and status line to `~/.claude/settings.json` , next to anything you already have, and keeps a backup ([details](#claude-code) ).\n2. On macOS, grant Accessibility and Automation, so the deck can bring windows to the front.\n3. Start Token Deck at login.\n\nThe three metal buttons under the keys pick the mode, and the deck remembers the last one.\n\n| Button | Mode | What the keys show | \n|---|---|---|\n| Left | [Agents](#agents) | Claude Code, Cursor, Codex, OpenCode, Amp and Devin | \n| Middle | [Sessions](#sessions) | Your live Claude Code, Codex and OpenCode sessions, newest first | \n| Right | [Models & Usage](#models--usage) | Your 5-hour and weekly usage, then up to five models | \n\nHold the middle button to open [your own modes](#your-own-modes).\n\nTurning a knob shows a short message across the top row of keys for 5 seconds, like `SONNET` `NEXT` `SESSION`. Key presses are ignored while a message is showing. `NOT AVAILABLE` means the agent can't do what you asked; `NONE INSTALLED` means none of Claude Code, Codex or OpenCode is installed.\n\nPress a key to go to that agent's latest session or window, or to open it if it isn't running. A dim key means the app isn't installed. Claude Code opens in the Claude desktop app when you have it, and in Terminal otherwise. Amp's key opens VS Code, and Devin's opens [app.devin.ai](https://app.devin.ai).\n\nThe left and right knobs act on the last of Claude Code, Codex or OpenCode whose key or session you pressed, or the first one installed.\n\n| Control | Turn | Press | \n|---|---|---|\n| Big knob | Hop between the open agent windows | Back to the previous window | \n| Left knob | The model your next session starts with | Back to the agent's default model | \n| Right knob | The effort your next session starts with | Back to the agent's default effort | \n\nEach key is one recent session, newest first. The dot shows what it's doing, and the ring shows how full its context window is. Only Claude Code reports context, so Codex and OpenCode sessions get a dashed ring.\n\n| Dot | Status | \n|---|---|\n| Blue | Working | \n| Coral, with a frame around the key | Needs your approval | \n| White | Waiting for your reply | \n| Gray | Idle | \n| Lime | Done | \n\nPress a key to jump to that session's window, and Models & Usage then shows that session's agent. Token Deck finds the exact tab in Terminal, iTerm2 and Ghostty, the right window in VS Code and Cursor, or the session in the Claude desktop app; for other terminals it brings the app forward. For Codex and OpenCode it looks for the terminal running the agent in that session's folder, and a Codex session without one opens in the Codex app. A finished Claude Code session that isn't running anymore reopens in Terminal, in its own folder, with `claude --resume`. When there's no window to go to, the deck shows `FAILED`. On Windows, Token Deck brings Windows Terminal forward, without picking the tab.\n\n| Control | Turn | Press | \n|---|---|---|\n| Big knob | The next or previous six sessions | The next page with a session that needs you | \n| Left knob | Filter by agent | All agents | \n| Right knob | Filter by status: all, working, needs you, idle, done | All statuses | \n\nOpenCode sessions show up while `opencode serve` is running (Token Deck looks at `http://127.0.0.1:4096` and uses `OPENCODE_SERVER_PASSWORD` if you set one). OpenCode 2.x is found through its own service file.\n\nThe deck never approves a tool call. Pressing a session that needs approval takes you to its window, and you decide there.\n\nModels & Usage shows one agent at a time; the left knob switches between Claude Code, Codex and OpenCode. The first key shows how much of that agent's 5-hour (`5H`) and weekly (` 7D`) limits you've used. Press it to see the exact numbers and reset times in the app's window. The other keys are up to five of its models, with the current one in lime. Press a model and your next session starts on it.\n\n| Control | Turn | Press | \n|---|---|---|\n| Big knob | Effort | Ultracode on or off (Claude Code) | \n| Left knob | Agent | Back to the agent of the last session you opened | \n| Right knob | Permission: `READ` ,`ASK` ,`AUTO` ,`FULL` | Apply it | \n\nTurning the right knob only previews a permission level; nothing changes until you press it (a press before any turn just shows `TURN` `FIRST`), and `FULL` waits until you confirm it in a dialog on the computer. Model, effort and permission changes go into the agent's own settings file and apply from your next session, and the deck confirms each one, like `SONNET` `NEXT` `SESSION` or `HIGH` `EFFORT`. Sessions that are already running keep what they started with.\n\nWhere the usage numbers come from:\n\n- **Claude Code** reports them in its status line on Pro and Max plans, after a session's first reply.\n- **Codex** reports them through`codex app-server` when you're signed in with ChatGPT. Token Deck asks once a minute.\n- **OpenCode** doesn't report limits, so the key shows`--` .\n\nThe deck shows the last reading it got for up to 24 hours, then `--`, and drops a window as soon as its reset time passes. On Windows, Claude Code's status line isn't installed yet, so its usage and context don't show there.\n\nThe models come from each agent: Claude Code's model list (Opus, Sonnet, Haiku and Fable until it has one), the models Codex offers you, and OpenCode's configured model followed by its providers' models. Reorder them on the app's Models page.\n\nWhat each permission level writes:\n\n| Deck | Claude Code `permissions.defaultMode` | Codex `sandbox_mode` ,`approval_policy` | OpenCode 1.x `permission` | \n|---|---|---|---|\n| `READ` | `plan` | `read-only` ,`on-request` | edit `ask` , bash`ask` | \n| `ASK` | `default` | `workspace-write` ,`on-request` | edit `allow` , bash`ask` | \n| `AUTO` | `auto` | `workspace-write` ,`never` | edit `allow` , bash`allow` | \n| `FULL` | `bypassPermissions` | `danger-full-access` ,`never` | edit `allow` , bash`allow` | \n\nClaude Code's effort levels are `low`, `medium`, `high` and `xhigh`. Codex offers whichever levels the selected model supports. Token Deck writes Claude Code's as `modelSettings.<model>.effortLevel`, or as `effortLevel` before Claude Code 2.1.251.\n\nThe app's window has a simulator: the deck drawn at the bottom shows the same key images and behaves like the real one. Click a key, or use the keyboard:\n\n| Key | Does | \n|---|---|\n| `1` to`6` | Press a screen key | \n| `Q`` W``E` | Press the left, middle or right metal button (hold Shift to hold it, which opens your own modes from the middle button) | \n| `←``→` | Turn the big knob | \n| `↑``↓` | Turn the left knob | \n| `,``.` | Turn the right knob | \n| `Enter` | Press the big knob (Shift: the left knob, Option: the right knob) | \n\nA mode is a JSON file in `~/.tokendeck/modes/`. Hold the middle button and the keys list your modes, up to six; press one to open it. Any metal button takes you back. With no mode files, holding the middle button just opens Sessions. Token Deck reloads a file when you save it, even while that mode is open, and the app's Deck page lists any problems in your files. If you save a mistake while the mode is open, the keys stay as they were and the deck shows `MODE FILE` `ERROR` until you fix it.\n\n```\n{\n  \"name\": \"Deploy\",\n  \"tiles\": [\n    { \"label\": \"BUILD\", \"icon\": \"~/icons/hammer.svg\",\n      \"action\": { \"type\": \"shell\", \"command\": \"npm run build\", \"cwd\": \"~/dev/app\" } },\n    { \"label\": \"LOGS\", \"action\": { \"type\": \"url\", \"url\": \"https://grafana.example.com/d/abc\" } },\n    { \"label\": \"EDITOR\", \"action\": { \"type\": \"open\", \"app\": \"Cursor\" } },\n    { \"label\": \"PALETTE\", \"action\": { \"type\": \"keys\", \"keys\": \"cmd+shift+p\" } },\n    { \"label\": \"AGENTS\", \"action\": { \"type\": \"mode\", \"mode\": \"agents\" } },\n    null\n  ],\n  \"knobs\": {\n    \"main\": {\n      \"cw\": { \"type\": \"keys\", \"keys\": \"cmd+=\" },\n      \"ccw\": { \"type\": \"keys\", \"keys\": \"cmd+-\" },\n      \"click\": { \"type\": \"shell\", \"command\": \"say done\" }\n    },\n    \"left\": null,\n    \"right\": null\n  }\n}\n```\n\n`tiles` holds up to six keys, left to right and top to bottom; `null` leaves a key empty, and pressing an empty key or turning a knob with no action shows `FAILED`. A label is shown in capitals, one word per line, two lines at most. `icon` is an optional PNG or SVG, drawn at 28 pixels. `knobs` maps `main` (the big knob), `left` and `right` to an action for `cw` (clockwise), `ccw` (counter-clockwise) and `click`.\n\n| Action | Fields | Does | \n|---|---|---|\n| `shell` | `command` , optional`cwd` | Runs the command in your login shell ( `zsh -lic` on macOS,`cmd /c` on Windows), for up to 10 seconds. The deck shows`OK` or`FAILED` . | \n| `open` | `app` | Opens an app by name. | \n| `url` | `url` | Opens a link in your browser. | \n| `keys` | `keys` | Sends a shortcut to the app in front. On macOS write it like `cmd+shift+p` (`cmd` ,`ctrl` ,`opt` ,`shift` ). On Windows the string goes to`SendKeys` as is, so use its syntax:`^+p` . | \n| `mode` | `mode` | Switches to `agents` ,`sessions` or`models` . | \n\nToken Deck changes three files that belong to other apps: Claude Code's `~/.claude/settings.json`, Codex's `~/.codex/config.toml` and OpenCode's `~/.config/opencode/opencode.json`. It backs each one up before its first change, and every change replaces the whole file in one step, so the agent never reads half a file. A file that's a symlink, as in a dotfiles repository, stays a symlink. Token Deck leaves alone a file it can't read, and a JSON file it can't parse.\n\nFrom launch, Token Deck reads `claude agents --json --all` every two seconds, plus the session files under `~/.claude/sessions` and `~/.claude/projects`, to list your sessions, and the list of running processes to see which model each session runs. It never reads Claude Code's credentials; `claude auth status --json` tells it whether you're signed in.\n\nWhen you connect Claude Code (in the first-run setup, or on the app's This Mac page), Token Deck:\n\n1. Copies `~/.claude/settings.json` to`~/.claude/settings.json.tokendeck-backup` . This happens once; reconnecting keeps the first backup.\n2. Writes two small scripts, `~/.tokendeck/bin/hook` and`~/.tokendeck/bin/statusline` (`hook.ps1` on Windows).\n3. Sets its hook on seven events in `settings.json` :`UserPromptSubmit` ,`Stop` ,`Notification` ,`PermissionRequest` and`PostModelSwitch` run in the background, and`SessionStart` and`SessionEnd` run with a two-second limit. Token Deck adds its hook next to any hooks you already have on those events. The hook is a`command` hook that exits at once when Token Deck isn't running, so a quit or crashed app never shows hook errors in your sessions.\n4. Points the status line at `~/.tokendeck/bin/statusline` (macOS only). Your previous status line is saved in`~/.tokendeck/statusline-original.json` , with its command in`~/.tokendeck/statusline-original` , and the script runs that command with the same input, so your status line looks the same. The script also keeps the latest status line data in`~/.tokendeck/last-statusline.json` , which is where the context ring and usage numbers come from.\n\n**Stop watching** on the This Mac page takes Token Deck's hooks out and puts your previous status line back, and leaves everything else in `settings.json` as it is now. The backup from your first connect stays next to it if you ever want to go further back.\n\nToken Deck never writes a `settings.json` it can't parse: if the file isn't valid JSON, it leaves it alone and tells you.\n\nWhen you turn a knob, Token Deck writes `model`, the effort setting, `permissions.defaultMode` or `ultracode` in `settings.json`, keeping everything else in the file.\n\nToken Deck runs `codex app-server` in the background to read your sessions, models and usage limits. It never answers an approval request; you approve in Codex.\n\nA knob writes the top-level `model`, `model_reasoning_effort`, `sandbox_mode` and `approval_policy` lines in `~/.codex/config.toml`. It edits those lines in place and adds missing ones at the top, so other comments and settings stay as they are, and it never touches `notify`. Before the first edit it copies the file to `~/.codex/config.toml.tokendeck-backup`; to undo, copy that file back.\n\nToken Deck reads sessions and the available models from the OpenCode server. A knob writes `model` in `~/.config/opencode/opencode.json`, and on 1.x sets `edit` and the default `bash` rule in its `permission` map, keeping your per-command rules. Before the first change it copies the file to `opencode.json.tokendeck-backup`. If the file has comments, which Token Deck can't keep, the deck says `NOT AVAILABLE` and the file stays as it is. If you set `OPENCODE_SERVER_PASSWORD` in your shell profile, Token Deck reads it from your login shell.\n\nTheir keys only open or focus the app. Token Deck doesn't read or change anything of theirs.\n\nTo bring a window to the front, macOS asks once for Automation for each app Token Deck controls (Terminal, iTerm2, System Events and so on), and once for Accessibility under System Settings → Privacy & Security. Custom-mode keystrokes use the same permissions. Updates on macOS may ask again, because Token Deck isn't signed.\n\n- Hooks reach the app through a server on `127.0.0.1` only, on a random port, behind a random per-install token in the path. Its address is in`~/.tokendeck/url` while the app runs.\n- Token Deck only goes online for updates: it checks this repository's GitHub releases when it starts, Windows downloads a new version in the background, and Update now on a Mac runs the install script from `usage.stigg.io` .\n- There's no telemetry. The log stays on your computer, in `~/.tokendeck/log/tokendeck.log` , rotated at 5 MB.\n\nToken Deck's own files are in `~/.tokendeck`: `settings.json` (the app's own settings), `log/`, `bin/`, `modes/`, `url` and the status line files above. The backups sit next to the files they back up, and Electron keeps a cache in `~/Library/Application Support/Token Deck` (`%APPDATA%\\Token Deck` on Windows).\n\n**The deck only shows the welcome screen.** Check that Token Deck is running: look for its icon in the menu bar or the system tray. Then unplug the deck and plug it back in. The app's Deck page shows the connection state.\n\n**\"Quit the StreamDock or VSD Craft app to use Token Deck.\"** Another program has the deck. Quit it and replug the deck.\n\n**\"Deck not responding. Unplug it and plug it back in.\"** The deck stopped answering. Replugging resets it.\n\n**A key doesn't bring the window forward.** Give Token Deck Accessibility in System Settings → Privacy & Security, and allow the Automation prompts. The app's This Mac page says when Accessibility is missing.\n\n**The usage key shows `--`.** Claude Code only reports limits on Pro and Max plans, after a session's first reply, and only through the status line, so connect Claude Code first. Codex needs a ChatGPT sign-in. OpenCode has no limits to show.\n\n**Codex keys say `NOT AVAILABLE`.** Token Deck couldn't reach `codex app-server`. Check that `codex` runs in your terminal and that you're signed in.\n\n**macOS says the app is damaged.** See the disk image note under [Install](#macos).\n\n**Logs.** About → Show log opens `~/.tokendeck/log/tokendeck.log`.\n\n**Uninstall.** Click Stop watching on the This Mac page to take Token Deck out of your Claude Code settings. Quit Token Deck from its menu and delete the app (on Windows, from Settings → Apps). Delete `~/.tokendeck` and the Electron cache folder above to remove the rest. If you changed Codex or OpenCode defaults from the deck, the originals are in `~/.codex/config.toml.tokendeck-backup` and `~/.config/opencode/opencode.json.tokendeck-backup`.\n\n- On Windows, Token Deck doesn't chain Claude Code's status line, so Claude Code's context ring and usage don't show there. Claude Code's own status line support on Windows is still unreliable, and a broken chain would blank yours.\n- On OpenCode 2.x, the deck can't change the permission setting yet; it says `NOT AVAILABLE` .\n\nThe deck keeps one picture in its own memory: the welcome screen with the Stigg logo, `io.stigg.io/usage` and the After Tokens token explosion. It shows whenever the deck has power and no app is driving it, on any computer. The decks in the After Tokens boxes came with it, and Token Deck writes it once to any deck it hasn't seen before. The About page can write it again, or turn the automatic write off.\n\nHow the write works, the batch tool the Stigg team used to prepare the giveaway decks, and how to recover a deck that starts up black are in [docs/welcome-screen.md](https://github.com/stiggio/token-deck/blob/main/docs/welcome-screen.md).\n\nYou need Node 22 and npm. The app runs on macOS and Windows; the tests and the site build also run on Linux.\n\n```\nnpm install\nnpm run dev\nnpm test\n```\n\n`npm run dev` starts the app with the settings window and the simulator. `npm test` runs the unit tests: the protocol (including that no frame Token Deck can send clears the deck or puts it to sleep), the input decoder against a real capture, the write queue, the welcome-screen write sequence, JPEG encoding and the tile renderer. With a deck plugged in and the app quit, `TOKENDECK_DEVICE=1 npm test` also runs the hardware test.\n\n| Command | Does | \n|---|---|\n| `npm run build` | Compiles the app into `out/` and runs the font check | \n| `npm run dist:mac` | Builds the macOS disk images and zips (Apple silicon and Intel) | \n| `npm run dist:win` | Builds the Windows installer | \n| `npm run site` | Renders the site's tiles and writes `site/index.html` | \n| `npm run icons` | Rebuilds the tray icons | \n\n**Releases.** Pushing a `v*` tag runs `.github/workflows/release.yml`: it builds both platforms, starts each build once with `--smoke` to check the native modules and resources, and publishes the release. The file names never change (`TokenDeck-mac-arm64.zip`, `TokenDeck-win-x64.exe` and so on), so the download links always point at the latest release. The macOS builds are unsigned; adding the `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD` and `APPLE_TEAM_ID` secrets turns on signing, notarization and the built-in updater.\n\n**The site.** `site/` is the page at [usage.stigg.io](https://usage.stigg.io), published by GitHub Pages (`.github/workflows/pages.yml`) when `main` changes. `scripts/export-site-tiles.ts` renders the device tiles with the app's own renderer, and `scripts/build-site.mjs` writes `index.html` around `site/style.css` and `site/main.js`. The page uses only Stigg's Söhne, loaded from the same CDN files stigg.io uses; if marketing re-uploads those fonts in Webflow, update the four URLs at the top of `build-site.mjs`.\n\n**Fonts.** Söhne's license doesn't allow it in the app or in this repository, so the app uses Geist and the tiles use a bitmap font drawn in code. `node scripts/lint-fonts` fails if a Söhne file, or any font other than Geist, is committed or packaged.\n\n**Command line.** The app binary also takes a command, run with the tray app quit:\n\n```\nalias tokendeck='\"/Applications/Token Deck.app/Contents/MacOS/Token Deck\"'\n```\n\n| Command | Does | \n|---|---|\n| `tokendeck probe` | Lists the decks plugged in, with serial number and firmware | \n| `tokendeck burn --watch` | Writes the welcome screen to every deck you plug in, one after another ( [docs](https://github.com/stiggio/token-deck/blob/main/docs/welcome-screen.md#preparing-many-decks) ) | \n| `tokendeck calibrate` | Not implemented yet; prints where the calibration image is | \n\nOn Windows the binary is `Token Deck.exe` in the install folder.\n\n| Path | What's there | \n|---|---|\n| `src/main/deck/` | USB transport, protocol, write queue and the tile renderer | \n| `src/main/integrations/` | Claude Code, Codex, OpenCode, and the launch-only agents | \n| `src/main/modes/` | The mode controller and custom modes | \n| `src/main/burn/` ,`src/main/cli.ts` | The welcome-screen write and the command line | \n| `src/renderer/` | The settings window and the simulator (React) | \n| `resources/` | The welcome screen, panel geometry, agent glyphs and tray icons | \n| `site/` ,`scripts/` | The download page and the build scripts | \n| `brand-kit/` ,`assets/` | The box design kit the app and site are drawn from | \n\n[PLAN.md](https://github.com/stiggio/token-deck/blob/main/PLAN.md) is the original build plan with every decision behind the app. The shipped app differs from it in places (Models & Usage leads with the usage key, for example); the code and this README describe what ships. How Token Deck talks to the deck, and what was measured on real hardware, is in [docs/hardware.md](https://github.com/stiggio/token-deck/blob/main/docs/hardware.md).\n\nThe code is MIT licensed, © Stigg. The Stigg logos, marks and app icon are not covered by that license, and the agent logos belong to their owners; see [BRAND-ASSETS.md](https://github.com/stiggio/token-deck/blob/main/BRAND-ASSETS.md).", "url": "https://wpnews.pro/news/tokendeck-coding-agents-usage-management-consol", "canonical_source": "https://github.com/stiggio/token-deck", "published_at": "2026-11-10 16:39:39+00:00", "updated_at": "2026-11-10 17:00:21.844429+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "ai-products"], "entities": ["TokenDeck", "Stigg", "Claude Code", "Codex", "OpenCode", "Stream Dock N3", "Cursor", "Amp"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/tokendeck-coding-agents-usage-management-consol", "markdown": "https://wpnews.pro/news/tokendeck-coding-agents-usage-management-consol.md", "text": "https://wpnews.pro/news/tokendeck-coding-agents-usage-management-consol.txt", "jsonld": "https://wpnews.pro/news/tokendeck-coding-agents-usage-management-consol.jsonld"}}