taskmux 0.4.0

Modern tmux-based task manager for LLM development tools

Taskmux

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.

Features

• 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

Install

Requires tmux and Python 3.11+.

uv tool install taskmux

Commands

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 vs kill vs restart

Command	Signal	Window	Auto-restart
stop	C-c → SIGTERM → SIGKILL	Stays alive	Blocked
kill	SIGKILL	Destroyed	Blocked
restart	Full stop + restart	Reused	Re-enabled

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

Configuration

Config file: taskmux.toml in the current directory.

Minimal

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

Full-stack example

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).

Fields

Field	Default	Description
name	"taskmux"	tmux session name
auto_start	true	global toggle — false creates session but launches nothing
hooks.*	—	before_start, after_start, before_stop, after_stop
Task fields
command	required	shell command to run
auto_start	true	include in taskmux start
cwd	—	working directory
port	—	port to clean up before starting
health_check	—	shell command (exit 0 = healthy)
health_interval	10	seconds between checks
health_timeout	5	seconds before check times out
health_retries	3	consecutive failures before restart
stop_grace_period	5	seconds after C-c before SIGTERM
restart_policy	"on-failure"	"no", "on-failure", "always"
max_restarts	5	max restarts before giving up (resets after 60s healthy)
restart_backoff	2.0	exponential backoff base (capped 60s)
log_file	—	override log path (default: ~/.taskmux/logs/{session}/{task}.log)
log_max_size	"10MB"	max size before rotation
log_max_files	3	rotated files to keep
depends_on	[]	tasks that must be healthy first
hooks.*	—	per-task lifecycle hooks

JSON Output

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"}

Restart Policies

Enforced by start --monitor and daemon.

Policy	Behavior
"no"	Never auto-restart
"on-failure"	(default) Restart on crash or after health_retries consecutive failures
"always"	Restart on any exit (including clean)

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.

Health Checks

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

Persistent Logs

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

Event History

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

Event	Trigger
task_started / task_stopped / task_restarted / task_killed	CLI commands
session_started / session_stopped	start/stop all
health_check_failed	health check fails (includes attempt count)
auto_restart	restart triggered (includes reason)
max_restarts_reached	hit limit
config_reloaded	config file changed

Auto-trims to 10K lines at 15K.

Hooks

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"

Daemon & WebSocket API

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 } }));

Tmux

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

Links

• PyPI
• GitHub

License

MIT