A YAML-driven automation tool for managing complex tmux sessions, windows, and panes with precision and idempotency.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install tmux-manager
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install tmux-manager using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is tmux-manager?
tmux-manager is a sophisticated management utility designed to orchestrate tmux environments through declarative YAML configuration files. It enables developers to define intricate session structures, including specific working directories, environment variables, and pre/post-execution hooks. By utilizing this within the Openclaw Skills ecosystem, users can automate the deployment of their development environments with a single command.
The tool focuses on idempotency, ensuring that existing sessions are respected while missing ones are seamlessly created. Its advanced filtering capabilities, such as session and window grouping, allow for granular control over large-scale terminal setups, making it an essential tool for developers managing multiple microservices or complex project environments.
tmux-manager Use Cases
- Automating the startup of multi-window development environments for specific projects.
- Restarting a specific group of services (e.g., all windows tagged with 'dev') across multiple tmux sessions.
- Monitoring live output from specific panes using the tail functionality without manually attaching to sessions.
- Deploying standardized terminal layouts across different machines using a shared YAML configuration.
- Sending remote commands to running sessions for CI/CD or automation scripts.
How tmux-manager Works
- The manager reads a
tmux-sessions.yamlconfiguration file located in its script directory or a path specified by the user. - It parses the selectors (e.g.,
--all,--session-group, or specific session names) to identify target environments. - For creation tasks, it validates the current tmux state and skips sessions that are already active to maintain idempotency.
- It executes defined
pre_hookcommands on the host shell before initiating the tmux session creation. - It leverages tmux commands to build the requested sessions, windows, and panes, applying environment variables and layouts as defined.
- Finally, it executes any
post_hookcommands and sets the focus to the designated window if specified.
tmux-manager Setup
To integrate this into your workflow, ensure you have uv and tmux installed on your system. You can install the dependencies and deploy the script using the following steps:
# Install dependencies via Homebrew
brew install uv tmux
# Deploy the manager
# Copy tmux-manager.py and your tmux-sessions.yaml to your desired directory
# Validate your configuration before first run
uv run scripts/tmux-manager.py --validate
tmux-manager Data Schema & Taxonomy
The skill organizes data through a YAML structure that defines the hierarchy of sessions and windows.
| Field | Level | Description |
|---|---|---|
name |
Session | Unique identifier for the tmux session. |
session_group |
Session | Tag used for bulk targeting multiple sessions. |
working_dir |
Session/Window | The directory the shell or command starts in. |
windows |
Session | A list of window objects containing names and commands. |
window_group |
Window | Tag used to filter specific windows within sessions. |
env |
Session/Window | Key-value pairs of environment variables to export. |
tmux-manager Advanced Features
- Idempotent Operations: Automatically detects running sessions to prevent duplicate creation errors.
- Group Filtering: Supports complex targeting by combining
--session-groupand--window-groupto isolate specific tasks. - Execution Hooks: Define
pre_hookandpost_hookshell commands with configurable failure behaviors (warnorabort). - Remote Interaction: Use
--send-keysto inject commands into active windows or--tailfor real-time output streaming. - Config Validation: Built-in
--validateflag to catch syntax errors and typos in your YAML definitions.
SKILL.md
Loading
Related Openclaw Skills
Conviction.fm
An AI agent skill for competing in daily crypto prediction pools using natural language strategies and automated execution.
Diffbot
Diffbot is an AI-powered extraction skill that transforms unstructured web content into structured data like articles, products, and organization records.
flux-image
A high-performance AI image generation and editing skill powered by Black Forest Labs Flux models via AceDataCloud.
arh-pr-workflow
A comprehensive automation skill for managing the lifecycle of feature branches and stacked pull requests using Uber's arh CLI tool.
Multi-Agent Research Framework
A sophisticated multi-agent collaborative research framework designed to coordinate domain-specific AI experts for complex project execution.
PayPal Financial Information Skill
A specialized automation tool for extracting and organizing public PayPal product descriptions, fee structures, and help center information.
Featured*
