User guide

Install and get started

Requirements

On macOS or Windows, use Stream Deck 7.1 or newer, with macOS 13+ or Windows 11+. Install the harnesses you want to use on the same computer, with versions that provide the required hooks. Remote sessions, SSH and WSL are not connected automatically.

The Stream Deck application must remain running on your computer. The mobile app is optional when using a physical deck. To use a phone as your deck, set up Stream Deck Mobile on the same Wi-Fi network as your computer.

First launch

1. Open the com.sxnlabs.harness-deck.streamDeckPlugin file supplied for this version and finish installing it in Stream Deck.
2. Select your device in Stream Deck. Import fifteen-keys.streamDeckProfile for a 15-key deck, or six-keys.streamDeckProfile for the compact Mobile profile. Then select Harness Control · 15 keys or Harness Control · 6 keys.
3. Click a Harness Control key in the Stream Deck editor to display its settings below the key grid. Use Your agents to connect your harnesses.
4. Connect Claude Code or Codex using the connection chapter, then start a new local session.
5. Click Check again. Session received confirms that a session event has reached the plugin during its current run.

Configured confirms that connection settings are present. Check Session received separately to confirm that events are arriving. A session opened before installation may need to be restarted to load its hooks.

Connect Claude Code and Codex

Claude Code

Find the Claude Code card in Your agents. Check the default profile directory, then click Connect. Start a new Claude Code session with your usual configuration and check for Session received.

The default directory is ~/.claude, or the absolute path specified by CLAUDE_CONFIG_DIR in the plugin’s environment. Harness Control adds its hooks to the selected profile and backs up the settings it changes. Existing hooks and permission rules are preserved.

Multiple Claude configurations

To use Personal and Work profiles, for example:

1. Rename the default profile Personal, then click Save name.
2. Open Add Claude profile. Enter Work and the absolute path to an existing configuration directory, such as /Users/your-name/.claude-manda on macOS. Enter the full path without ~.
3. Click Add profile, then Connect for that profile.
4. Restart each session with its usual directory. On macOS or Linux, you can launch the second profile with the following command if that directory exists.

CLAUDE_CONFIG_DIR="$HOME/.claude-manda" claude

On Windows, launch the second profile in PowerShell with:

$env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\.claude-manda"
claude

In PowerShell, this variable stays set in the current terminal. Use separate windows for the two profiles.

Both profiles appear on the Claude row, with their profile name and the beginning of the session name. Their permission requests and connection settings remain separate. Disconnect on Work disconnects only Work. Your accounts and terminal aliases stay in their usual settings.

Codex

Click Connect on the Codex card. In Codex CLI, open /hooks, inspect new or changed Harness Control hooks, and trust them. Then start a new local session and check for Session received. Codex requires this review before running these hooks, including after some updates. Official Codex hooks documentation.

The requests you see depend on the agent’s permission mode and the operation it wants to perform. In Claude, a permission hook runs when the agent needs a decision about a tool. Claude Code reference.

Open a terminal session

Select the session on the deck, then open Selected session in a key’s settings. Set Exact terminal window title to the complete, unique title of its window. The value is saved when you change the field.

On macOS, this command targets Ghostty. On first use, follow the macOS prompts to allow window control. If access is denied, check System Settings > Privacy & Security > Accessibility. A window with that title must be open. The command does not select a background tab. For a Codex desktop session without a terminal origin, Open uses the session’s link in Codex.

Use the keys

The 15-key profile

The first two rows display ten sessions: Claude Code followed by Codex by default. On macOS and Windows, a recognized harness app uses both rows. A terminal shared between multiple harnesses keeps the two configured rows.

Pressing a session selects it and opens it when its connector supports opening. Command keys show the selected session’s name, harness and Claude profile. Previous and Next navigate sessions and pages without opening them; Archive archives the selected session in a supported harness, then removes it from the Deck.

Recent sessions appear first. A new session can move keys, but another request does not change your selection. Renaming a session does not move it to the front.

Understand the displayed state

A waiting key pulses gently across its whole background, with a three-second cycle and steady text. Answer questions and plan choices in the harness. Approve and Deny respond to supported tool permission requests.

Approve or deny

Select the session showing APPROVAL. In Selected session, inspect the requested tool and its parameters, then press Approve or Deny. The decision applies once to the selected request and does not create a permanent permission.

The buttons are disabled when no request is pending. You cannot approve an expired request or one that has already completed or been answered elsewhere through its old key. If the deck or plugin becomes unavailable, Claude, Codex and Cursor resume their normal permission handling. Harness Control does not grant automatic approvals.

Archive and restore a session

Select a Codex or OpenCode session, then press Archive. The plugin requests native archiving and waits for the harness to confirm before removing the session from the keys. Failed commands leave the session visible. Its history remains in the harness’s archive.

For Codex, install a CLI that provides codex archive and codex unarchive; this connector was verified with 0.161.0. It uses the exact session ID and configuration directory. OpenCode uses its local API, verified with 1.18.35, on the connected server and project.

In a key’s settings, open Archived sessions and click Restore. This also unarchives the session in its harness. Keep the same Codex configuration directory or reconnect the original OpenCode server and project. If the session has closed, resume it in the harness after restoring it. Archiving sends no Approve/Deny decision.

Native archiving is not integrated for Claude Code in the terminal, Pi or Cursor in this version. Their Archive key stays muted and shows UNAVAILABLE. Claude Personal and Work profiles each retain their sessions. Claude Code cloud documents sidebar archiving; it does not automatically apply to a local terminal session. Claude Code cloud documentation.

