normful run-in-tmux
Creates a tmux session with one or more commands running in separate split panes. Automatically detects the git repository root and generates a unique session name.
When to use
- User wants to run development commands (e.g.,
npm run dev,cargo watch) - User needs multiple terminal panes running different commands
- User wants to start a background process that persists after terminal closes
How to run
The script is located at scripts/run-in-tmux. Execute it using uv run:
uv run scripts/run-in-tmux -c "npm run dev"
Usage
# Single command (JSON output)
uv run scripts/run-in-tmux -c "npm run dev" --json
# Multiple commands (each gets its own pane)
uv run scripts/run-in-tmux -c "npm run dev" -c "npm test" --json
Options
| Flag | Description |
|---|---|
-c, --command |
Command to run (required, repeatable) |
--json |
Output JSON to stdout |
--plain |
Line-based plain text output |
-q, --quiet |
Suppress non-essential output |
-v, --verbose |
Show debug details |
--no-color |
Disable colored output |
--version |
Show version and exit |
Output
JSON format (--json)
uv run scripts/run-in-tmux -c "echo hello" -c "echo world" --json
{
"success": true,
"session_name": "picadillo-1f4f1afa",
"commands": ["echo hello", "echo world"],
"panes": 2,
"working_directory": "/Users/norman/code/picadillo",
"attach_command": "tmux attach -t picadillo-1f4f1afa",
"peek_commands": [
"tmux capture-pane -t picadillo-1f4f1afa.0 -p",
"tmux capture-pane -t picadillo-1f4f1afa.1 -p"
],
"kill_command": "tmux kill-session -t picadillo-1f4f1afa"
}
Session naming
Session names follow the pattern <repo-slug>-<hash>:
repo-slug: First 8 characters of the git repository basenamehash: 8-character MD5 hash of the repo path + commands
This ensures unique sessions for different commands in the same repo.
Requirements
- Python 3.10+
- tmux installed and running
- Must be in a git repository
- Dependencies:
typer,rich(auto-installed via uv)