tmux-macro

Monitor tmux panes for pattern matches and auto-execute directives.

tmux-macro watches a tmux pane for text patterns you define, then automatically sends keystrokes when those patterns appear. Useful for auto-responding to prompts, restarting crashed processes, or automating repetitive terminal workflows.

Requirements

• Node.js >= 18
• tmux

Install

npm install -g tmux-macro

Usage

tmux-macro [options]

Options

| Flag | Description | | ---- | ----------- | | -w, --watch | Watch mode: select pane, then monitor and auto-execute matching rules | | -c, --config <path> | Use a custom rules file instead of .rules.json | | -v, --version | Show version number | | -h, --help | Show help message |

Running without flags launches the interactive TUI.

Quick Start

1. Start tmux and open the panes you want to monitor
2. Run tmux-macro — it launches a TUI showing your active panes
3. Select a pane by number
4. Press d to open the directive wizard and create your first rule
5. The dashboard monitors the pane and executes directives when patterns match

Features

• TUI Dashboard — fullscreen terminal interface showing monitoring status, active rules, and a live activity log
• Pattern Matching — rules define string patterns to match against captured pane content; all patterns in a rule must match to trigger
• Directive Execution — when a rule fires, commands are sent to the pane as tmux send-keys (e.g., keystrokes, Enter, text input)
• Interactive Wizard — press d during monitoring to create new rules by capturing the current pane state and selecting match patterns
• Auto Rearm — after a rule fires, it enters a cooldown period then re-arms automatically, so repeating patterns are handled without intervention

Watch Mode

Watch mode runs headless after pane selection — useful for background automation:

tmux-macro --watch

1. Select a pane (same picker as TUI mode)
2. Monitor and auto-execute rules silently
3. Logs fired rules to stderr: [ISO-8601] Fired: rule-name
4. Stop with Ctrl+C or SIGTERM

Configuration

tmux-macro searches for .rules.json starting from the current directory, walking up to the filesystem root, then falling back to ~/.rules.json. Use -c to specify a custom path. Create it manually or use the built-in wizard.

{
    "rules": [
        {
            "name": "auto-confirm",
            "match": ["Do you want to continue?", "[Y/n]"],
            "commands": ["y", "Enter"]
        }
    ]
}

Each rule has:

| Field | Type | Description | | ---------- | ---------- | ------------------------------------------------------ | | name | string | Identifier for the rule (shown in dashboard) | | match | string[] | All strings must appear in the pane content to trigger | | commands | string[] | Sent as tmux send-keys when the rule fires |

How It Works

1. Observe — every second, tmux-macro captures the content of the monitored pane
2. Match — each armed rule checks if all its match strings appear in the captured content
3. Execute — the first matching rule fires, sending its commands to the pane via tmux
4. Cooldown — the fired rule is disarmed for 30 polls, then re-arms after 3 consecutive non-matches

Keybindings

| Key | Action | | -------- | --------------------- | | d | Open directive wizard | | q | Quit | | Ctrl+C | Quit |

License

MIT