awslabs / awslabs/cli-agent-orchestrator
[Feat] Instead of spawning new tmux window, reuse existing ones
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
## Overview
Whenever an assign or handoff happens, the supervisor spawns a new tmux window, and these windows are one-off, meaning that they are abandoned after that command is complete. This piles up tmux windows, which a human has to manually clean up.
## User Stories
* As a **developer running the supervisor**, I want **handoff/assign tmux windows to be automatically cleaned up when the command completes**, so that **my tmux environment doesn’t accumulate abandoned windows**.
* As a **developer running multiple handoffs per day**, I want **tmux windows to be easy to identify (names/labels)**, so that **I can quickly find the active one and ignore or diagnose failures**.
* As a **developer debugging a failed handoff**, I want **failed windows to be retained (or optionally retained) with logs**, so that **I can inspect what went wrong without losing context**.
* As a **power user**, I want **configurable cleanup behavior (always / on-success / never / TTL)**, so that **I can match the workflow to my preference**.
## Acceptance Criteria
* Supervisor-created tmux windows are **not left behind by default** after an assign/handoff command finishes successfully.
* Cleanup is **safe and scoped**: only windows created by the supervisor for this command are cleaned up (no risk of deleting user windows).
* On failure, the tmux window is **retained by default** (or configurable), and the user is shown **how to switch to it** (window name + command).
* Windows created by the supervisor follow a **deterministic naming convention** (e.g., `sup::`), and are identifiable for later cleanup.
* A **manual cleanup command** exists (or a flag) to remove leftover supervisor windows (e.g., `--cleanup`), including stale windows from previous runs.
* Behavior is **configurable** via config/env/CLI flag:
* `cleanup=always | on-success | never`
* optional `ttl_minutes=N` for pruning stale windows
* If tmux is not available or tmux commands fail, the supervisor **fails gracefully** with actionable error output.
## Proposed solution
* **New module `feature1.py`** (tmux window lifecycle manager)
* Responsibilities:
* Create window with structured name
* Track window(s) created per workflow/command
* Execute cleanup policy (on-success/on-exit/ttl-based pruning)
* Utility helpers: `window_exists`, `kill_window`, `list_supervisor_windows`, `switch_hint`
* Example APIs:
* `create_window(workflow_id, command_name, ...) -> window_name`
* `cleanup_window(window_name, policy, success: bool)`
* `prune_stale_windows(ttl_minutes)`
* **Modify `util2.py`**
* Integrate lifecycle manager into assign/handoff flow:
* Wrap command execution in try/finally
* On success: cleanup based on policy
* On failure: retain window and print switch instructions
* Add configuration plumbing:
* Read CLI flags / env vars
* Pass policy + ttl into `feature1.py`
## Additional context
**Is your feature request related to a problem? Please describe.**
Yes. Each assign/handoff spawns a new one-off tmux window that is not cleaned up after completion, which gradually clutters the developer’s tmux workspace. Users must manually list and kill windows, which is tedious and error-prone.
**Describe alternatives you’ve considered**
* **Manual cleanup**: Running `tmux list-windows` and `tmux kill-window` works but doesn’t scale and is easy to forget.
* **Reuse a single window**: Reduces clutter but can cause collisions between concurrent runs and makes debugging harder (mixed logs).
* **External wrapper script**: Could prune windows, but duplicates logic and risks drift from supervisor behavior.
**Additional context**
* Suggested defaults:
* Cleanup policy: `on-success`
* Failure behavior: retain window and print how to switch to it
* Naming convention includes workflow/run id for traceability
* Optional: add a `--keep-tmux` flag for debugging or local development.
Contributor guide
Research direction
Start by tracing the existing assign/handoff flow and tmux calls in util2.py, then review the proposed lifecycle responsibilities for feature1.py. Done means supervisor-created windows follow a deterministic naming scheme, successful runs clean up safely, failures retain windows with switch instructions, and cleanup behavior is configurable with graceful tmux errors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100