ace-tmux 0.11.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6edbcf3bf58e90e79182dc805d7f8a0a05ce2d0700b8073f9b62a2d1ae9c000f
+  data.tar.gz: 5c2b63bcf1ca460962d2699feded26f4218175d36ae60bfa557e0f23cf453a47
+SHA512:
+  metadata.gz: 0b243e73b26ee915c578f6d9759100455d00a9e266b935a31f859b7c6eaa01d22094f198614f6542bf0f40d5567e535f9b3d25c5bfa776e2c6a8dba9426ee25b
+  data.tar.gz: 64ce6b86d35c2c9196b4ba047dd32cfb188bfb8279f7bb9d34eeb8b5658f8b14164e5c49715ba03a79ad88fef287a5b1cf5fddcf61d89fc5b61148d708d02fb7

data/.ace-defaults/tmux/config.yml

@@ -0,0 +1,11 @@
+# ace-tmux default configuration
+# Override in ~/.ace/tmux/config.yml or .ace/tmux/config.yml
+
+# Path to tmux binary (default: tmux from PATH)
+tmux_binary: tmux
+
+# Default presets when no arguments are provided
+# ace-tmux (no args) uses session default outside tmux, window default inside tmux
+defaults:
+  session: default
+  window: cc

data/.ace-defaults/tmux/panes/claude.yml

@@ -0,0 +1,4 @@
+# Claude Code pane preset
+commands:
+  - cc
+focus: true

data/.ace-defaults/tmux/panes/nvim.yml

@@ -0,0 +1,4 @@
+# Neovim editor pane preset
+commands:
+  - sleep 0.15
+  - nvim

data/.ace-defaults/tmux/panes/work-on-task-cc.yml

@@ -0,0 +1,4 @@
+# Task driving pane preset
+commands:
+  - cc /as-assign-drive
+focus: true

data/.ace-defaults/tmux/panes/work-on-task-status.yml

@@ -0,0 +1,4 @@
+# Assignment/task status pane preset
+commands:
+  - ace-task status
+  - ace-assign status

data/.ace-defaults/tmux/sessions/default.yml

@@ -0,0 +1,5 @@
+# Default session preset
+# 3-pane layout: claude (left 40%), shell (right-top), nvim (right-bottom)
+name: default
+windows:
+  - preset: cc

data/.ace-defaults/tmux/windows/cc-ipad.yml

@@ -0,0 +1,10 @@
+# Claude Code workspace for small screens (iPad)
+# top: claude (full width) | bottom-left: shell | bottom-right: shell
+direction: vertical
+panes:
+  - preset: claude
+    size: "50%"
+  - direction: horizontal
+    panes:
+      - commands: []
+      - commands: []

data/.ace-defaults/tmux/windows/cc.yml

@@ -0,0 +1,14 @@
+# Claude Code workspace: claude (left) | nvim + git status (center) | taskflow (right)
+direction: horizontal
+panes:
+  - preset: claude
+    size: "34%"
+  - direction: vertical
+    size: "32%"
+    panes:
+      - preset: nvim
+      - commands:
+          - ace-git status
+  - commands:
+      - ace-task list
+    size: "34%"

data/.ace-defaults/tmux/windows/work-on-task.yml

@@ -0,0 +1,16 @@
+# Work-on task orchestration workspace:
+# - Left: cc running /as-assign-drive
+# - Middle: nvim on active assignment cache (via .ace-local/assign/.latest) + shell status
+# - Right: status from task and assignment
+direction: horizontal
+panes:
+  - preset: work-on-task-cc
+    size: "34%"
+  - direction: vertical
+    size: "32%"
+    panes:
+      - preset: nvim 
+      - commands:
+          - ace-git status
+  - preset: work-on-task-status
+    size: "34%"

