taskmux 0.2.4__tar.gz → 0.2.5__tar.gz

{taskmux-0.2.4 → taskmux-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskmux
-Version: 0.2.4
+Version: 0.2.5
 Summary: Modern tmux-based task manager for LLM development tools
 Project-URL: Homepage, https://github.com/nc9/taskmux
 Project-URL: Repository, https://github.com/nc9/taskmux
@@ -104,6 +104,67 @@ command = "docker compose up postgres"
 auto_start = false
 ```
 
+## Full Example
+
+A full-stack app with a database, API server, and frontend — using health checks to ensure each service is ready before starting its dependents:
+
+```toml
+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"
+depends_on = ["migrate"]
+health_check = "curl -sf http://localhost:8000/health"
+
+[tasks.worker]
+command = "celery -A myapp worker -l info"
+cwd = "apps/api"
+depends_on = ["db"]
+
+[tasks.web]
+command = "bun dev"
+cwd = "apps/web"
+depends_on = ["api"]
+health_check = "curl -sf http://localhost:3000"
+
+[tasks.storybook]
+command = "bun storybook"
+cwd = "apps/web"
+auto_start = false
+```
+
+What happens on `taskmux start`:
+
+1. **db** starts first (no dependencies)
+2. **migrate** and **worker** wait for db's health check (`pg_isready`) to pass
+3. **api** waits for migrate's health check
+4. **web** waits for api's health check (`curl localhost:8000/health`)
+5. **storybook** is skipped (`auto_start = false`) — start it manually with `taskmux start storybook`
+
+```bash
+taskmux start                    # Starts everything in dependency order
+taskmux logs                     # Interleaved logs from all tasks
+taskmux logs -g "ERROR"          # Grep all tasks for errors
+taskmux logs api                 # Logs from just the API
+taskmux logs -f api              # Follow API logs live
+taskmux health                   # Health check table
+taskmux inspect api              # JSON state for a single task
+taskmux restart worker           # Restart just the worker
+taskmux start storybook          # Start a manual task
+```
+
 ## Commands
 
 ```bash
@@ -124,10 +185,13 @@ taskmux remove <task>            # Remove task from config
 taskmux inspect <task>           # JSON task state (pid, command, health)
 
 # Logs
-taskmux logs <task>              # Show recent logs
-taskmux logs -f <task>           # Follow logs live
-taskmux logs -n 100 <task>       # Last N lines
-taskmux logs <task> -g "error"   # Search logs with grep
+taskmux logs                     # Interleaved logs from all tasks
+taskmux logs <task>              # Show recent logs for a task
+taskmux logs -f                  # Attach to session (switch windows with tmux keybinds)
+taskmux logs -f <task>           # Follow a task's logs live
+taskmux logs -n 200 <task>       # Last N lines
+taskmux logs -g "error"          # Search all tasks
+taskmux logs <task> -g "error"   # Search one task
 taskmux logs <task> -g "error" -C 5  # Grep with context lines
 
 # Init
@@ -161,12 +225,20 @@ after_stop = "echo done"
 
 [tasks.server]
 command = "python manage.py runserver"
+cwd = "apps/api"
+health_check = "curl -sf http://localhost:8000/health"
+depends_on = ["db"]
 
 [tasks.server.hooks]
 before_start = "python manage.py migrate"
 
+[tasks.db]
+command = "docker compose up postgres"
+health_check = "pg_isready -h localhost"
+
 [tasks.worker]
 command = "celery worker -A myapp"
+depends_on = ["db"]
 
 [tasks.tailwind]
 command = "npx tailwindcss -w"
@@ -185,8 +257,31 @@ auto_start = false
 | `hooks.after_stop` | — | Run after stopping tasks |
 | `tasks.<name>.command` | — | Shell command to run |
 | `tasks.<name>.auto_start` | `true` | Start with `taskmux start` |
+| `tasks.<name>.cwd` | — | Working directory for the task |
+| `tasks.<name>.health_check` | — | Shell command to check health (exit 0 = healthy) |
+| `tasks.<name>.health_interval` | `10` | Seconds between health checks |
+| `tasks.<name>.health_timeout` | `5` | Seconds before health check times out |
+| `tasks.<name>.health_retries` | `3` | Consecutive failures before "unhealthy" |
+| `tasks.<name>.depends_on` | `[]` | Task names that must be healthy before this task starts |
 | `tasks.<name>.hooks.*` | — | Per-task lifecycle hooks (same fields as global) |
 
+### Dependency Ordering
+
+Tasks with `depends_on` are started in topological order. Before starting a task, taskmux waits for each dependency's health check to pass (up to `health_retries * health_interval` seconds). If a dependency never becomes healthy, the dependent task is skipped with a warning.
+
+Circular dependencies and references to nonexistent tasks are rejected at config load time.
+
+When starting a single task with `taskmux start <task>`, dependencies are not auto-started — you get a warning if they aren't running.
+
+### Health Checks
+
+If `health_check` is set, taskmux runs it as a shell command. Exit code 0 means healthy. If not set, taskmux falls back to checking if the tmux pane has a running process (not just a shell prompt).
+
+Health checks are used by:
+- `taskmux health` — shows a table of all task health
+- `taskmux start` — waits for dependencies to be healthy before starting dependents
+- `taskmux daemon` — continuously monitors and auto-restarts unhealthy tasks
+
 ### Hook Cascade
 
 Hooks fire in this order:
@@ -212,14 +307,17 @@ Use `--defaults` to skip prompts (CI/automation).
 
 ```json
 {
-  "name": "server",
-  "command": "npm run dev",
+  "name": "api",
+  "command": "python manage.py runserver 0.0.0.0:8000",
   "auto_start": true,
+  "cwd": "apps/api",
+  "health_check": "curl -sf http://localhost:8000/health",
+  "depends_on": ["db"],
   "running": true,
   "healthy": true,
   "pid": "12345",
-  "pane_current_command": "node",
-  "pane_current_path": "/home/user/project",
+  "pane_current_command": "python",
+  "pane_current_path": "/home/user/project/apps/api",
   "window_id": "@1",
   "pane_id": "%1"
 }

{taskmux-0.2.4 → taskmux-0.2.5}/README.md

@@ -69,6 +69,67 @@ command = "docker compose up postgres"
 auto_start = false
 ```
 
+## Full Example
+
+A full-stack app with a database, API server, and frontend — using health checks to ensure each service is ready before starting its dependents:
+
+```toml
+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"
+depends_on = ["migrate"]
+health_check = "curl -sf http://localhost:8000/health"
+
+[tasks.worker]
+command = "celery -A myapp worker -l info"
+cwd = "apps/api"
+depends_on = ["db"]
+
+[tasks.web]
+command = "bun dev"
+cwd = "apps/web"
+depends_on = ["api"]
+health_check = "curl -sf http://localhost:3000"
+
+[tasks.storybook]
+command = "bun storybook"
+cwd = "apps/web"
+auto_start = false
+```
+
+What happens on `taskmux start`:
+
+1. **db** starts first (no dependencies)
+2. **migrate** and **worker** wait for db's health check (`pg_isready`) to pass
+3. **api** waits for migrate's health check
+4. **web** waits for api's health check (`curl localhost:8000/health`)
+5. **storybook** is skipped (`auto_start = false`) — start it manually with `taskmux start storybook`
+
+```bash
+taskmux start                    # Starts everything in dependency order
+taskmux logs                     # Interleaved logs from all tasks
+taskmux logs -g "ERROR"          # Grep all tasks for errors
+taskmux logs api                 # Logs from just the API
+taskmux logs -f api              # Follow API logs live
+taskmux health                   # Health check table
+taskmux inspect api              # JSON state for a single task
+taskmux restart worker           # Restart just the worker
+taskmux start storybook          # Start a manual task
+```
+
 ## Commands
 
 ```bash
@@ -89,10 +150,13 @@ taskmux remove <task>            # Remove task from config
 taskmux inspect <task>           # JSON task state (pid, command, health)
 
 # Logs
-taskmux logs <task>              # Show recent logs
-taskmux logs -f <task>           # Follow logs live
-taskmux logs -n 100 <task>       # Last N lines
-taskmux logs <task> -g "error"   # Search logs with grep
+taskmux logs                     # Interleaved logs from all tasks
+taskmux logs <task>              # Show recent logs for a task
+taskmux logs -f                  # Attach to session (switch windows with tmux keybinds)
+taskmux logs -f <task>           # Follow a task's logs live
+taskmux logs -n 200 <task>       # Last N lines
+taskmux logs -g "error"          # Search all tasks
+taskmux logs <task> -g "error"   # Search one task
 taskmux logs <task> -g "error" -C 5  # Grep with context lines
 
 # Init
@@ -126,12 +190,20 @@ after_stop = "echo done"
 
 [tasks.server]
 command = "python manage.py runserver"
+cwd = "apps/api"
+health_check = "curl -sf http://localhost:8000/health"
+depends_on = ["db"]
 
 [tasks.server.hooks]
 before_start = "python manage.py migrate"
 
+[tasks.db]
+command = "docker compose up postgres"
+health_check = "pg_isready -h localhost"
+
 [tasks.worker]
 command = "celery worker -A myapp"
+depends_on = ["db"]
 
 [tasks.tailwind]
 command = "npx tailwindcss -w"
@@ -150,8 +222,31 @@ auto_start = false
 | `hooks.after_stop` | — | Run after stopping tasks |
 | `tasks.<name>.command` | — | Shell command to run |
 | `tasks.<name>.auto_start` | `true` | Start with `taskmux start` |
+| `tasks.<name>.cwd` | — | Working directory for the task |
+| `tasks.<name>.health_check` | — | Shell command to check health (exit 0 = healthy) |
+| `tasks.<name>.health_interval` | `10` | Seconds between health checks |
+| `tasks.<name>.health_timeout` | `5` | Seconds before health check times out |
+| `tasks.<name>.health_retries` | `3` | Consecutive failures before "unhealthy" |
+| `tasks.<name>.depends_on` | `[]` | Task names that must be healthy before this task starts |
 | `tasks.<name>.hooks.*` | — | Per-task lifecycle hooks (same fields as global) |
 
+### Dependency Ordering
+
+Tasks with `depends_on` are started in topological order. Before starting a task, taskmux waits for each dependency's health check to pass (up to `health_retries * health_interval` seconds). If a dependency never becomes healthy, the dependent task is skipped with a warning.
+
+Circular dependencies and references to nonexistent tasks are rejected at config load time.
+
+When starting a single task with `taskmux start <task>`, dependencies are not auto-started — you get a warning if they aren't running.
+
+### Health Checks
+
+If `health_check` is set, taskmux runs it as a shell command. Exit code 0 means healthy. If not set, taskmux falls back to checking if the tmux pane has a running process (not just a shell prompt).
+
+Health checks are used by:
+- `taskmux health` — shows a table of all task health
+- `taskmux start` — waits for dependencies to be healthy before starting dependents
+- `taskmux daemon` — continuously monitors and auto-restarts unhealthy tasks
+
 ### Hook Cascade
 
 Hooks fire in this order:
@@ -177,14 +272,17 @@ Use `--defaults` to skip prompts (CI/automation).
 
 ```json
 {
-  "name": "server",
-  "command": "npm run dev",
+  "name": "api",
+  "command": "python manage.py runserver 0.0.0.0:8000",
   "auto_start": true,
+  "cwd": "apps/api",
+  "health_check": "curl -sf http://localhost:8000/health",
+  "depends_on": ["db"],
   "running": true,
   "healthy": true,
   "pid": "12345",
-  "pane_current_command": "node",
-  "pane_current_path": "/home/user/project",
+  "pane_current_command": "python",
+  "pane_current_path": "/home/user/project/apps/api",
   "window_id": "@1",
   "pane_id": "%1"
 }

{taskmux-0.2.4 → taskmux-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskmux"
-version = "0.2.4"
+version = "0.2.5"
 description = "Modern tmux-based task manager for LLM development tools"
 readme = "README.md"
 license-file = "LICENSE"

{taskmux-0.2.4 → taskmux-0.2.5}/taskmux/tmux_manager.py

@@ -8,10 +8,27 @@ from collections import deque
 from datetime import datetime
 
 import libtmux
+from rich.console import Console
+from rich.markup import escape
 
 from .hooks import runHook
 from .models import TaskmuxConfig
 
+TASK_COLORS = ["cyan", "green", "yellow", "magenta", "blue", "red"]
+
+
+def _find_new_lines(current: list[str], prev_tail: list[str]) -> list[str]:
+    """Return lines in current that are new since prev_tail."""
+    if not prev_tail:
+        return current
+    target = prev_tail[-1]
+    for i in range(len(current) - 1, -1, -1):
+        if current[i] == target:
+            ctx = min(len(prev_tail), i + 1)
+            if current[i - ctx + 1 : i + 1] == prev_tail[-ctx:]:
+                return current[i + 1 :]
+    return current  # no match, prev scrolled away — return all
+
 
 class TmuxManager:
     """Manages tmux sessions and tasks using libtmux API."""
@@ -433,6 +450,54 @@ class TmuxManager:
         info["healthy"] = self.is_task_healthy(task_name)
         return info
 
+    def _tail_panes(
+        self,
+        panes: list[tuple[str, libtmux.Pane, str]],
+        lines: int = 100,
+        grep: str | None = None,
+    ) -> None:
+        """Poll capture-pane and print new lines with colored task prefixes."""
+        console = Console()
+        state: dict[str, list[str]] = {}
+
+        try:
+            while True:
+                for task_name, pane, color in panes:
+                    output = pane.cmd("capture-pane", "-p", "-S", f"-{lines}").stdout
+                    while output and not output[-1].strip():
+                        output.pop()
+
+                    prev = state.get(task_name, [])
+                    new = _find_new_lines(output, prev)
+
+                    if grep:
+                        new = [ln for ln in new if grep.lower() in ln.lower()]
+
+                    for line in new:
+                        prefix = escape(f"[{task_name}]")
+                        console.print(f"[{color}]{prefix}[/{color}] {escape(line)}")
+
+                    if output:
+                        state[task_name] = output[-50:]
+
+                time.sleep(0.5)
+        except KeyboardInterrupt:
+            console.print("\n[dim]Stopped following logs[/dim]")
+
+    def _collect_panes(self, task_names: list[str]) -> list[tuple[str, libtmux.Pane, str]]:
+        """Collect (name, pane, color) tuples for running tasks."""
+        sess = self._get_session()
+        result: list[tuple[str, libtmux.Pane, str]] = []
+        for i, name in enumerate(task_names):
+            window = sess.windows.get(window_name=name, default=None)
+            if not window:
+                continue
+            pane = window.active_pane
+            if pane:
+                color = TASK_COLORS[i % len(TASK_COLORS)]
+                result.append((name, pane, color))
+        return result
+
     def show_logs(
         self,
         task_name: str | None,
@@ -461,8 +526,9 @@ class TmuxManager:
             return
 
         if follow:
-            window.select_window()
-            sess.attach()
+            panes = self._collect_panes([task_name])
+            if panes:
+                self._tail_panes(panes, lines=lines, grep=grep)
         else:
             pane = window.active_pane
             if pane:
@@ -482,26 +548,33 @@ class TmuxManager:
     ) -> None:
         """Show logs from all running tasks."""
         sess = self._get_session()
+        console = Console()
+        task_names = list(self.config.tasks.keys())
 
         if follow:
-            sess.attach()
+            panes = self._collect_panes(task_names)
+            if panes:
+                self._tail_panes(panes, lines=lines, grep=grep)
             return
 
-        for task_name in self.config.tasks:
+        for i, task_name in enumerate(task_names):
             window = sess.windows.get(window_name=task_name, default=None)
             if not window:
                 continue
             pane = window.active_pane
             if not pane:
                 continue
+            color = TASK_COLORS[i % len(TASK_COLORS)]
             output = pane.cmd("capture-pane", "-p", "-S", f"-{lines}").stdout
             if grep:
                 matching = [line for line in output if grep.lower() in line.lower()]
                 for line in matching:
-                    print(f"[{task_name}] {line}")
+                    prefix = escape(f"[{task_name}]")
+                    console.print(f"[{color}]{prefix}[/{color}] {escape(line)}")
             else:
                 for line in output:
-                    print(f"[{task_name}] {line}")
+                    prefix = escape(f"[{task_name}]")
+                    console.print(f"[{color}]{prefix}[/{color}] {escape(line)}")
 
     def list_tasks(self) -> None:
         """List all tasks and their status"""