Aque

A tmux-based agent queue manager. You sit at one "desk" and your AI agents come to you.

Why?

Running multiple AI coding agents (Claude Code, aider, Codex) at once? They all need your attention at different times. Aque queues them so you work through them one at a time — no forgotten terminal tabs, no context switching.

Install

pipx install aque

Or with pip:

pip install aque

Requires: Python 3.11+, tmux

Development

git clone https://github.com/can-can/aque.git
cd aque
pip install -e ".[dev]"

Usage

Launch agents:

aque run --dir ~/projects/api --label "auth fix" -- claude --model opus
aque run --dir ~/projects/web -- aider --model gpt-4
aque run --dir ~/code/tests -- codex

Use --type to enable signal-based idle detection for supported agent types:

aque run --type claude --dir ~/projects/api -- claude --model opus

Sit at your desk:

aque desk

The desk shows a unified dashboard with all your agents, their states, and a live preview of the selected agent's terminal output.

Dashboard Keys

Detach Behavior

When you detach from a tmux session (Ctrl-b d), aque handles the transition automatically:

• Running/waiting agent — auto-dismissed back to running, returns to dashboard
• Exited agent — auto-marked as done and moved to history

No action menu, no extra steps.

Auto-Attach

When a waiting agent is detected (on the dashboard or after detaching), aque shows a 3-second countdown modal and auto-attaches to the top-priority waiting agent. Press Esc to cancel and stay on the dashboard.

Agent Types & Signal-Based Detection

For supported agent types, aque can use signal files instead of polling for more reliable idle detection.

When you specify --type, aque installs a hook into the agent that writes a signal file when it stops. This is faster and more accurate than prompt-marker polling.

Currently supported types:

When creating an agent from the dashboard (n), the new agent form lets you select a type in the first step.

The agent type is shown as a tag in the agent list, and the detection method is shown in the preview panel.

Auto-Responder

When you launch an agent, aque automatically pairs it with a responder agent — another aque-managed tmux session. After the partner sits in waiting for responder_idle_gap seconds (default 30), aque types a one-line nudge into the responder's pane. The responder reads the partner's screen with tmux capture-pane and replies with tmux send-keys using its own toolbelt.

Responders are hidden from the dashboard by default. Press R to reveal them, and a to toggle auto-response on the selected partner.

To suppress auto-response for a single launch: aque run --no-responder -- .... To override the responder command for a single launch: aque run --responder-cmd "claude --model haiku" -- ....

Disable globally in ~/.aque/config.yaml:

responder_enabled: false

Configurable keys (with defaults):

responder_enabled: true
responder_command: ["claude"]
responder_idle_gap: 30
responder_dir: null   # null => ~/.aque/responders/<partner_id>/

Idle Detection

Aque monitors tmux panes for prompt markers (❯, $, >>>) to detect when an agent is waiting for input. After the configured idle timeout (default: 10s), the agent transitions from running to waiting and enters the queue.

When using a typed agent, signal files take precedence over prompt-marker polling.

Narrow Terminal Support

On terminals narrower than 80 columns, aque automatically switches to a compact single-column layout: the preview panel is hidden, the agent list uses shorter labels, and modals/forms adapt to fit. The layout updates live on resize.

Agent States

Other Commands

aque list    # show all agents and states
aque kill 3  # terminate an agent

Configuration

Edit ~/.aque/config.yaml:

idle_timeout: 10
snapshot_interval: 2
session_prefix: aque
default_dir: ~/Projects
action_keys:
  dismiss: d
  done: k
  skip: s
  hold: h

License

MIT