muxrun

muxrun

/mʌks.rʌn/

Managing multiple processes across terminals gets messy: scattered tabs, no clear picture of what's running where, and manual restarts every time you switch branches or worktrees.

muxrun keeps it simple — muxrun up to start everything, muxrun ps to see what's running and from which directory, muxrun up again to restart.

Quick Start

claude plugin marketplace add https://github.com/tkuramot/muxrun
claude plugin install muxrun@muxrun

1. Install muxrun:

go install github.com/tkuramot/muxrun@latest

2. Create muxrun.toml in your project directory:

[[group]]
name = "myapp"
dir = "."

  [[group.app]]
  name = "server"
  cmd = "go run main.go"

3. Run:

muxrun up

This starts the server app inside a tmux session named muxrun-myapp. Use muxrun down to stop it.

Overview

muxrun organizes applications into groups. Each group becomes a tmux session, and each app becomes a window within that session.

muxrun
├── Group A (tmux session)
│   ├── App 1 (tmux window)
│   └── App 2 (tmux window)
└── Group B (tmux session)
    └── App 3 (tmux window)

Requirements

• tmux 3.0+

Configuration

Config file resolution

muxrun looks for a config file in the following order:

1. --config / -c flag (explicit path, skips other lookup)
2. muxrun.toml in the current directory, then parent directories up to the filesystem root

Minimal example

[[group]]
name = "backend"
dir = "."

  [[group.app]]
  name = "api"
  cmd = "go run main.go"

Full example with file watching

[[group]]
name = "backend"
dir = "."

  [[group.app]]
  name = "api"
  cmd = "go run main.go"
  watch = { enabled = true, exclude = ["_test\\.go$"] }

  [[group.app]]
  name = "worker"
  cmd = "go run worker.go"

[[group]]
name = "frontend"
dir = "./frontend"

  [[group.app]]
  name = "dev"
  cmd = "npm run dev"

Fields

See docs/config.md for the full field reference, watch configuration, and validation rules.

When watch is enabled, muxrun starts a background daemon that restarts the app on file changes. The daemon starts with muxrun up and stops with muxrun down.

Usage

muxrun up — Start applications

muxrun up                           # Start all groups
muxrun up backend                   # Start a specific group
muxrun up backend frontend          # Start multiple groups

muxrun down — Stop applications

down accepts the same arguments as up.

muxrun down                         # Stop all groups
muxrun down backend                 # Stop a specific group

[!WARNING] Use muxrun down to stop sessions. Killing sessions directly with tmux kill-session may leave file watch daemons running.

muxrun ps — Check status

$ muxrun ps
GROUP       APP       STATUS    PID      DIR
backend     api       running   12345    /home/user/repo/cmd/api
backend     worker    running   12346    /home/user/repo/cmd/worker
frontend    dev       stopped   -        /home/user/repo/frontend

muxrun logs — View pane output

muxrun logs backend api       # Show buffered output for an app
muxrun logs -f backend api    # Stream output in real-time (Ctrl-C to stop)

[!TIP] If you're familiar with tmux, each app runs in its own window inside a muxrun-<group> session — attach directly for full scrollback and search.

muxrun check — Validate config file

muxrun check

Tips

Using with git worktrees

When dir is a relative path, it is resolved relative to the muxrun.toml location. Copy muxrun.toml into each worktree at creation time to treat each worktree as an independent environment.

[[group]]
name = "backend"
dir = "."          # resolved relative to muxrun.toml location

  [[group.app]]
  name = "api"
  cmd = "go run main.go"