data/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.11.0] - 2026-03-24
+
+### Changed
+- Removed demo GIF from README to streamline the landing page.
+
+## [0.10.2] - 2026-03-23
+
+### Changed
+- Refreshed package README layout, quick-link navigation, and section flow to align with the current package pattern.
+
+## [0.10.1] - 2026-03-22
+
+### Changed
+- Renamed overseer work-on pane/window presets from `work-on-tasks*` to `work-on-task*` for canonical preset naming consistency.
+
+## [0.10.0] - 2026-03-22
+
+### Added
+- Added `work-on-tasks` pane and window presets for overseer-driven work-on workflows.
+
+## [0.9.2] - 2026-03-22
+
+### Fixed
+- Restore YAML composition examples for pane and window preset reuse in usage docs.
+
+## [0.9.1] - 2026-03-22
+
+### Fixed
+- Include `docs/**/*` in gemspec so documentation ships with the gem.
+- Fix VHS tape output path to `docs/demo/` instead of `.ace-local/demo/`.
+- Clarify `on_project_exit` as reserved/not-yet-implemented in usage docs.
+
+## [0.9.0] - 2026-03-22
+
+### Added
+- Reworked package documentation with a new landing-page README, tutorial getting-started guide, full usage reference, handbook catalog, demo assets, and aligned gem metadata messaging.
+
+## [0.8.0] - 2026-03-21
+
+### Changed
+- Expanded `TS-TMUX-001` E2E lifecycle coverage with a new window-management goal and tightened artifact-evidence contracts for preset discovery and session start flows.
+
+## [0.7.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.7.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.6.3] - 2026-03-17
+
+### Fixed
+- Updated CLI help-output assertions to match `ace-support-cli` output casing (`COMMANDS`/`EXAMPLES`).
+
+## [0.6.2] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.6.1] - 2026-02-23
+
+### Changed
+- Centralized error class hierarchy: PresetNotFoundError and NotInTmuxError now inherit from Ace::Tmux::Error
+
+### Technical
+- Updated internal dependency version constraints to current releases
+
+## [0.6.0] - 2026-02-22
+
+### Changed
+
+- **Breaking**: Removed DWIM context-aware default routing
+  - `ace-tmux` (no args) now shows help instead of routing to `start`/`window` based on TMUX env
+  - Users must now use explicit commands: `ace-tmux start`, `ace-tmux window`, `ace-tmux list`
+  - Unknown first arguments are no longer prepended with default command
+- Migrated to standard help pattern (ADR-023)
+  - Added `HELP_EXAMPLES` constant with usage examples
+  - Registered `HelpCommand` for `help`, `--help`, `-h`
+  - Updated `REGISTERED_COMMANDS` to include descriptions
+
+### Technical
+
+- Updated CLI tests to test standard help pattern instead of DWIM routing
+
+## [0.5.5] - 2026-02-20
+
+### Fixed
+- `WindowManager#detect_current_session` now checks `ACE_TMUX_SESSION` env var first, enabling E2E test isolation without requiring an active tmux session
+
+## [0.5.4] - 2026-02-19
+
+### Fixed
+
+- Fix "index N in use" error when creating tmux windows in sessions with `base-index` set
+
+## [0.5.3] - 2026-02-19
+
+### Fixed
+
+- Include stderr details in "Failed to create window" error message for better debugging
+
+## [0.5.2] - 2026-02-14
+
+### Fixed
+
+- First window name now always derives from the effective working directory (`--root` override > preset `root:` > CWD), matching the existing behavior of `ace-tmux window --root`
+
+## [0.5.1] - 2026-02-14
+
+### Fixed
+
+- Bundler/Ruby environment variables (`BUNDLE_GEMFILE`, `BUNDLE_BIN_PATH`, `RUBYOPT`, `RUBYLIB`) no longer leak into tmux sessions and spawned processes
+  - `bin/ace-tmux` cleans env vars from its own process after Bundler setup
+  - `SessionManager` unsets env vars from the tmux session environment via `set-environment -u`
+  - New `TmuxCommandBuilder.set_environment` atom for `tmux set-environment` commands
+
+## [0.5.0] - 2026-02-14
+
+### Changed
+
+- **Breaking**: Gem renamed from `ace-support-tmux` to `ace-tmux` (task 266)
+  - Namespace changed from `Ace::Support::Tmux` to `Ace::Tmux`
+  - Require path changed from `ace/support/tmux` to `ace/tmux`
+  - Binary name (`ace-tmux`) and config path (`.ace/tmux/`) unchanged
+  - No backward compatibility shims provided (per ADR-024)
+
+## [0.4.1] - 2026-02-14
+
+### Fixed
+
+- `ace-tmux --root /path` inside tmux now adds a window instead of erroring with "sessions should be nested" — unknown-arg routing is now context-aware
+
+## [0.4.0] - 2026-02-14
+
+### Added
+
+- Context-aware default presets — `ace-tmux` with no arguments starts default session (outside tmux) or adds default window (inside tmux)
+- `defaults` config section in `config.yml` with `session` and `window` default preset names
+- `--root`/`-r` option on `start` command for working directory override (parity with `window` command)
+- `inside_tmux?` detection method on CLI for context-aware routing
+
+### Changed
+
+- `preset` argument is now optional on both `start` and `window` commands — falls back to configured defaults
+
+## [0.3.4] - 2026-02-13
+
+### Fixed
+
+- Session creation failing with `base-index 1` tmux config by using window IDs instead of index-based targeting
+
+## [0.3.3] - 2026-02-13
+
+### Fixed
+
+- Window targeting uses unique window ID (`@42` format) instead of name-based resolution, eliminating "can't find window" errors when duplicate names exist
+- Window name derived from `--root` basename instead of preset's `name` field — `ace-tmux window cc --root /path/to/project` names the window `project`
+
+### Added
+
+- `--name`/`-n` flag on `ace-tmux window` for explicit window name override (priority: `--name` > `--root` basename > preset argument)
+
+### Changed
+
+- Removed `name: cc` from cc.yml window preset — presets define layout, not window names
+
+## [0.3.2] - 2026-02-13
+
+### Fixed
+
+- Pane startup race condition — `send-keys` commands now execute after `select-layout`, preventing resize artifacts in apps like nvim/LazyVim
+
+### Changed
+
+- Restored per-pane `sleep 0.15` in claude and nvim pane presets — shell-side sleep absorbs async resize signals that Ruby-side delay cannot
+
+## [0.3.1] - 2026-02-13
+
+### Fixed
+
+- Per-leaf pane `root` overrides now apply in nested layouts — previously all nested panes used the window/session root
+- `LayoutStringBuilder` pane ID assignment falls back to sequential index when `pane_ids` array is shorter than expected
+
+## [0.3.0] - 2026-02-12
+
+### Added
+
+- Nested pane layouts with arbitrary tree structure via `direction` key in YAML presets
+- `LayoutNode` model — tree node (leaf or container) for nested layout representation
+- `LayoutStringBuilder` atom — pure function that generates tmux custom layout strings with CRC16 checksum from a `LayoutNode` tree
+- `list_panes` and `display_message_target` commands in `TmuxCommandBuilder`
+- `layout_tree` attribute and `nested_layout?` predicate on `Window` model
+- Recursive preset resolution for nested containers in `PresetResolver`
+- Nested pane setup flow in `SessionManager` and `WindowManager` — flat splits → list-panes → layout string → select-layout
+
+## [0.2.0] - 2026-02-12
+
+### Added
+
+- Generic `options` hash on Window and Pane models — pass-through for any tmux option via `set-window-option` and `set-option -p`
+- `--root`/`-r` flag on `ace-tmux window` command to set working directory for the new window and all its panes
+- `set_window_option` and `set_pane_option` commands in TmuxCommandBuilder
+
+### Changed
+
+- Default session preset: 3-pane layout (claude left 40%, shell right-top, nvim right-bottom) with `main-vertical` layout and `main-pane-width` option
+- Code-editor window preset: 3 equal vertical panes (claude | shell | nvim) with `even-horizontal` layout
+
+## [0.1.0] - 2026-02-12
+
+### Added
+
+- Initial release of ace-support-tmux
+- Composable tmux session management via YAML presets
+- Deep-merge composition at session, window, and pane levels
+- `ace-tmux start <session-preset>` — Create tmux session from YAML preset
+- `ace-tmux window <window-preset>` — Add window to existing session from preset
+- `ace-tmux list [sessions|windows|panes]` — List available presets
+- ACE config cascade integration (project > user > gem defaults)
+- tmuxinator-compatible YAML keys
+
+
+## [0.5.6] - 2026-02-22
+
+### Fixed
+- Standardized quiet, verbose, debug option descriptions to canonical strings

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+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.

