agent-cli 0.87.0__tar.gz → 0.88.0__tar.gz

{agent_cli-0.87.0/agent_cli/dev/skill → agent_cli-0.88.0/.claude/skills/agent-cli-dev}/SKILL.md

@@ -9,7 +9,7 @@ This skill teaches you how to spawn parallel AI coding agents in isolated git wo
 
 `agent-cli dev` supports two complementary patterns:
 - Separate worktrees for isolated implementation/review tasks
-- Multiple agents on the same worktree using `dev agent -m tmux`
+- Multiple agents on the same worktree using `dev agent --tmux-session <unique-name>` for autonomous launches, or `-m tmux` when a human explicitly wants shared tmux windows
 
 ## Installation
 
@@ -136,17 +136,26 @@ Use this when several agents should inspect or validate the same code at once wi
 # Create the worktree once. This step only prepares the shared workspace.
 agent-cli dev new review-auth --from HEAD
 
-# Then launch the actual agents with prompts.
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
+# Then launch the actual agents with prompts. Give each agent its own tmux session.
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-security-20260402-1530 \
+  --prompt-file .claude/review-security.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-performance-20260402-1530 \
+  --prompt-file .claude/review-performance.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-tests-20260402-1530 \
+  --prompt-file .claude/review-tests.md
 ```
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
 - Use `dev agent --agent <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
-- Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
-- Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
+- For autonomous agents, prefer `--tmux-session <unique-name>` and use a different session name for each launch
+- Reserve bare `-m tmux` for human-driven grouped windows or when the user explicitly wants agents to share one tmux session
+- Outside tmux, bare `-m tmux` joins the deterministic repo-scoped tmux session
+- Inside tmux, bare `-m tmux` opens a new window in the current session unless you pass `--tmux-session <name>`, which reuses or creates a specific tmux session and also implies `-m tmux`
+- tmux session names cannot contain `.` or `:`
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
 - If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
 - Each agent launch gets its own unique task file in `.claude/` (e.g., `TASK-{timestamp}-{hex}.md`), so parallel launches do not overwrite each other
@@ -168,14 +177,21 @@ When complete, write findings to .claude/REPORT-security-20260319-153045-123.md
 
 ## Headless/scripted orchestration
 
-For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
+For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `--tmux-session`:
 
 ```bash
-agent-cli dev new validation-a --from HEAD --agent codex -m tmux \
+agent-cli dev new validation-a --from HEAD --agent codex \
+  --tmux-session validation-a-20260402-1530 \
   --prompt-file .claude/validation-a.md
 ```
 
-This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+This works without an attached terminal. For autonomous or scripted launches, prefer a unique `--tmux-session` per agent so separate runs do not trample each other by sharing one tmux session. Use bare `-m tmux` only when you explicitly want shared tmux grouping. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+
+## Cleanup behavior
+
+- `dev rm` and `dev clean` also clean up tmux windows that `agent-cli` tagged for the worktree
+- If git worktree removal succeeds but tmux cleanup is partial, the command warns and still removes the worktree
+- Session isolation prevents agents from interfering with each other's tmux windows during execution, but cleanup still applies to all tagged windows for the worktree
 
 ## Example: Multi-feature implementation
 
