{"id":50549831,"url":"https://github.com/alejandrosnz/claude-deck","last_synced_at":"2026-06-04T02:30:20.996Z","repository":{"id":357644831,"uuid":"1237034422","full_name":"alejandrosnz/claude-deck","owner":"alejandrosnz","description":"An OpenDeck / Stream Deck plugin that shows Claude Code usage stats","archived":false,"fork":false,"pushed_at":"2026-05-21T05:42:23.000Z","size":1433,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-21T12:13:40.426Z","etag":null,"topics":["claude","open-deck","stream-deck","stream-deck-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alejandrosnz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-12T20:13:37.000Z","updated_at":"2026-05-19T19:52:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alejandrosnz/claude-deck","commit_stats":null,"previous_names":["alejandrosnz/claude-deck"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/alejandrosnz/claude-deck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrosnz%2Fclaude-deck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrosnz%2Fclaude-deck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrosnz%2Fclaude-deck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrosnz%2Fclaude-deck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alejandrosnz","download_url":"https://codeload.github.com/alejandrosnz/claude-deck/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrosnz%2Fclaude-deck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33887124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","open-deck","stream-deck","stream-deck-plugin"],"created_at":"2026-06-04T02:30:19.542Z","updated_at":"2026-06-04T02:30:20.971Z","avatar_url":"https://github.com/alejandrosnz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-deck\n\nAn OpenDeck / Stream Deck plugin that shows Claude Code usage stats on your control surface and (in the future) lets you control Claude Code directly from hardware buttons.\n\n![Claude Deck Cover](docs/images/cover_image.png)\n\n\u003e Compatible with **OpenDeck** (Windows, Linux, macOS) and the official **Elgato Stream Deck** software.\n\n[![Latest Release](https://img.shields.io/github/v/release/alejandrosnz/claude-deck)](https://github.com/alejandrosnz/claude-deck/releases/latest)\n\n---\n\n## What it does\n\n### Current actions\n\n| Action | Controller | Description |\n|---|---|---|\n| **Usage 5h** | Keypad | Shows the rolling 5-hour token usage as a percentage and time-to-reset. Button colour shifts green → amber → red as the limit approaches. |\n| **Usage 7d** | Keypad | Shows the rolling 7-day token usage as a percentage and time-to-reset. Same colour logic. |\n\nBoth buttons refresh automatically every 2 minutes and on press (manual refresh).\n\n### Planned actions (future versions)\n\n| Action | Controller | Description |\n|---|---|---|\n| **Accept** | Keypad | Sends the \"yes / accept\" answer to Claude Code's current permission prompt. |\n| **Change Mode** | Keypad | Cycles between Claude Code modes: `plan` → `build` (auto/accept edits) → default. |\n| **Reject / Stop** | Keypad | Sends Ctrl+C to stop a running session. |\n\n---\n\n## Compatibility\n\n| Software | Status |\n|---|---|\n| **OpenDeck** (Linux, Windows, macOS) | Primary target |\n| **Elgato Stream Deck** software (Windows, macOS) | Supported — Node.js plugin |\n| **Tacto** (OpenAction derivative) | Should work |\n\nThe plugin is written as a **Node.js plugin** using the standard Stream Deck SDK v2 (`@elgato/streamdeck`). This makes it compatible with both OpenDeck (which supports Node.js plugins natively) and the official Elgato software.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- [OpenDeck](https://github.com/nekename/OpenDeck) installed, **or** the Elgato Stream Deck software (≥ 6.7)\n- Claude Code CLI installed and logged in (`claude login`)\n\n### From GitHub Releases (recommended)\n\n1. Go to the [Releases page](https://github.com/alejandrosnz/claude-deck/releases/latest) and download the `.streamDeckPlugin` file for the latest version.\n\n2. Install the plugin:\n\n**OpenDeck — via UI (all platforms)**\n\nOpen OpenDeck → Settings → **Plugins** tab → click **Add plugin** → select the downloaded `.streamDeckPlugin` file. Restart OpenDeck when prompted.\n\n**OpenDeck — manual install**\n\nThe `.streamDeckPlugin` file is a ZIP archive. Unzip it directly into the OpenDeck plugins directory and restart OpenDeck.\n\n*Linux / macOS:*\n```bash\nunzip claude-deck-\u003cversion\u003e.streamDeckPlugin -d ~/.config/opendeck/plugins/\n```\n\n*Windows:*\n```powershell\nExpand-Archive claude-deck-\u003cversion\u003e.streamDeckPlugin -DestinationPath \"$env:APPDATA\\opendeck\\plugins\\\"\n```\n\n**Elgato Stream Deck software (Windows / macOS)**\n\nDouble-click the `.streamDeckPlugin` file. The Stream Deck software opens automatically and installs it.\n\n3. Drag the **Usage 5h** or **Usage 7d** action from the action list onto any button slot.\n\n### From source\n\n```bash\ngit clone https://github.com/your-handle/claude-deck\ncd claude-deck/com.claudedeck.sdPlugin\nnpm install\nnpm run build\n```\n\nThen install the built plugin directory into your plugins folder using the manual steps above (the `com.claudedeck.sdPlugin` directory is the bundle).\n\n---\n\n## How to use\n\n1. Drag a **Usage 5h** or **Usage 7d** button onto any key slot in your profile.\n2. The button will show a loading indicator briefly, then display the current usage percentage and a colour-coded gauge.\n3. **Press the button** at any time to see how long until the usage window resets. The overlay stays for 10 seconds, or disappears immediately on a second press.\n\n\u003e **Prerequisite:** Claude Code must have been run at least once on this machine and you must be logged in (`claude login`). The plugin reads the OAuth credentials that Claude Code stores locally — if they do not exist yet, the button will stay in the loading state until they are created.\n\n---\n\n## How it works\n\n### Data source — Claude Code Usage API\n\nUsage data is fetched from the Anthropic API:\n\n```\nGET https://api.anthropic.com/api/oauth/usage\nAuthorization: Bearer \u003cclaude_code_oauth_token\u003e\nanthropic-beta: oauth-2025-04-20\n```\n\nResponse fields used:\n\n```jsonc\n{\n  \"five_hour\": { \"utilization\": 0.42, \"resets_at\": \"2026-05-12T18:00:00Z\" },\n  \"seven_day\": { \"utilization\": 0.15, \"resets_at\": \"2026-05-19T00:00:00Z\" }\n}\n```\n\n### Credential discovery (cross-platform)\n\nClaude Code stores OAuth credentials differently per OS:\n\n| Platform | Location |\n|---|---|\n| macOS | macOS Keychain, service `Claude Code-credentials` |\n| Linux / Windows | `~/.claude/.credentials.json` (JSON file written by Claude Code) |\n\nThe plugin reads the appropriate source at startup and whenever a fetch fails with a 401.\n\n### Poll strategy\n\n- Credentials are read once at startup and re-read on auth failure.\n- Usage is fetched every **120 seconds** (respects the Anthropic rate limit).\n- On 429, the plugin backs off (45 s → 90 s → 180 s → 300 s).\n- Results are cached in memory; the button updates immediately after each fetch.\n\n---\n\n## Development\n\n```bash\nnpm run dev        # watch mode — rebuilds on file change\nnpm run build      # production build\nnpm run lint       # ESLint\nnpm run typecheck  # tsc --noEmit\n```\n\n### Pre-commit checklist\n\n1. `npm run typecheck` — no TypeScript errors\n2. `npm run lint` — no ESLint violations\n3. `npm run build` — clean build\n4. Manual smoke-test: drag action onto a button and confirm it shows usage data\n\n---\n\n## Roadmap\n\n- [x] 5-hour usage widget\n- [x] 7-day usage widget\n- [ ] Accept button (send approval to current permission prompt)\n- [ ] Change mode button (plan / build / default cycle)\n- [ ] Reject / Stop button (Ctrl+C)\n- [ ] Usage history graph (mini sparkline on button image)\n- [ ] Configurable refresh interval via Property Inspector\n- [ ] Token / cost display variant\n\n---\n\n## Project structure\n\n```\nclaude-deck/\n├── com.claudedeck.sdPlugin/     # Plugin bundle (OpenAction .sdPlugin directory)\n│   ├── assets/\n│   │   ├── manifest.json        # Plugin manifest\n│   │   └── icons/               # Button icons (SVG + PNG)\n│   ├── src/\n│   │   ├── plugin.ts            # Entry point, registers actions\n│   │   ├── actions/\n│   │   │   ├── usage-5h.ts      # 5-hour usage button action\n│   │   │   └── usage-7d.ts      # 7-day usage button action\n│   │   ├── usage-api.ts         # Claude Code OAuth API client\n│   │   ├── credentials.ts       # Cross-platform credential reader\n│   │   └── renderer.ts          # Button image generator (Canvas/SVG)\n│   ├── package.json\n│   ├── rollup.config.mjs\n│   └── tsconfig.json\n├── README.md\n└── AGENTS.md\n```\n\n---\n\n## Acknowledgements\n\n- [AgentDeck](https://github.com/puritysb/AgentDeck) — reference implementation for Claude Code integration and usage API details\n- [OpenDeck](https://github.com/nekename/OpenDeck) — the OpenAction server this plugin targets\n- [OpenAction API](https://openaction.amankhanna.me/) — plugin API specification\n- [Elgato Stream Deck SDK v2](https://developer.elgato.com/documentation/stream-deck/sdk/overview/) — base SDK used by this plugin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrosnz%2Fclaude-deck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falejandrosnz%2Fclaude-deck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrosnz%2Fclaude-deck/lists"}