Tmux session manager for development environments. Define tasks in taskmux.toml, start them in dependency order, monitor health, auto-restart on failure, read persistent timestamped logs. Every command supports --json for agents and scripts.

• Task orchestration — start/stop/restart tasks with dependency ordering and signal escalation
• Persistent logs — timestamped, rotated, survives session kill (~/.taskmux/logs/)
• Health checks — custom commands with retries, used for dependency gating and auto-restart
• Restart policies — no, on-failure (default), always with exponential backoff
• JSON output — --json on every command for programmatic consumption
• Event history — lifecycle events recorded to ~/.taskmux/events.jsonl
• Lifecycle hooks — before/after start/stop at global and per-task level
• Port cleanup — kills orphaned listeners before starting
• Agent context — taskmux init injects usage instructions into Claude/Codex/OpenCode context files
• Daemon mode — WebSocket API + config watching + health monitoring
• Tmux native — tmux attach to see live output, interact with tasks

Requires tmux and Python 3.11+.

uv tool install taskmux

All commands support --json for machine-readable output.

# Lifecycle
taskmux start                    # start all auto_start tasks in dependency order
taskmux start <task> [task2...]  # start specific tasks
taskmux start -m                 # start + monitor health + auto-restart
taskmux stop                     # graceful stop all (C-c → SIGTERM → SIGKILL)
taskmux stop <task> [task2...]   # stop specific tasks
taskmux restart                  # restart all
taskmux restart <task>           # restart specific tasks
taskmux kill <task>              # hard-kill (SIGKILL + destroy window)

# Info
taskmux status                   # task overview (aliases: list, ls)
taskmux health                   # health check table
taskmux inspect <task>           # full task state as JSON
taskmux events                   # recent lifecycle events
taskmux events --task server     # filter by task
taskmux events --since 1h        # filter by time

# Logs — persistent, timestamped, stored at ~/.taskmux/logs/
taskmux logs                     # interleaved logs from all tasks
taskmux logs <task>              # logs for one task
taskmux logs -f [task]           # follow live
taskmux logs -n 200 <task>       # last N lines
taskmux logs -g "error"          # grep all tasks
taskmux logs -g "err" -C 5      # grep with context
taskmux logs --since 5m          # last 5 minutes
taskmux logs --since "2024-01-01T14:00"
taskmux logs-clean [task]        # delete log files

# Config
taskmux add <task> "<command>"   # add task to taskmux.toml
taskmux remove <task>            # remove task (kills if running)
taskmux init                     # create taskmux.toml + inject agent context
taskmux init --defaults          # non-interactive

# Monitoring
taskmux watch                    # watch config, reload on change
taskmux daemon --port 8765       # daemon: WebSocket API + health + config watch

stop and kill mark tasks as manually stopped — no auto-restart even with restart_policy = "always". restart or start clears this flag.

Config file: taskmux.toml in the current directory.

name = "myproject"

[tasks.server]
command = "npm run dev"

[tasks.build]
command = "npm run build:watch"

[tasks.db]
command = "docker compose up postgres"
auto_start = false

name = "fullstack-app"

[tasks.db]
command = "docker compose up postgres redis"
health_check = "pg_isready -h localhost -p 5432"
health_interval = 3

[tasks.migrate]
command = "python manage.py migrate && echo done && sleep infinity"
cwd = "apps/api"
depends_on = ["db"]
health_check = "test -f .migrate-complete"

[tasks.api]
command = "python manage.py runserver 0.0.0.0:8000"
cwd = "apps/api"
port = 8000
depends_on = ["migrate"]
health_check = "curl -sf http://localhost:8000/health"
stop_grace_period = 10

[tasks.worker]
command = "celery -A myapp worker -l info"
cwd = "apps/api"
depends_on = ["db"]
restart_policy = "always"
max_restarts = 10
restart_backoff = 3.0

[tasks.web]
command = "bun dev"
cwd = "apps/web"
port = 3000
depends_on = ["api"]
health_check = "curl -sf http://localhost:3000"

[tasks.storybook]
command = "bun storybook"
cwd = "apps/web"
auto_start = false

On taskmux start: db starts first → migrate + worker wait for db health → api waits for migrate → web waits for api → storybook skipped (manual).

Every command supports --json. Key schemas:

taskmux status --json            # {"session": "x", "running": true, "tasks": [...]}
taskmux health --json            # {"healthy_count": 2, "total_count": 3, "tasks": [...]}
taskmux start server --json      # {"ok": true, "task": "server", "action": "started"}
taskmux logs server --json       # {"task": "server", "lines": ["2024-01-01T14:00:00 ..."]}
taskmux events --json            # {"events": [...], "count": 10}

Error: {"ok": false, "error": "Task 'ghost' not found in config"}

Enforced by start --monitor and daemon.

restart_policy and auto_start are orthogonal — auto_start controls initial launch, restart_policy controls what happens after exit.

Backoff: restart_backoff ^ attempt seconds (capped 60s). Resets after 60s healthy. Stops after max_restarts.

If health_check is set, taskmux runs it as a shell command (exit 0 = healthy). Falls back to checking if the pane has a running process. Must fail health_retries consecutive times before triggering restart.

Used by:

• taskmux health — status table
• taskmux start — dependency gating
• start --monitor / daemon — auto-restart trigger

Task output is piped to ~/.taskmux/logs/{session}/{task}.log with UTC timestamps:

2024-01-01T14:00:00.123 Server started on port 3000
2024-01-01T14:00:01.456 GET /health 200 2ms

Logs survive session kill. Rotated at log_max_size (default 10MB), keeping log_max_files (default 3). Filter with --since:

taskmux logs server --since 5m
taskmux logs --since 1h

Lifecycle events at ~/.taskmux/events.jsonl:

Auto-trims to 10K lines at 15K.

Fire order: global before_start → task before_start → run → task after_start → global after_start. Same for stop. before_* failure aborts the action.

[hooks]
before_start = "echo starting"

[tasks.api.hooks]
before_start = "python manage.py migrate"
after_stop = "echo api stopped"

taskmux daemon --port 8765

Health monitoring every 30s, auto-restart per policy, config file watching. WebSocket API:

ws.send(JSON.stringify({ command: "status" }));
ws.send(JSON.stringify({ command: "restart", params: { task: "server" } }));
ws.send(JSON.stringify({ command: "logs", params: { task: "server", lines: 50 } }));

Taskmux creates standard tmux sessions:

tmux attach-session -t myproject   # attach to see live output
# Ctrl+b 1/2/3 switch windows, Ctrl+b d detach

• PyPI
• GitHub

MIT