@@ -200,5 +216,6 @@ Each agent works independently in its own branch. Results can be reviewed and me
 | `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** |
 | `--agent` | Specific agent (or `auto`): claude, aider, codex, gemini |
 | `--agent-args` | Extra arguments for the agent |
+| `--tmux-session` | Reuse or create a specific tmux session. For autonomous agents, prefer a unique name per launch |
 
 @examples.md

{agent_cli-0.87.0/.claude → agent_cli-0.88.0/.claude-plugin}/skills/agent-cli-dev/SKILL.md

@@ -9,7 +9,7 @@ This skill teaches you how to spawn parallel AI coding agents in isolated git wo
 
 `agent-cli dev` supports two complementary patterns:
 - Separate worktrees for isolated implementation/review tasks
-- Multiple agents on the same worktree using `dev agent -m tmux`
+- Multiple agents on the same worktree using `dev agent --tmux-session <unique-name>` for autonomous launches, or `-m tmux` when a human explicitly wants shared tmux windows
 
 ## Installation
 
@@ -136,17 +136,26 @@ Use this when several agents should inspect or validate the same code at once wi
 # Create the worktree once. This step only prepares the shared workspace.
 agent-cli dev new review-auth --from HEAD
 
-# Then launch the actual agents with prompts.
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
+# Then launch the actual agents with prompts. Give each agent its own tmux session.
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-security-20260402-1530 \
+  --prompt-file .claude/review-security.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-performance-20260402-1530 \
+  --prompt-file .claude/review-performance.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-tests-20260402-1530 \
+  --prompt-file .claude/review-tests.md
 ```
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
 - Use `dev agent --agent <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
-- Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
-- Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
+- For autonomous agents, prefer `--tmux-session <unique-name>` and use a different session name for each launch
+- Reserve bare `-m tmux` for human-driven grouped windows or when the user explicitly wants agents to share one tmux session
+- Outside tmux, bare `-m tmux` joins the deterministic repo-scoped tmux session
+- Inside tmux, bare `-m tmux` opens a new window in the current session unless you pass `--tmux-session <name>`, which reuses or creates a specific tmux session and also implies `-m tmux`
+- tmux session names cannot contain `.` or `:`
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
 - If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
 - Each agent launch gets its own unique task file in `.claude/` (e.g., `TASK-{timestamp}-{hex}.md`), so parallel launches do not overwrite each other
@@ -168,14 +177,21 @@ When complete, write findings to .claude/REPORT-security-20260319-153045-123.md
 
 ## Headless/scripted orchestration
 
-For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
+For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `--tmux-session`:
 
 ```bash
-agent-cli dev new validation-a --from HEAD --agent codex -m tmux \
+agent-cli dev new validation-a --from HEAD --agent codex \
+  --tmux-session validation-a-20260402-1530 \
   --prompt-file .claude/validation-a.md
 ```
 
-This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+This works without an attached terminal. For autonomous or scripted launches, prefer a unique `--tmux-session` per agent so separate runs do not trample each other by sharing one tmux session. Use bare `-m tmux` only when you explicitly want shared tmux grouping. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+
+## Cleanup behavior
+
+- `dev rm` and `dev clean` also clean up tmux windows that `agent-cli` tagged for the worktree
+- If git worktree removal succeeds but tmux cleanup is partial, the command warns and still removes the worktree
+- Session isolation prevents agents from interfering with each other's tmux windows during execution, but cleanup still applies to all tagged windows for the worktree
 
 ## Example: Multi-feature implementation
 
@@ -200,5 +216,6 @@ Each agent works independently in its own branch. Results can be reviewed and me
 | `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** |
 | `--agent` | Specific agent (or `auto`): claude, aider, codex, gemini |
 | `--agent-args` | Extra arguments for the agent |
+| `--tmux-session` | Reuse or create a specific tmux session. For autonomous agents, prefer a unique name per launch |
 
 @examples.md

{agent_cli-0.87.0 → agent_cli-0.88.0}/.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.7"
+    rev: "v0.15.8"
     hooks:
       - id: ruff
         args: ["--fix"]

agent_cli-0.88.0/LLAMA_SERVER_USAGE.md

