Frequently Asked Questions

Q: How do I install Agent Hand?

Install Agent Hand with one command: 'curl -fsSL https://raw.githubusercontent.com/weykon/agent-hand/master/install.sh | bash'. The install script checks for tmux (installing it if needed), downloads the correct binary for your OS/architecture, and installs to /usr/local/bin or ~/.local/bin. Requirements: tmux (auto-installed if missing), Linux/macOS/WSL. Binary size is only 2.7MB with no runtime dependencies.

Q: What are the key hotkeys in Agent Hand?

Three essential hotkeys: (1) Ctrl+G - Opens fuzzy search popup to switch between any session instantly; (2) Ctrl+N - Jumps to the highest-priority session (waiting → ready → running → idle); (3) Ctrl+Q - Detaches from current session back to the dashboard, remembering your last position. These work inside any agent-hand tmux session and won't conflict with your regular tmux since they use a dedicated server.

Q: Is Agent Hand free or paid?

Agent Hand is free to use with core features. A Pro version adds advanced features like analytics, custom themes, and team collaboration. The free version includes: unlimited sessions, all hotkeys (Ctrl+G/N/Q), status tracking, groups/labels, and the TUI dashboard. Pro features require authentication via 'agent-hand login'. Pricing is available at agent-hand.com/pricing.

Q: Will Agent Hand interfere with my existing tmux setup?

No. Agent Hand uses a completely separate tmux server socket (tmux -L agentdeck_rs). Your default tmux sessions, configuration, and keybindings remain untouched. You can run both simultaneously - use your regular tmux for personal work and agent-hand for AI agent sessions. The isolation is by design.

Q: How does Agent Hand track session status?

Agent Hand monitors pane output to detect status: (1) WAITING (!) - Detected when output contains confirmation prompts (y/n, confirm, approve, etc.); (2) RUNNING (●) - Active output indicating the agent is processing; (3) READY (✓) - Was recently running, now idle but within the ready_ttl window (default 40 minutes, configurable); (4) IDLE (○) - No recent activity. You can customize detection patterns via config.json.

Q: Can I use Agent Hand with Claude Code, Copilot, and other AI agents?

Yes. Agent Hand works with any AI coding agent that runs in a terminal: Claude Code (claude), GitHub Copilot (copilot), OpenCode, Aider, Cursor, and custom agents. When creating a session, use the -c flag to specify the command: 'agent-hand add . -t MyProject -c claude'. The status detection works out-of-the-box with common agents and can be extended via configuration.

Q: How do I upgrade Agent Hand?

Run 'agent-hand upgrade' to check for and install the latest version from GitHub Releases. The command downloads the appropriate binary for your platform and replaces the current installation. Alternatively, re-run the install script: 'curl -fsSL https://raw.githubusercontent.com/weykon/agent-hand/master/install.sh | bash'.

Question 1

What is Agent Hand and how does it work?

Answer

Agent Hand is a tmux-backed terminal session manager designed specifically for AI coding agents. It creates isolated tmux sessions for each AI agent (Claude Code, GitHub Copilot, OpenCode, etc.) and provides a TUI dashboard to monitor their status.

Each session runs in a dedicated tmux server named 'agentdeck_rs', completely separate from your default tmux installation. The tool tracks session status (waiting, running, ready, idle) and provides hotkeys (Ctrl+G, Ctrl+N, Ctrl+Q) for fast switching between agents.

Question 2

How is Agent Hand different from regular tmux?

Answer

Agent Hand is built on top of tmux but adds AI-specific features:

Status tracking - visual indicators show which agents are waiting for input (!), running (●), ready for review (✓), or idle (○)
Smart prioritization - Ctrl+N jumps to the highest-priority session automatically
Fuzzy search - Ctrl+G opens a popup to find any session instantly
Isolation - uses a dedicated tmux server that never interferes with your personal tmux setup
Groups and labels - organize sessions by project with custom titles and colored labels

Question 3

Why do I need a session manager for AI coding agents?

Answer

When running multiple AI agents simultaneously (Claude, Copilot, OpenCode), you face three problems:

