ClauDeck User Guide

Kei

Use each step's "Done when" line as your checkpoint.

1. Show ClauDeck in the menu bar

   Open ClauDeck from the Applications folder and look for the deck-shaped icon in the menu bar at the top right of the screen.

   Done when: clicking the icon shows "このアプリについて…" (About this app) at the top, and the menu has a line starting with "Status:".

   Not there? Check "Allow in the Menu Bar" in System Settings.

2. Register your AI tools

   Open "Agent Integration" in the menu and choose the row for the AI you use (Claude Code, Codex, Antigravity). For Claude Code and Codex, review what will be added and press "入れる" (Install). For Antigravity, choose the integration level and press "適用" (Apply). No coding needed.

   Done when: Claude Code and Codex show "Registered", and Antigravity shows the level you chose.

   Antigravity settings not found? Launch Antigravity once, then try again.

3. Install the Stream Deck plugin

   Choose "Install Stream Deck Plugin…" in the menu, then quit and reopen the Stream Deck app as instructed. The plugin is the part that adds ClauDeck's actions to Stream Deck.

   Done when: "Status" in ClauDeck shows "Stream Deck: Connected (N seats)".

4. Place slots on the deck

   Find "ClauDeck Slot" in the Stream Deck app's action list and drag it onto any key. Then run "Test Buttons" from the ClauDeck menu to check it.

   Done when: the slot ID (such as c0r0) appears in the in-app guide. "AI Slot" is a different plugin, so do not mix them up.

5. Check the approval mode

   Look at "Mode" under "Status". own means approvals are taken on the deck (default). defer shows status only, and approvals happen on the AI's screen. You can change it with "Show Welcome Screen Again…".

6. Give your AI its first task

   Run your AI once in your project as usual. For Codex, answer the one-time prompt in the interactive CLI to trust ClauDeck's notifications. For Antigravity, quit and reopen it after applying the settings, then send a task.

   Done when: the session takes a slot and the start of your prompt appears on the key's top line.

7. Return one approval

   Ask the AI to do something that needs confirmation, such as editing a file. When the key flashes and a sound plays, check what it is and press the key.

   Done when: the action goes ahead on the AI side.

Kei

Check the tool name on the top line before you press.

Cancel right after pressing

While "Undoable / Sending" is shown (1.5 s), press the same key again to cancel sending the approval. This stops the send; it does not undo actions that have already run.

Hold to "Always allow"

If the bottom line says "Hold=Always", holding the key for 0.8 s or longer auto-allows the same request for the rest of that session. This record lives only in ClauDeck's memory and expires after 24 hours; it is never written to a settings file. The highest-impact actions, such as deletion or push (Tier 3), cannot be set to Always allow.

When a key does not respond

Presses within 0.3 s after a key lights up are ignored to prevent mistakes. "Hold" does not go through under 0.8 s. "Input" is not an approval. A normal approval goes back to the AI's screen after 15 seconds (default).

Language

Switch between Japanese and English with "Language" in the ClauDeck menu bar menu.

Launch at login

Toggle "Launch at Login" in the ClauDeck menu. When checked, ClauDeck starts automatically from your next login. While ClauDeck is not running, approvals happen on the AI's screen as usual.

Sounds and volume

• Approve: a rising sound that stops. The loudest, meant to call you.
• Input: two short questioning tones. A cue to answer on screen.
• Task finished: rises and drops at the end, marking the end of a turn.
• Session ended: three gently falling notes.

Each slot has its own pitch. Under "Sound" in the menu, you can turn off just the transition sounds, or all sounds. "Sound" → "Volume" offers High, Medium and Low (High is the default).

More slots and pages

• Place more ClauDeck Slot actions to add slots right away. Removing one frees it.
• Write "slot name: slot ID" under pins in the settings file to keep a slot in the same place after restarting. You can also pin by AI type (claude, codex, antigravity) to keep the three AIs in fixed positions.
• If you use more sessions than slots, place one ClauDeck Page key.
• On a second deck, slot IDs get a device suffix (for example c0r0#56bc). Which deck is primary is decided by device ID order, so it does not change with launch order.

Settings file

Settings are in ~/.config/claudeck/config.json. They are reloaded automatically when you save and apply from the next approval, so you normally do not need to restart (band colors appear a few seconds after saving).

{
  "policy": "own",
  "hold": 15,
  "sound": true,
  "state_sound": true,
  "pages": 3,
  "notify_ms": 9750,
  "volume": 100,
  "ended_ttl_ms": 900000,
  "auto_page": false,
  "pins": { "claude": "c0r0", "codex": "c1r0" },
  "agent_colors": { "antigravity": "#c026d3" }
}

Viewing the log

Choose "Open Log in Finder" in the menu to see the activity log. It contains no conversation text or file contents.

Checking the version and updating

Click the ClauDeck icon in the menu bar and choose "このアプリについて…" (About this app) at the top to see the version and build number, the copyright and a link to the official site (up to 2.0 it was called "About ClauDeck"). If that item is missing, you have an older version. Update to the latest version and open it again.

At launch, ClauDeck checks for a newer version and, if there is one, opens a "Software Update" window. You can also check from "Check for Updates…" in the menu.

1. Check the remote machine

   Make sure the Linux machine has Python 3.6 or later and Claude Code.

2. Set up passwordless SSH

   Add your public key to ~/.ssh/authorized_keys on the remote machine, and check that you can connect from Terminal on your Mac without a password.

3. Enter the connection

   Open "SSH Remote Sync…" in the ClauDeck menu and enter a connection name, display name, SSH user, host and port. To use a specific private key, pick it with "選ぶ…" (Choose…).

4. Connect

   Turn on auto-connect and reconnect-on-disconnect, then press "設定して接続" (Set up and connect). It checks the connection, sends a small helper to the remote machine, registers with the remote Claude Code, and opens a dedicated channel, in that order.

5. Reopen Claude Code on the remote machine

   When it works, a slot named "[display name] directory" appears on the deck.

How the connection is handled, and what happens when it drops

• ClauDeck connects only to the host you specify. It does not go through the developer's servers or any third-party service.
• The channel inside your Mac is never exposed to the remote machine; only a separate remote entrance protected by a token is used.
• Passwords, two-factor codes and private key contents are not saved (only the private key's file location is remembered).
• When the connection drops, it retries at growing intervals of up to 30 seconds. You can also reconnect with "今すぐ再接続" (Reconnect now) in "SSH Remote Sync…".
• After about 20 seconds disconnected, the slot changes to "Ended", and returns to the same slot with the next activity after reconnecting.
• Approvals during a disconnection cannot be shown on the deck, so they are asked on the AI's screen on the SSH host.

Terms

• Slot: a Stream Deck key taken by one session.
• Session: one conversation with Claude Code, Codex or Antigravity.
• Approve: the flashing state waiting for allow or deny.
• Deny key: a key that turns slot presses into denials while held. It is not a slot.
• Armed: the Deny key being held down. It never times out and always returns when released.
• Unread: a slot whose turn finished but you have not looked at. Same grey as Idle, but raised.
• Offline: shown by the plugin when ClauDeck is not running. Approvals are asked on the AI's screen meanwhile.
• Window: the session list shown on a dial. It does not approve or deny.
• Front: the slot whose window is currently in front. It gets a white band at the bottom.
• Source: which AI a slot belongs to, shown by the top band and the two letters at the start of the bottom line (CC, CX, AG).
• Input: a multiple-choice question. It cannot be answered on the deck.
• Grace period: the time after pressing during which sending the approval is held back.
• Focus: pressing a slot to bring its app to the front.