awslabs / awslabs/cli-agent-orchestrator

[Feat] Instead of new tmux windows, spawn new panes

Open
#74 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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 tmux window. I want the option to open them as new tmux pane instead, so that I can see all agents working in a single view. This will make it easier to interrupt with agents if they are digressing.

## User Stories

* As a **developer running the supervisor**, I want to **open new agent runs in tmux panes instead of new windows**, so that **I can monitor multiple agents side-by-side in one view**.
* As a **developer orchestrating several agents in parallel**, I want to **choose the pane layout (horizontal/vertical/tiled)**, so that **the view remains readable as the number of agents grows**.
* As a **developer who frequently intervenes**, I want **a quick way to focus a pane and send input / stop a command**, so that **I can interrupt or redirect an agent when it’s digressing**.
* As a **user who sometimes prefers the current behavior**, I want **a simple toggle to use windows vs panes**, so that **the workflow fits different tasks and screen sizes**.

## Acceptance Criteria

* A configuration option (CLI flag and/or config/env) exists to select tmux spawn mode:

* `spawn_mode=window | pane`
* When `spawn_mode=pane`, assign/handoff creates **a new pane in the current tmux window** (or a designated supervisor window) rather than creating a new window.
* Pane creation is **deterministic and non-destructive**:

* It must not kill/overwrite existing panes.
* It must not disrupt user sessions outside the targeted window.
* Layout behavior is configurable and works for repeated spawns:

* supports at least `splitv` (vertical split) and `splith` (horizontal split)
* optionally `tiled` / “even” balancing (e.g., `select-layout tiled`)
* If pane creation fails (not in tmux, target window missing, tmux error), the supervisor **falls back to window mode** (or exits with a clear actionable error), and prints what happened.
* Each pane is labeled/identifiable (pane title or command printed) with a consistent naming scheme, and the supervisor prints:

* which window it used
* how to navigate/focus panes (e.g., `prefix + o`, `select-pane -t ...`)

## Proposed solution

* **New module `feature1.py`** (tmux spawn strategy + layout manager)

* Responsibilities:

* Detect whether we’re inside tmux (`$TMUX`) and gather context (session, window id)
* Spawn a new agent either as a **window** or a **pane** based on config
* Apply a layout strategy after spawn (optional)
* Provide safe fallbacks and user-facing hints
* Example APIs:

* `spawn_agent(cmd, mode, target_window=None, split="v", layout=None) -> SpawnResult`
* `ensure_target_window(name_or_id) -> window_id`
* `apply_layout(window_id, layout)`
* **Modify `util2.py`**

* Wire new options into assign/handoff:

* Parse config: `spawn_mode`, `split`, `layout`, optional `target_window`
* Replace “always create new window” calls with `feature1.spawn_agent(...)`
* Print consistent UX output:

* agent identifier → tmux pane/window location
* navigation shortcuts and attach commands

### Implementation notes (tmux primitives)

* Create pane:

* `tmux split-window -h| -v -t ""`
* Apply layout:

* `tmux select-layout -t tiled` (or even-horizontal / even-vertical)
* Label pane (optional but nice):

* `tmux select-pane -t -T "agent:"`

## Additional context

**Is your feature request related to a problem? Please describe.**
Yes. Window-per-agent makes it hard to monitor multiple agents at once and easy to “lose” an agent that has started to drift. A single multi-pane view improves situational awareness and makes it faster to intervene (send input, stop execution, or redirect).

**Describe alternatives you’ve considered**

* **Keep window mode only**: simplest, but poor visibility when running many agents.
* **Use external terminal tabs (iTerm/kitty)**: works but splits the workflow across tools and loses tmux-native navigation.
* **One window per workflow** (still windows): better grouping but still not the single-view monitoring you want.

**Additional context**

* Suggested defaults:

* `spawn_mode=window` (backward compatible)
* If `spawn_mode=pane`: `split=v` + `layout=tiled` after N panes (or always)
* Optional future enhancement:

* A “supervisor dashboard window” that always hosts panes, regardless of where the command was launched.

Contributor guide

Open the contributing guide

Research direction

Start by locating the current tmux window creation in the assign and handoff entry points, then inspect util2.py and the proposed feature1.py boundary. Done means configurable window or pane spawning, split/layout choices, safe fallback behavior, identifiable panes, and the stated navigation output without disrupting existing sessions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.