Context overload - too many terminal panes to track
Missed prompts - easy to miss confirmation requests waiting in background sessions
Navigation friction - constantly switching between terminals wastes time

Agent Hand solves this with clear status icons, priority jumping (Ctrl+N), and a unified dashboard showing all sessions at a glance. It prevents the "which Claude was I talking to?" problem.

Question 4

How do I install Agent Hand?

Answer

Install Agent Hand with one command:

curl -fsSL https://raw.githubusercontent.com/weykon/agent-hand/master/install.sh | bash

The install script checks for tmux (installing it if needed), downloads the correct binary for your OS/architecture, and installs to /usr/local/bin or ~/.local/bin.

Requirements: tmux (auto-installed if missing), Linux/macOS/WSL. Binary size is only 2.7MB with no runtime dependencies.

Question 5

What are the key hotkeys in Agent Hand?

Answer

Three essential hotkeys:

Ctrl+G - Opens fuzzy search popup to switch between any session instantly
Ctrl+N - Jumps to the highest-priority session (waiting → ready → running → idle)
Ctrl+Q - Detaches from current session back to the dashboard, remembering your last position

These work inside any agent-hand tmux session and won't conflict with your regular tmux since they use a dedicated server.

Question 6

Is Agent Hand free or paid?

Answer

Agent Hand is free to use with core features. A Pro version adds advanced features like analytics, custom themes, and team collaboration.

Free version includes: unlimited sessions, all hotkeys (Ctrl+G/N/Q), status tracking, groups/labels, and the TUI dashboard.

Pro features require authentication via agent-hand login . Pricing is available at agent-hand.com/pricing .

Question 7

Will Agent Hand interfere with my existing tmux setup?

Answer

No. Agent Hand uses a completely separate tmux server socket ( tmux -L agentdeck_rs ). Your default tmux sessions, configuration, and keybindings remain untouched.

You can run both simultaneously - use your regular tmux for personal work and agent-hand for AI agent sessions. The isolation is by design.

Question 8

How does Agent Hand track session status?

Answer

Agent Hand monitors pane output to detect status:

WAITING (!) - Detected when output contains confirmation prompts (y/n, confirm, approve, etc.)
RUNNING (●) - Active output indicating the agent is processing
READY (✓) - Was recently running, now idle but within the ready_ttl window (default 40 minutes, configurable)
IDLE (○) - No recent activity

You can customize detection patterns via config.json .

Question 9

Can I use Agent Hand with Claude Code, Copilot, and other AI agents?

Answer

Yes. Agent Hand works with any AI coding agent that runs in a terminal:

Claude Code (claude)
GitHub Copilot (copilot)
OpenCode
Aider
Cursor
Custom agents

When creating a session, use the -c flag to specify the command:

agent-hand add . -t MyProject -c claude

The status detection works out-of-the-box with common agents and can be extended via configuration.

Question 10

How do I upgrade Agent Hand?

Answer

Run the upgrade command:

agent-hand upgrade

This checks for and installs the latest version from GitHub Releases. The command downloads the appropriate binary for your platform and replaces the current installation.

Alternatively, re-run the install script:

curl -fsSL https://raw.githubusercontent.com/weykon/agent-hand/master/install.sh | bash

Question 11

What is the performance impact of Agent Hand?

Answer

Agent Hand has minimal overhead :

Startup time: under 50ms
Memory usage: approximately 8MB
Binary size: 2.7MB

It uses Rust's zero-cost abstractions and efficient tmux IPC. The TUI dashboard refreshes at 60fps with negligible CPU usage. Status detection runs only when viewing the dashboard, not continuously.

Question 12

How do I organize sessions into groups?

Answer

In the TUI dashboard:

Press 'g' to create a new group
Groups can be expanded/collapsed with Space or Enter
To move a session to a group, select it and press 'm'

Groups are useful for organizing by project (work/client-a), use case (experiments, production), or agent type (Claude sessions, Copilot sessions). Group names support paths like 'work/demo' for nested organization.