aque 0.0.1__tar.gz

aque-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.superpowers/
+docs/superpowers/
+dist/

aque-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aque Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aque-0.0.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aque
+Version: 0.0.1
+Summary: A tmux-based agent queue manager. You sit at the desk, agents come to you.
+Project-URL: Homepage, https://github.com/can-can/aque
+Project-URL: Repository, https://github.com/can-can/aque
+Project-URL: Issues, https://github.com/can-can/aque/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,queue,textual,tmux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Requires-Dist: libtmux>=0.37.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=0.47.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.svg" width="80" alt="aque logo">
+</p>
+
+<h1 align="center">Aque</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/aque/"><img src="https://img.shields.io/pypi/v/aque.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/aque/"><img src="https://img.shields.io/pypi/pyversions/aque.svg" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+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.
+
+![Demo](docs/demo.gif)
+
+## Install
+
+```bash
+pipx install aque
+```
+
+Or with pip:
+
+```bash
+pip install aque
+```
+
+Requires: Python 3.11+, [tmux](https://github.com/tmux/tmux)
+
+### Development
+
+```bash
+git clone https://github.com/can-can/aque.git
+cd aque
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Launch agents:
+
+```bash
+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
+```
+
+Sit at your desk:
+
+```bash
+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
+
+| Key | Action |
+|-----|--------|
+| ↑↓ | Navigate agent list |
+| Enter | Attach to selected agent |
+| n | Create new agent |
+| k | Kill selected agent (moves to history) |
+| h | Toggle hold on selected agent |
+| q | Quit desk |
+
+### 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.
+
+### 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.
+
+### Agent States
+
+| State | Meaning |
+|-------|---------|
+| running | Agent is actively working |
+| waiting | Agent is idle, queued for your attention |
+| focused | You are currently attached to this agent |
+| on_hold | Paused, skipped in the queue |
+| exited | Tmux session has ended |
+| done | Completed, moved to history |
+
+### Other Commands
+
+```bash
+aque list    # show all agents and states
+aque kill 3  # terminate an agent
+```
+
+## Configuration
+
+Edit `~/.aque/config.yaml`:
+
+```yaml
+idle_timeout: 10
+snapshot_interval: 2
+session_prefix: aque
+action_keys:
+  dismiss: d
+  done: k
+  skip: s
+  hold: h
+```
+
+## License
+
+[MIT](LICENSE)

aque-0.0.1/README.md

@@ -0,0 +1,124 @@
+<p align="center">
+  <img src="docs/logo.svg" width="80" alt="aque logo">
+</p>
+
+<h1 align="center">Aque</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/aque/"><img src="https://img.shields.io/pypi/v/aque.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/aque/"><img src="https://img.shields.io/pypi/pyversions/aque.svg" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+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.
+
+![Demo](docs/demo.gif)
+
+## Install
+
+```bash
+pipx install aque
+```
+
+Or with pip:
+
+```bash
+pip install aque
+```
+
+Requires: Python 3.11+, [tmux](https://github.com/tmux/tmux)
+
+### Development
+
+```bash
+git clone https://github.com/can-can/aque.git
+cd aque
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Launch agents:
+
+```bash
+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
+```
+
+Sit at your desk:
+
+```bash
+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
+
+| Key | Action |
+|-----|--------|
+| ↑↓ | Navigate agent list |
+| Enter | Attach to selected agent |
+| n | Create new agent |
+| k | Kill selected agent (moves to history) |
+| h | Toggle hold on selected agent |
+| q | Quit desk |
+
+### 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.
+
+### 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.
+
+### Agent States
+
+| State | Meaning |
+|-------|---------|
+| running | Agent is actively working |
+| waiting | Agent is idle, queued for your attention |
+| focused | You are currently attached to this agent |
+| on_hold | Paused, skipped in the queue |
+| exited | Tmux session has ended |
+| done | Completed, moved to history |
+
+### Other Commands
+
+```bash
+aque list    # show all agents and states
+aque kill 3  # terminate an agent
+```
+
+## Configuration
+
+Edit `~/.aque/config.yaml`:
+
+```yaml
+idle_timeout: 10
+snapshot_interval: 2
+session_prefix: aque
+action_keys:
+  dismiss: d
+  done: k
+  skip: s
+  hold: h
+```
+
+## License
+
+[MIT](LICENSE)

aque-0.0.1/aque/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

aque-0.0.1/aque/cli.py

@@ -0,0 +1,136 @@
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from aque.config import load_config
+from aque.monitor import start_monitor_daemon, stop_monitor
+from aque.run import launch_agent
+from aque.state import AgentState, StateManager
+
+app = typer.Typer(help="Aque — a tmux-based agent queue manager.")
+console = Console()
+
+AQUE_DIR = Path.home() / ".aque"
+
+
+@app.callback()
+def main(
+    aque_dir: Optional[str] = typer.Option(None, "--aque-dir", help="Aque state directory (default: ~/.aque)"),
+) -> None:
+    global AQUE_DIR
+    if aque_dir:
+        AQUE_DIR = Path(aque_dir)
+        AQUE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_state_manager() -> StateManager:
+    return StateManager(AQUE_DIR)
+
+
+def ensure_monitor_running() -> None:
+    mgr = get_state_manager()
+    state = mgr.load()
+    if state.monitor_pid:
+        try:
+            os.kill(state.monitor_pid, 0)
+            return
+        except ProcessLookupError:
+            state.monitor_pid = None
+            mgr.save(state)
+    start_monitor_daemon(AQUE_DIR)
+
+
+@app.command()
+def run(
+    dir: str = typer.Option(..., "--dir", help="Working directory for the agent"),
+    label: Optional[str] = typer.Option(None, "--label", help="Human-readable label"),
+    command: list[str] = typer.Argument(..., help="Agent command and arguments"),
+) -> None:
+    """Launch an agent in a managed tmux session."""
+    config = load_config(AQUE_DIR)
+    mgr = get_state_manager()
+    agent_id = launch_agent(
+        command=command,
+        working_dir=dir,
+        label=label,
+        state_manager=mgr,
+        prefix=config["session_prefix"],
+    )
+    ensure_monitor_running()
+    console.print(f"[green]Agent #{agent_id} launched[/green]: {label or command[0]}")
+
+
+@app.command(name="list")
+def list_agents() -> None:
+    """Show all managed agents and their states."""
+    mgr = get_state_manager()
+    state = mgr.load()
+
+    if not state.agents:
+        console.print("[dim]No agents running.[/dim]")
+        return
+
+    table = Table()
+    table.add_column("ID", style="bold")
+    table.add_column("STATE")
+    table.add_column("LABEL")
+    table.add_column("DIR")
+
+    state_colors = {
+        AgentState.RUNNING: "green",
+        AgentState.WAITING: "yellow",
+        AgentState.FOCUSED: "blue",
+        AgentState.EXITED: "dim",
+        AgentState.ON_HOLD: "magenta",
+        AgentState.DONE: "red",
+    }
+
+    for agent in state.agents:
+        color = state_colors.get(agent.state, "white")
+        table.add_row(
+            str(agent.id),
+            f"[{color}]{agent.state.value}[/{color}]",
+            agent.label,
+            agent.dir,
+        )
+
+    console.print(table)
+
+
+@app.command()
+def kill(agent_id: int = typer.Argument(..., help="Agent ID to terminate")) -> None:
+    """Terminate an agent and clean up its tmux session."""
+    import libtmux
+    from aque.history import HistoryManager
+
+    mgr = get_state_manager()
+    hmgr = HistoryManager(AQUE_DIR)
+    state = mgr.load()
+    agent = next((a for a in state.agents if a.id == agent_id), None)
+
+    if agent is None:
+        console.print(f"[red]Agent #{agent_id} not found.[/red]")
+        raise typer.Exit(1)
+
+    try:
+        server = libtmux.Server()
+        session = server.sessions.get(session_name=agent.tmux_session)
+        if session:
+            session.kill()
+    except Exception:
+        pass
+
+    mgr.done_agent(agent_id, hmgr)
+    console.print(f"[red]Agent #{agent_id} done — moved to history.[/red]")
+
+
+@app.command()
+def desk() -> None:
+    """Open the desk TUI. Agents come to you."""
+    from aque.desk import DeskApp
+    desk_app = DeskApp(aque_dir=AQUE_DIR)
+    desk_app.run()

aque-0.0.1/aque/config.py

@@ -0,0 +1,37 @@
+import copy
+from pathlib import Path
+
+import yaml
+
+
+DEFAULT_CONFIG = {
+    "idle_timeout": 10,
+    "snapshot_interval": 2,
+    "action_keys": {
+        "dismiss": "d",
+        "done": "k",
+        "skip": "s",
+        "hold": "h",
+    },
+    "queue_order": "fifo",
+    "session_prefix": "aque",
+}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    result = copy.deepcopy(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_config(aque_dir: Path) -> dict:
+    config_path = Path(aque_dir) / "config.yaml"
+    if not config_path.exists():
+        return copy.deepcopy(DEFAULT_CONFIG)
+    with open(config_path) as f:
+        user_config = yaml.safe_load(f) or {}
+    return _deep_merge(DEFAULT_CONFIG, user_config)