tmu-reference

name	tmu-reference
description	Reference for using, explaining, troubleshooting, or developing the tmu tmux wrapper in this repository. Use this skill whenever a user asks about `tmu` commands, layout storage, stack workspace behavior, session/window TUI keys, tmux control mode integration, project structure, configuration, installation, testing, or implementation details.

tmu Reference

Use this skill as the entry point for questions and changes concerning tmu. Treat the repository as the source of truth: verify behavior in the referenced files before answering when the current implementation may have changed.

Requirements are Go 1.26 for development, tmux 3.5 or later, and an invoking tmux pane for running commands.

Project overview

tmu is a Go 1.26 tmux utility wrapper. It communicates with tmux exclusively through control mode (tmux -C) and provides:

• declarative pane layout construction;
• a structured stack workspace;
• a Bubble Tea session manager;
• a Bubble Tea window manager.

Commands must run inside tmux because tmu uses $TMUX_PANE to target the pane that invoked it. The control client has its own implicit current target, so tmu does not rely on target-less tmux commands for context-sensitive operations. tmu version is the exception and can run outside tmux.

Command reference

Layout commands

tmu layout apply NAME
tmu layout reset

Define layouts as versioned split and pane trees in <UserConfigDir>/tmu/config.json. Split children use integer sibling weights; horizontal means left-to-right and vertical means top-to-bottom. layout apply validates the complete tree and current window dimensions before closing panes, then keeps the invoking pane as the first depth-first leaf and creates the rest.

Raw tmux layout strings and layout add are not supported. Read docs/layouts.md for the complete schema, limits, example, weight allocation, destructive behavior, and migration instructions.

The first normal command initializes a missing config from config.example.json, including the ide, legacy, ai, and grid layouts ported from the legacy tml script.

layout reset closes every pane in the invoking pane's window except the invoking pane.

Implementation: internal/layout/service.go.

Stack commands

tmu stack
tmu stack count N
tmu stack focus

tmu stack replaces the current window's panes with these regions:

• upper-left main pane;
• three lower-left sub-panes;
• side focus pane;
• a narrow right column containing the configured number of stack panes.

The default stack count is 30. tmu stack count N persists a value from 1 to 1000. Before resetting existing panes, tmu verifies that the window is at least 20 columns wide and tall enough for the requested stack count. A count of N requires at least 2*N-1 rows, so the default 30 requires 59 rows.

Run tmu stack focus from a stack pane to swap it into the focus region. tmu records stack membership in the pane option @tmu_stack_member and the focused pane ID in the window option @tmu_focus_pane.

Building a stack is destructive to the current pane layout: it retains the invoking pane as main and closes the other panes after precondition checks pass.

Implementation: internal/stack/service.go.

Window background color

tmu bgcolor a1b2c3
tmu bgcolor '#A1B2C3'

bgcolor requires exactly six hexadecimal RGB digits, with an optional leading #, and normalizes letters to lowercase. It changes the background component of the invoking pane's window-scoped window-style and window-active-style. Existing foreground and style attributes are retained. The change is limited to the running tmux server; it does not persist in the tmu config, has no reset form, and does not change pane, session, or global options.

tmux 3.5 distinguishes a window-local option from its inherited effective value: show-options -w -qv returns no line for an unset local option, while show-options -w -A -v returns the inherited value. Appending only bg=... to an unset local style masks inherited foreground and attributes, so the service materializes the effective style before changing its background. If the second option update fails, it restores both options' original local values or unsets them to restore inheritance; update and all rollback errors are retained.

Implementation: internal/bgcolor/service.go.

Session TUI

tmu session

Keys:

• j or down: move down;
• k or up: move up;
• enter: switch to the selected session;
• n: create a session;
• d: request deletion, followed by y to confirm;
• q, esc, or ctrl+c: quit.

The * marker identifies the invoking pane's current session. The detail text shows whether any tmux client is attached to the session. Switching explicitly targets the terminal that launched tmu; if that terminal cannot be resolved, tmu refuses the switch.

Window TUI

tmu window

The window TUI is scoped to the invoking pane's session. It supports the session TUI keys and adds r to rename the selected window. Creating a window uses the first available index in the invoking session. Successful session or window switches exit the TUI so an interactive process is not left hidden in the old pane.

TUI implementation: internal/tui/model.go and internal/tui/backends.go. tmux resource operations: internal/tmux/resources.go.

Version command

tmu version

Local builds report dev. GitHub Release builds report the SemVer tag embedded by GoReleaser. Implementation: internal/version/version.go.

Configuration

tmu uses Go's user configuration directory and stores its data at:

<UserConfigDir>/tmu/config.json

On the primary Unix-like target this is normally ~/.config/tmu/config.json. The JSON document has version: 1, structured named layouts, and stack_count. Missing files are initialized with the four built-in layouts and stack count 30. Existing files without version 1, raw layout strings, unknown fields, and invalid node combinations are rejected. Writes use a mode-0600 temporary file and an atomic rename.

Implementation: internal/config/store.go.

Installation and verification

Install the command with:

go install github.com/kyoh86/tmu/cmd/tmu@latest

For repository development, run:

make check
make build

make release-snapshot validates all Linux/macOS amd64/arm64 release artifacts without publishing. Pushing a valid v-prefixed SemVer tag runs the release workflow; prerelease tags are published as GitHub pre-releases.

Use an isolated tmux socket for destructive integration tests. Do not run stack, reset, window deletion, or session deletion tests against the developer's default tmux server.

Internal architecture

• cmd/tmu/main.go: process entry point and exit handling.
• internal/app/app.go: command parsing and dependency assembly.
• internal/tmux/client.go: subprocess execution and control protocol framing.
• internal/tmux/resources.go: typed session and window operations.
• internal/config/store.go: configuration persistence.
• internal/bgcolor/service.go: window background style composition and rollback.
• internal/layout/plan.go: weight allocation and geometry validation.
• internal/layout/service.go: declarative layout application and reset.
• internal/stack/service.go: stack geometry, metadata, and focus swapping.
• internal/tui/: Bubble Tea model and tmux adapters.

The application depends on the narrow tmux.Executor interface. Tests use recording executors to verify exact tmux command contracts without modifying a live server.

Control mode behavior relevant to tmu

A response starts with %begin and ends with %end or %error. Notifications outside a response block are ignored. tmu rejects nested, unmatched, missing, or unfinished response frames instead of treating truncated output as success.

Window option reads and writes for bgcolor use show-options -w and set-option -w, always with -t $TMUX_PANE. Do not rely on the control client's implicit current window: it may differ from the window containing the invoking pane.

Session and window switches use switch-client -c <client-tty> -t <target>. Pane and window operations propagate $TMUX_PANE or resolve its session before issuing a command. Preserve this explicit-target rule when extending tmu.

Answering and modification workflow

1. Identify whether the question concerns CLI behavior, configuration, TUI, control mode, or internal architecture.
2. Read the implementation file listed in the corresponding section.
3. Check tests for boundary and error behavior before stating a contract.
4. For changes, preserve explicit tmux targets and keep UI, state, persistence, and subprocess I/O separated.
5. Report destructive effects and terminal-size constraints prominently.
6. Run the repository verification commands before declaring a change complete.