If you use an older 15-key profile, replace its Open key with Archive session from the Stream Deck action library. Session keys still open chats directly.

Appearance and the Mobile profile

Session keys use a solid harness color, without a logo, and a large title on up to four lines. The Claude profile appears with the state. In Deck appearance and layout, configure command keys (Dark background / Solid color background) and row harnesses (First session row / Second session row).

The compact Mobile profile provides Open, Approve, Deny, Stop, Previous and Next. In Codex, Pi and Cursor, STOP IN APP means that you must interrupt the session manually. The supplied 15-key profile has no Stop key.

Connect OpenCode, Pi and Cursor

OpenCode

Click Set up server on the OpenCode card. Connect the plugin to the local server used by your OpenCode session. To start a new terminal with a known address:

opencode --hostname 127.0.0.1 --port 4096

In OpenCode connection, enable Enable OpenCode, enter http://127.0.0.1:4096, select OpenCode terminal, then click Save connection. If your server uses a password, enter its credentials in this section. Connected can appear even when no project or session is displayed yet.

A separately launched opencode serve process is another instance: use the address of the server attached to your terminal. Project directory (optional) lets you target a project. Terminal app identifies the terminal for row switching; bringing its window to the front also requires an exact window title. OpenCode server documentation.

Open selects the session through OpenCode when the terminal is attached to that server. With Desktop app, open the session manually in OpenCode. Approve/Deny answer an individual request; Stop uses the OpenCode server.

Pi

Click Prepare Pi, then Copy command. Run the displayed command in the specified terminal. On Windows, use PowerShell, as shown in the interface. This command launches Pi with the Harness Control extension for that session.

The extension adds individual confirmation for shell commands, writes, and custom or MCP tools. Built-in read tools run directly. If the deck does not respond, an interactive Pi session can ask for confirmation in Pi; without an interactive interface, the tool is blocked. Stop is handled in Pi.

To start a session without this connection, launch Pi without the Harness Control extension option. This button does not install a global extension.

Cursor

Click Connect, then start a new local conversation in Cursor. You can approve or deny shell command and MCP tool requests from the deck. File changes update the session’s state; this connector does not grant their permissions. Open conversations and stop them in Cursor.

Available commands

Opening and interrupting windows also depend on your operating system, as described in the compatibility chapter.

Troubleshooting

Click a Harness Control key in the editor, then Check again. Read the status and message on the relevant card, or on the specific Claude profile.

No sessions appear

Check that the selected Stream Deck profile belongs to Harness Control, that the plugin is installed and that Stream Deck is running. Restart the agent after connecting it. For Claude, check the configuration directory used at launch; for Codex, hook trust; for Pi, the command with the extension; for OpenCode, the server and project you are targeting.

Claude, Codex and Cursor sessions appear from their local events. Their full history is not added to the deck. After restarting the plugin, resume activity in your sessions or start new ones.

A key pulses, but Approve is disabled

The session may be waiting for an answer to a question or another choice. Open the harness to read it. Approve/Deny become active when a supported tool permission request is pending. Operations already allowed by your rules can run without displaying a request on the deck.

A key shows an exclamation mark

The triangle means that an action could not be executed. Click that key in the Stream Deck editor to read the plugin’s message. If the key is Open, check the window title and permissions described below.

Open does not bring up the right window

Check Exact terminal window title for the selected session. It must match exactly one open window; two identical titles or a changed title prevent targeting. On macOS, use Ghostty and check Accessibility permission. On Windows, the system may refuse to bring a window to the front. Select background tabs manually.

The displayed name is the project name

The plugin displays the project when no usable session name is available. Wait a few seconds after renaming a session in the harness. You can inspect its path and the name used by the plugin in Selected session.

Get help

Email nathan@sxnlabs.com with your operating system, Stream Deck, Harness Control and harness versions, deck model, displayed status, and steps to reproduce the issue. A screenshot of the statuses is often enough. Hide confidential project names, paths and tool parameters.

Compatibility, updates and data

macOS, Windows and Linux

On Linux, follow the OpenDeck instructions, including device access rules and host Node installation when using Flatpak. Import harness-control-0.9.5.0-linux-opendeck.streamDeckPlugin, add Harness Control actions, and connect your agents in their settings. This package is intended for OpenDeck.

Update

Install the new plugin version, then open a key’s settings. If a card shows Update needed, update its connection. Inspect changed Codex hooks with /hooks and restart the affected sessions.

Keep your Stream Deck profiles and check rows, appearance and exact window titles after updating. Stream Deck provides profile backup and restore. Handle any request pending before a restart in the harness; the plugin does not approve it again when it returns.

Disconnect or uninstall

For Claude Code, click Disconnect next to the relevant profile. For Codex or Cursor, open Details and click Disconnect. The connector’s Harness Control hooks are removed, while other settings are preserved. Restart sessions to load the change. You can then delete an added Claude profile with Remove; its configuration directory stays in place.

For OpenCode, clear Enable OpenCode and click Save connection. For Pi, restart without the extension. Disconnect the harnesses you want to remove before uninstalling the plugin in Stream Deck.

Data used

The connection between Harness Control and sessions is local. The plugin uses session names, projects, states and tool requests to display keys and the selected request. It looks up names in local metadata for sessions it has already received; it does not import full conversation histories.

Claude and OpenAI accounts remain in their applications. Any OpenCode server credentials are stored in the plugin’s settings on this computer. Your harnesses continue using their usual services according to their own configuration.

Back to top ↑