@@ -0,0 +1,90 @@
+# Using agent-cli with llama-server (llama-cpp)
+
+This guide explains how to use agent-cli with llama-server, which provides an OpenAI-compatible API for running local LLM models.
+
+## Prerequisites
+
+1. Install and set up llama-cpp with llama-server support
+2. Download a compatible GGUF model file
+
+## Starting llama-server
+
+Start the llama-server with your model:
+
+```bash
+# Example with a 3B parameter model
+llama-server \
+  -m /path/to/your/model.gguf \
+  -c 2048 \
+  --host 0.0.0.0 \
+  --port 8080
+```
+
+## Configuration
+
+### Option 1: Using Configuration File
+
+Add to your `~/.config/agent-cli/config.toml` or `./agent-cli-config.toml`:
+
+```toml
+[defaults]
+llm-provider = "openai"
+llm-openai-model = "your-model-name"  # Can be anything, llama-server ignores this
+openai-base-url = "http://localhost:8080/v1"
+# openai-api-key is not required for llama-server
+```
+
+### Option 2: Using Command Line
+
+```bash
+# Example: Autocorrect text
+agent-cli autocorrect \
+  --llm-provider openai \
+  --llm-openai-model llama-3.2-3b \
+  --openai-base-url http://localhost:8080/v1
+
+# Example: Transcribe and process audio
+agent-cli transcribe \
+  --llm-provider openai \
+  --llm-openai-model llama-3.2-3b \
+  --openai-base-url http://localhost:8080/v1 \
+  --llm
+
+# Example: Chat assistant
+agent-cli chat \
+  --llm-provider openai \
+  --llm-openai-model llama-3.2-3b \
+  --openai-base-url http://localhost:8080/v1
+```
+
+## Notes
+
+- The `--llm-openai-model` parameter is sent to llama-server but typically ignored (the model is already loaded)
+- No API key is required when using llama-server
+- Make sure the base URL includes the `/v1` suffix for OpenAI API compatibility
+- Performance depends on your hardware and the model size
+
+## Advantages
+
+- Complete privacy - all processing happens locally
+- No API costs
+- No internet connection required (after model download)
+- Full control over the model and parameters
+- Can use any GGUF-compatible model
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Verify llama-server is running: `curl http://localhost:8080/v1/models`
+2. Check the llama-server logs for errors
+3. Ensure the base URL includes `/v1` at the end
+4. Try a simple curl test:
+   ```bash
+   curl http://localhost:8080/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{
+       "model": "test",
+       "messages": [{"role": "user", "content": "Hello"}]
+     }'
+   ```

{agent_cli-0.87.0 → agent_cli-0.88.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.87.0
+Version: 0.88.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>

{agent_cli-0.87.0 → agent_cli-0.88.0}/agent_cli/dev/cleanup.py

@@ -4,14 +4,26 @@ from __future__ import annotations
 
 import json
 import subprocess
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from . import worktree
+from .terminals.tmux import Tmux
 
 if TYPE_CHECKING:
     from pathlib import Path
 
 
+@dataclass
+class RemoveWorktreeResult:
+    """Outcome of removing a worktree and any tagged tmux windows."""
+
+    name: str
+    success: bool
+    error: str | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
 def find_worktrees_with_no_commits(repo_root: Path) -> list[worktree.WorktreeInfo]:
     """Find worktrees whose branches have no commits ahead of the default branch."""
     worktrees_list = worktree.list_worktrees()
@@ -95,18 +107,45 @@ def remove_worktrees(
     repo_root: Path,
     *,
     force: bool = False,
-) -> list[tuple[str, bool, str | None]]:
+) -> list[RemoveWorktreeResult]:
     """Remove a list of worktrees.
 
-    Returns list of (branch_name, success, error_message) tuples.
+    Returns a result for each worktree removal attempt.
     """