data/README.md

@@ -0,0 +1,40 @@
+<div align="center">
+  <h1> ACE - TMUX </h1>
+
+  Composable tmux sessions from YAML presets, with window injection into active sessions.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-tmux"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-tmux.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+`ace-tmux` helps you standardize terminal workspaces with preset-driven sessions, reusable windows, and nested pane layouts. You can spin up a full workspace from a session preset or inject a focused window into an already-running tmux session, with config cascade across project, user, and gem defaults.
+
+## How It Works
+
+1. Define session and window layouts in YAML presets stored in `.ace/tmux/` (project), `~/.ace/tmux/` (user), or gem defaults.
+2. Run `ace-tmux start [PRESET]` to create a full session or `ace-tmux window [PRESET]` to inject a window into the current session.
+3. Presets are deep-merged through the config cascade, so project-level overrides layer cleanly on top of shared defaults.
+
+## Use Cases
+
+**Start or attach to a preset-backed session** - run `ace-tmux start [PRESET]` to create a session from YAML presets, or attach to an existing session with the same name, integrating panes for [ace-task](../ace-task) status, [ace-git](../ace-git) info, and editor windows.
+
+**Inject windows into running sessions** - run `ace-tmux window [PRESET]` to add a new window from presets without recreating the current session, useful for spinning up focused tool or test panes on the fly.
+
+**Compose nested pane layouts in YAML** - use `direction` and nested pane containers to model custom split trees beyond tmux built-in layouts, keeping workspace structure version-controlled alongside your project.
+
+**Reuse presets through config cascade** - load project presets from `.ace/tmux/`, personal presets from `~/.ace/tmux/`, and gem defaults via `.ace-defaults/tmux/` with deep-merge behavior so teams share a baseline while individuals customize.
+
+**Orchestrate task-focused workspaces** - pair with [ace-overseer](../ace-overseer) and [ace-assign](../ace-assign) for assignment-driven worktree and tmux orchestration that spins up isolated workspaces per task.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/demo/ace-tmux-getting-started.tape.yml

