ACE - TMUX

Composable tmux sessions from YAML presets, with window injection into active sessions. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates

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. Use ace-tmux start ... --name <session> when you need multiple concurrent sessions from the same preset.
  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 status, ace-git info, and editor windows. Add --name to reuse the preset under a different runtime session name.

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 and ace-assign for assignment-driven worktree and tmux orchestration that spins up isolated workspaces per task.

Testing

  • ace-test ace-tmux runs deterministic fast-layer tests under test/fast/.
  • ace-test ace-tmux feat runs deterministic feature tests when test/feat/ coverage exists.
  • ace-test ace-tmux all runs full package deterministic coverage.
  • ace-test-e2e ace-tmux runs retained workflow scenarios under test/e2e/.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates | Part of ACE