-    results: list[tuple[str, bool, str | None]] = []
-    for wt in worktrees_to_remove:
-        success, error = worktree.remove_worktree(
-            wt.path,
+    return [
+        remove_worktree(
+            wt,
+            repo_root,
             force=force,
             delete_branch=True,
-            repo_path=repo_root,
         )
-        results.append((wt.branch or wt.path.name, success, error))
-    return results
+        for wt in worktrees_to_remove
+    ]
+
+
+def remove_worktree(
+    wt: worktree.WorktreeInfo,
+    repo_root: Path,
+    *,
+    force: bool = False,
+    delete_branch: bool = False,
+) -> RemoveWorktreeResult:
+    """Remove one worktree and then clean up any tagged tmux windows."""
+    removed, error = worktree.remove_worktree(
+        wt.path,
+        force=force,
+        delete_branch=delete_branch,
+        repo_path=repo_root,
+    )
+    result = RemoveWorktreeResult(
+        name=wt.branch or wt.path.name,
+        success=removed,
+        error=error,
+    )
+    if not removed:
+        return result
+
+    tmux = Tmux()
+    tmux_cleanup = tmux.kill_windows_for_worktree(wt.path)
+    result.warnings.extend(tmux_cleanup.errors)
+    return result

{agent_cli-0.87.0 → agent_cli-0.88.0}/agent_cli/dev/cli.py

@@ -157,6 +157,23 @@ def _resolve_prompt_text(
     return prompt
 
 
+def _normalize_tmux_session(
+    tmux_session: str | None,
+    multiplexer: Literal["tmux"] | None,
+) -> tuple[str | None, Literal["tmux"] | None]:
+    """Normalize `--tmux-session` and make it imply tmux launches."""
+    if tmux_session is None:
+        return None, multiplexer
+
+    normalized_session = tmux_session.strip()
+    if not normalized_session:
+        error("--tmux-session cannot be empty")
+    if "." in normalized_session or ":" in normalized_session:
+        error("tmux session names cannot contain '.' or ':'")
+
+    return normalized_session, "tmux"
+
+
 def _resolve_dev_new_agent_request(
     *,
     start_agent: bool,
@@ -440,6 +457,13 @@ def new(
             help="Launch the agent in a specific multiplexer. Currently supported: tmux. When started outside tmux, creates or reuses a detached session and reports the pane handle",
         ),
     ] = None,
+    tmux_session: Annotated[
+        str | None,
+        typer.Option(
+            "--tmux-session",
+            help="Reuse or create a specific tmux session for the agent. Implies --multiplexer tmux",
+        ),
+    ] = None,
     hooks: Annotated[
         bool,
         typer.Option(
@@ -489,6 +513,7 @@ def new(
         agent_name_deprecated=agent_name_deprecated,
         prompt=prompt,
     )
+    tmux_session, multiplexer = _normalize_tmux_session(tmux_session, multiplexer)
 
     repo_root = _ensure_git_repo()
 
@@ -571,6 +596,7 @@ def new(
             task_file,
             agent_env,
             multiplexer_name=multiplexer,
+            tmux_session=tmux_session,
         )
 
     # Print summary
@@ -873,17 +899,19 @@ def remove(
         if not typer.confirm("Continue?"):
             raise typer.Abort
 
-    removed, remove_err = worktree.remove_worktree(
-        wt.path,
+    result = cleanup.remove_worktree(
+        wt,
+        repo_root,
         force=force,
         delete_branch=delete_branch,
-        repo_path=repo_root,
     )
 
-    if removed:
+    if result.success:
         success(f"Removed worktree: {wt.path}")
+        for cleanup_warning in result.warnings:
+            warn(cleanup_warning)
     else:
-        error(remove_err or "Failed to remove worktree")
+        error(result.error or "Failed to remove worktree")
 
 
 @app.command("path")
@@ -1018,6 +1046,13 @@ def start_agent(
             help="Launch the agent in a specific multiplexer instead of the current terminal. Currently supported: tmux",
         ),
     ] = None,
+    tmux_session: Annotated[
+        str | None,
+        typer.Option(
+            "--tmux-session",
+            help="Reuse or create a specific tmux session for the agent. Implies --multiplexer tmux",
+        ),
+    ] = None,
     hooks: Annotated[
         bool,
         typer.Option(
@@ -1043,6 +1078,7 @@ def start_agent(
         agent_name = agent_name or agent_name_deprecated
 
     prompt = _resolve_prompt_text(prompt, prompt_file=prompt_file)
+    tmux_session, multiplexer = _normalize_tmux_session(tmux_session, multiplexer)
 
     repo_root = _ensure_git_repo()
 
@@ -1090,6 +1126,7 @@ def start_agent(
             task_file,
             agent_env,
             multiplexer_name=multiplexer,
+            tmux_session=tmux_session,
         )
         if handle:
             info(
@@ -1367,11 +1404,13 @@ def _clean_merged_worktrees(
         info("[dry-run] Would remove the above worktrees")
     elif yes or typer.confirm("\nRemove these worktrees?"):
         results = cleanup.remove_worktrees([wt for wt, _ in to_remove], repo_root, force=force)
-        for branch, ok, remove_err in results:
-            if ok:
-                success(f"Removed {branch}")
+        for result in results:
+            if result.success:
+                success(f"Removed {result.name}")
+                for cleanup_warning in result.warnings:
+                    warn(cleanup_warning)
             else:
-                warn(f"Failed to remove {branch}: {remove_err}")
+                warn(f"Failed to remove {result.name}: {result.error}")
 
 
 def _clean_no_commits_worktrees(
@@ -1401,11 +1440,13 @@ def _clean_no_commits_worktrees(
         info("[dry-run] Would remove the above worktrees")
     elif yes or typer.confirm("\nRemove these worktrees?"):
         results = cleanup.remove_worktrees(to_remove, repo_root, force=force)
-        for branch, ok, remove_err in results:
-            if ok:
-                success(f"Removed {branch}")
+        for result in results:
+            if result.success:
+                success(f"Removed {result.name}")
+                for cleanup_warning in result.warnings:
+                    warn(cleanup_warning)
             else:
-                warn(f"Failed to remove {branch}: {remove_err}")
+                warn(f"Failed to remove {result.name}: {result.error}")
 
 
 @app.command("clean")

{agent_cli-0.87.0 → agent_cli-0.88.0}/agent_cli/dev/coding_agents/base.py

@@ -143,7 +143,7 @@ def _get_parent_process_names() -> list[str]:
     - CLI tools that set process.title (like Claude) show their name directly
     """
     try:
-        import psutil  # noqa: PLC0415
+        import psutil  # type: ignore[import-untyped]  # noqa: PLC0415
 
         process = psutil.Process(os.getpid())
         names = []

{agent_cli-0.87.0 → agent_cli-0.88.0}/agent_cli/dev/launch.py

@@ -280,6 +280,7 @@ def _launch_in_tmux(
     tab_name: str,
     repo_root: Path | None,
     multiplexer_name: str | None,
+    tmux_session: str | None,
 ) -> TerminalHandle | None:
     """Launch an agent via tmux and return its pane handle."""
     from .terminals.tmux import Tmux  # noqa: PLC0415
@@ -289,8 +290,8 @@ def _launch_in_tmux(
         return None
 
     requested_tmux = multiplexer_name == "tmux"
-    session_name = None
-    if requested_tmux and not terminal.detect():
+    session_name = tmux_session
+    if session_name is None and requested_tmux and not terminal.detect():
         session_name = terminal.session_name_for_repo(repo_root or path)
 
     handle = terminal.open_in_session(
@@ -305,7 +306,7 @@ def _launch_in_tmux(
 
     session_label = (
         f" in tmux session {handle.session_name}"
-        if requested_tmux and handle.session_name
+        if (requested_tmux or tmux_session is not None) and handle.session_name
         else " in new tmux tab"
     )
     success(f"Started {agent.name}{session_label}")
@@ -320,6 +321,7 @@ def _launch_in_terminal(
     tab_name: str,
     repo_root: Path | None,
     multiplexer_name: str | None,
+    tmux_session: str | None,
 ) -> tuple[bool, TerminalHandle | None]:
     """Launch an agent in the resolved terminal."""
     if terminal.name == "tmux":
@@ -331,6 +333,7 @@ def _launch_in_terminal(
             tab_name,
             repo_root,
             multiplexer_name,
+            tmux_session,
         )
         return handle is not None, handle
 
@@ -350,13 +353,15 @@ def launch_agent(
     task_file: Path | None = None,
     env: dict[str, str] | None = None,
     multiplexer_name: str | None = None,
+    tmux_session: str | None = None,
 ) -> TerminalHandle | None:
     """Launch agent in a new terminal tab.
 
     Agents are interactive TUIs that need a proper terminal.
     Priority: tmux/zellij tab > terminal tab > print instructions.
     """
-    terminal = _resolve_launch_terminal(multiplexer_name)
+    effective_multiplexer_name = "tmux" if tmux_session is not None else multiplexer_name
+    terminal = _resolve_launch_terminal(effective_multiplexer_name)
     full_cmd = _build_agent_launch_command(
         path, agent, extra_args, prompt, task_file, env, terminal
     )
@@ -370,7 +375,8 @@ def launch_agent(
             full_cmd,
             tab_name,
             repo_root,
-            multiplexer_name,
+            effective_multiplexer_name,
+            tmux_session,
         )
         if launched:
             return handle

{agent_cli-0.87.0/.claude-plugin/skills/agent-cli-dev → agent_cli-0.88.0/agent_cli/dev/skill}/SKILL.md

@@ -9,7 +9,7 @@ This skill teaches you how to spawn parallel AI coding agents in isolated git wo
 
 `agent-cli dev` supports two complementary patterns:
 - Separate worktrees for isolated implementation/review tasks
-- Multiple agents on the same worktree using `dev agent -m tmux`
+- Multiple agents on the same worktree using `dev agent --tmux-session <unique-name>` for autonomous launches, or `-m tmux` when a human explicitly wants shared tmux windows
 
 ## Installation
 
@@ -136,17 +136,26 @@ Use this when several agents should inspect or validate the same code at once wi
 # Create the worktree once. This step only prepares the shared workspace.
 agent-cli dev new review-auth --from HEAD
 
-# Then launch the actual agents with prompts.
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md
-agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
+# Then launch the actual agents with prompts. Give each agent its own tmux session.
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-security-20260402-1530 \
+  --prompt-file .claude/review-security.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-performance-20260402-1530 \
+  --prompt-file .claude/review-performance.md
+agent-cli dev agent review-auth \
+  --tmux-session review-auth-tests-20260402-1530 \
+  --prompt-file .claude/review-tests.md
 ```
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
 - Use `dev agent --agent <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
-- Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
-- Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
+- For autonomous agents, prefer `--tmux-session <unique-name>` and use a different session name for each launch
+- Reserve bare `-m tmux` for human-driven grouped windows or when the user explicitly wants agents to share one tmux session
+- Outside tmux, bare `-m tmux` joins the deterministic repo-scoped tmux session
+- Inside tmux, bare `-m tmux` opens a new window in the current session unless you pass `--tmux-session <name>`, which reuses or creates a specific tmux session and also implies `-m tmux`
+- tmux session names cannot contain `.` or `:`
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
 - If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
 - Each agent launch gets its own unique task file in `.claude/` (e.g., `TASK-{timestamp}-{hex}.md`), so parallel launches do not overwrite each other
@@ -168,14 +177,21 @@ When complete, write findings to .claude/REPORT-security-20260319-153045-123.md
 
 ## Headless/scripted orchestration
 
-For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
+For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `--tmux-session`:
 
 ```bash
-agent-cli dev new validation-a --from HEAD --agent codex -m tmux \
+agent-cli dev new validation-a --from HEAD --agent codex \
+  --tmux-session validation-a-20260402-1530 \
   --prompt-file .claude/validation-a.md
 ```
 
-This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+This works without an attached terminal. For autonomous or scripted launches, prefer a unique `--tmux-session` per agent so separate runs do not trample each other by sharing one tmux session. Use bare `-m tmux` only when you explicitly want shared tmux grouping. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
+
+## Cleanup behavior
+
+- `dev rm` and `dev clean` also clean up tmux windows that `agent-cli` tagged for the worktree
+- If git worktree removal succeeds but tmux cleanup is partial, the command warns and still removes the worktree
+- Session isolation prevents agents from interfering with each other's tmux windows during execution, but cleanup still applies to all tagged windows for the worktree
 
 ## Example: Multi-feature implementation
 
@@ -200,5 +216,6 @@ Each agent works independently in its own branch. Results can be reviewed and me
 | `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** |
 | `--agent` | Specific agent (or `auto`): claude, aider, codex, gemini |
 | `--agent-args` | Extra arguments for the agent |
+| `--tmux-session` | Reuse or create a specific tmux session. For autonomous agents, prefer a unique name per launch |
 
 @examples.md