@@ -0,0 +1,30 @@
+---
+description: Showcase ace-tmux preset discovery, session start, and window management
+tags:
+- ace-tmux
+- docs
+- getting-started
+settings:
+  font_size: 16
+  width: 960
+  height: 540
+  format: gif
+scenes:
+- name: Discover available presets (sessions, windows, panes)
+  commands:
+  - type: ace-tmux list
+    sleep: 4s
+- name: Start a session from a preset without attaching
+  commands:
+  - type: ace-tmux start default --detach
+    sleep: 3s
+- name: Add a window to the running session
+  commands:
+  - type: ace-tmux window cc --session default
+    sleep: 3s
+- name: Verify session is running with windows
+  commands:
+  - type: tmux list-windows -t default
+    sleep: 4s
+teardown:
+- cleanup

data/docs/getting-started.md

@@ -0,0 +1,86 @@
+---
+doc-type: user
+title: ace-tmux Getting Started
+purpose: Tutorial for creating sessions and adding windows with ace-tmux.
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-tmux
+
+## Prerequisites
+
+- `tmux` installed and available on PATH
+- ACE toolchain available in your repository shell
+
+## Installation
+
+Install from RubyGems: `gem install ace-tmux`.
+
+Verify command availability: `ace-tmux --help`.
+
+## Start Your First Session
+
+Run: `ace-tmux start`.
+
+`ace-tmux` resolves the default session preset from `defaults.session` in config.
+
+## Add a Window to a Running Session
+
+From inside tmux, run: `ace-tmux window`.
+
+`ace-tmux` resolves the default window preset from `defaults.window` in config.
+
+## Create a Custom Window Preset
+
+Create `.ace/tmux/windows/cc.yml`:
+
+```yaml
+direction: horizontal
+panes:
+  - preset: claude
+    size: "35%"
+  - direction: vertical
+    size: "30%"
+    panes:
+      - preset: nvim
+      - commands:
+          - ace-git status
+  - commands:
+      - ace-task list
+    size: "35%"
+
+```
+
+Use it in a session or add it directly with `ace-tmux window cc`.
+
+
+## Nested Layouts
+
+`direction: horizontal` creates columns, `direction: vertical` creates rows, and children can be mixed recursively.
+
+
+```text
+┌────────────┬──────────┬──────────────┐
+│            │  nvim .  │              │
+│   claude   │──────────│  task list   │
+│    35%     │ git stat │    35%       │
+│            │   30%    │              │
+└────────────┴──────────┴──────────────┘
+
+```
+
+## Common Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ace-tmux start [PRESET]` | Start or attach to a session preset |
+| `ace-tmux window [PRESET]` | Add a window preset to a running session |
+| `ace-tmux list` | Show available session/window/pane presets |
+
+## Next steps
+
+- Define project-level presets in `.ace/tmux/`.
+- Override personal defaults in `~/.ace/tmux/`.
+- See [Usage Guide](usage.md) for full command and config reference.

data/docs/handbook.md

@@ -0,0 +1,31 @@
+---
+doc-type: user
+title: ace-tmux Handbook Reference
+purpose: Catalog of package-owned agent skills and workflows in ace-tmux.
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Handbook Reference
+
+## Skills
+
+No package-owned canonical skills are currently published under `ace-tmux/handbook/skills/`.
+
+## Workflows
+
+No package-owned workflow instructions are currently published under `ace-tmux/handbook/workflow-instructions/`.
+
+## Guides
+
+No package-owned guides are currently published under `ace-tmux/handbook/guides/`.
+
+## Templates
+
+No package-owned templates are currently published under `ace-tmux/handbook/templates/`.
+
+## Related Documentation
+
+- [Getting Started](getting-started.md)
+- [Usage Guide](usage.md)