Adding tmux support.

Author: joaopauloschuler

README.md

@@ -27,6 +27,7 @@ limitations under the License.
 * 🔌 **MCP server integration:** Connect any [Model Context Protocol](https://modelcontextprotocol.io) server as a tool source via the `--mcp` CLI flag. Supports both HTTP (Streamable HTTP) and stdio-based servers.
 * 👁️ **Image loading:** Agents can load and visually inspect image files (plots, screenshots, diagrams) via the built-in `load_image` tool — always available, no flags needed.
 * 🎨 **Image tools:** Visual image diffing (`diff_images`), OCR text extraction from images (`screen_ocr`), and a canvas for drawing shapes, text, and annotations (`canvas_create`, `canvas_draw`) — always available.
+* 🖵 **Tmux multi-screen:** Agents can create and operate multiple independent shell sessions concurrently via tmux (`--tmux` flag or `BPSA_TMUX=1`). Run builds, servers, and tests in parallel across named screen sessions.
 * 🎤 **Dictation input:** Dictate prompts via microphone using Whisper or ElevenLabs transcription (`/dictation` command, requires `BPSA_DICTATION_TRANSCRIBER` env var).
 * ⚡ **Native Python execution:** Execute Python code natively via `exec` for unrestricted processing.
 * 🌍 **Multi-language support:** Code in multiple languages beyond Python (Pascal, PHP, C++, Java and more).
@@ -94,6 +95,7 @@ $ bpsa --load-instructions          # Load CLAUDE.md, AGENTS.md, etc. at startup
 $ bpsa --browser                    # Enable Playwright browser integration
 $ bpsa --gui-x11                     # Enable native GUI interaction (xdotool/ImageMagick)
 $ bpsa --image                       # Enable image analysis and drawing tools
+$ bpsa --tmux                        # Enable tmux multi-screen tools
 $ bpsa --mcp http://localhost:8000/mcp  # Connect an HTTP MCP server
 $ bpsa --mcp 'npx -y @modelcontextprotocol/server-filesystem /'  # Connect a stdio MCP server
 ```

docs/CLI.md

@@ -73,6 +73,7 @@ These variables enable optional tool sets. Each corresponds to a CLI flag. Setti
 | `BPSA_BROWSER` | `--browser` | Enable Playwright browser integration (navigate, click, type, etc.) |
 | `BPSA_GUI` | `--gui-x11` | Enable native GUI interaction tools (screenshot, click, type via xdotool/ImageMagick on X11) |
 | `BPSA_IMAGE` | `--image` | Enable image analysis and drawing tools (diff_images, screen_ocr, canvas drawing) |
+| `BPSA_TMUX` | `--tmux` | Enable tmux multi-screen tools (create, send, read, list, destroy, wait) |
 
 ### Context Compression Variables
 
@@ -199,6 +200,51 @@ Use `prompt_toolkit` for:
 | `/verbose` | Toggle verbose output |
 | `/dictation [on\|off]` | Toggle dictation (requires `BPSA_DICTATION_TRANSCRIBER`) |
 
+## Tmux Multi-Screen Tools
+
+The `--tmux` flag (or `BPSA_TMUX=1` env var) enables tools that let the agent create and operate multiple independent shell sessions concurrently via tmux. This is useful for running long-running processes (servers, builds, file watchers) in parallel while the agent continues other work.
+
+**Requires:** `tmux` installed on the system.
+
+```bash
+bpsa --tmux
+
+# Or via environment variable:
+export BPSA_TMUX=1
+bpsa
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `tmux_create(session_name, command?)` | Create a new named screen session (default command: `bash`) |
+| `tmux_send(session_name, text, press_enter?)` | Send keystrokes to a session (default: presses Enter after text) |
+| `tmux_read(session_name, lines?)` | Read the current screen content / scrollback (default: 100 lines, max: 2000) |
+| `tmux_list()` | List all active agent screen sessions |
+| `tmux_destroy(session_name)` | Kill a session and all its processes |
+| `tmux_wait(session_name, pattern, timeout?, interval?)` | Poll until a text pattern appears (default: 60s timeout, 1s interval) |
+
+### Example Agent Workflow
+
+```
+tmux_create("server")
+tmux_send("server", "python app.py")
+tmux_wait("server", "Listening on port 8080")
+
+tmux_create("tests")
+tmux_send("tests", "pytest tests/ -v")
+tmux_wait("tests", "passed")
+tmux_read("tests")
+
+tmux_destroy("server")
+tmux_destroy("tests")
+```
+
+### Session Namespacing
+
+All sessions are automatically prefixed with `bpsa_` internally to avoid collisions with user tmux sessions. The agent uses short names (e.g., `server`) while tmux sees `bpsa_server`. Sessions are automatically cleaned up when the process exits.
+
 ## MCP Server Integration
 
 The `--mcp` flag connects [Model Context Protocol](https://modelcontextprotocol.io) servers as additional tool sources. Tools exposed by MCP servers are automatically available to the agent alongside the built-in tools.
@@ -482,3 +528,4 @@ bppas lib/ --strip-comments -o interfaces.txt
 - `prompt_toolkit` - REPL input handling (optional, falls back to basic `input()`)
 - `rich` - Output formatting (already a project dependency)
 - `argparse` - CLI argument parsing (stdlib)
+- `tmux` - Multi-screen session management (optional, required for `--tmux`)

src/smolagents/bp_cli.py

@@ -37,6 +37,9 @@
     BPSA_COMPRESSION_PRESERVE_FINAL_ANSWER_STEPS - Keep final_answer steps (default: 1)
     BPSA_COMPRESSION_MIN_CHARS                - Min chars before compressing (default: 4096)
 
+    Tmux multi-screen tools (requires tmux installed):
+    BPSA_TMUX                  - Enable tmux multi-screen tools (0 or 1, default: 0)
+
     Dictation input (requires `pip install bpsa[dictation]`):
     BPSA_DICTATION_TRANSCRIBER - Transcriber name: 'whisper' or 'elevenlabs' (required for /dictation)
     BPSA_DICTATION_MODEL       - Model name passed to transcriber (optional, whisper only)
@@ -337,7 +340,7 @@ def build_model(override_model_id=None):
     return model
 
 
-def build_agent(model, approval_callback=None, browser_enabled=False, gui_enabled=False, image_enabled=False, mcp_servers=None):
+def build_agent(model, approval_callback=None, browser_enabled=False, gui_enabled=False, image_enabled=False, tmux_enabled=False, mcp_servers=None):
     from smolagents import CodeAgent
     from smolagents.bp_thinkers import (
         DEFAULT_THINKER_COMPRESSION, DEFAULT_THINKER_MAX_STEPS,
@@ -371,6 +374,10 @@ def build_agent(model, approval_callback=None, browser_enabled=False, gui_enable
         gui_manager, gui_tools = create_gui_tools()
         tools.extend(gui_tools)
 
+    if tmux_enabled:
+        from smolagents.bp_tools_tmux import create_tmux_tools
+        tools.extend(create_tmux_tools())
+
     copilot_model_id = get_env("BPSA_COPILOT_MODEL_ID", default=None)
     if copilot_model_id:
         from smolagents.bp_tools import GitHubCopilotCoder
@@ -1675,7 +1682,7 @@ def cmd_undo(agent, args: str):
         console.print(f"[yellow]Only {actual} of {n} requested steps were removable (protected system prompt steps).[/]")
 
 
-def cmd_repeat(agent, model, n, prompt_text, session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=False, image_enabled=False):
+def cmd_repeat(agent, model, n, prompt_text, session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=False, image_enabled=False, tmux_enabled=False):
     """Run a prompt N times, each on a fresh agent with snapshotted context."""
     from smolagents.bp_session import load_session_from_dict, save_session_to_dict
     from smolagents.monitoring import LogLevel
@@ -1707,7 +1714,7 @@ def cmd_repeat(agent, model, n, prompt_text, session_stats, verbose, instruction
             os.chdir(original_folder)
 
             # Create fresh agent and restore snapshot
-            cycle_agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled)
+            cycle_agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled)
             load_session_from_dict(snapshot, cycle_agent)
 
             # Prepare prompt (prepend instructions on first_turn only)
@@ -1804,13 +1811,13 @@ def prepend_instructions(task: str, instructions: str | None) -> str:
     return task
 
 
-def run_one_shot(task: str, skip_instructions: bool = False, auto_approve: bool = True, browser_enabled: bool = False, gui_enabled: bool = False, image_enabled: bool = False, mcp_servers=None):
+def run_one_shot(task: str, skip_instructions: bool = False, auto_approve: bool = True, browser_enabled: bool = False, gui_enabled: bool = False, image_enabled: bool = False, tmux_enabled: bool = False, mcp_servers=None):
     global _auto_approve
     _auto_approve = auto_approve
     try_load_dotenv()
     check_required_env()
     model = build_model()
-    agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+    agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
     instructions = None
     if not skip_instructions:
         console.print("[dim]Loading agent instructions...[/]")
@@ -1835,14 +1842,14 @@ def run_one_shot(task: str, skip_instructions: bool = False, auto_approve: bool
         _shutdown_mcp(agent)
 
 
-def run_repl(skip_instructions: bool = False, auto_approve: bool = True, browser_enabled: bool = False, gui_enabled: bool = False, image_enabled: bool = False, mcp_servers=None):
+def run_repl(skip_instructions: bool = False, auto_approve: bool = True, browser_enabled: bool = False, gui_enabled: bool = False, image_enabled: bool = False, tmux_enabled: bool = False, mcp_servers=None):
     global _auto_approve
     _auto_approve = auto_approve
     try_load_dotenv()
     check_required_env()
 
     model = build_model()
-    agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+    agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
     model_id = get_env("BPSA_MODEL_ID")
     server_model = get_env("BPSA_SERVER_MODEL", default="OpenAIServerModel")
     tool_count = count_tools(agent)
@@ -2063,7 +2070,7 @@ def get_input():
                 _shutdown_browser(agent)
                 _shutdown_gui(agent)
                 _shutdown_mcp(agent)
-                agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+                agent = build_agent(model, approval_callback=interactive_approval_callback, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
                 session_stats = {
                     "turns": 0,
                     "total_time": 0.0,
@@ -2206,7 +2213,7 @@ def get_input():
                 except ValueError:
                     console.print("[red]N must be a positive integer. Usage: /repeat <N> <prompt>[/]")
                     continue
-                cmd_repeat(agent, model, repeat_n, parts[1], session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled)
+                cmd_repeat(agent, model, repeat_n, parts[1], session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled)
                 continue
             elif cmd == "/repeat-prompt":
                 parts = cmd_args.strip().split(None, 1)
@@ -2223,7 +2230,7 @@ def get_input():
                 file_content = load_file_as_prompt(parts[1])
                 if file_content is None:
                     continue
-                cmd_repeat(agent, model, repeat_n, file_content, session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled)
+                cmd_repeat(agent, model, repeat_n, file_content, session_stats, verbose, instructions, first_turn, browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled)
                 continue
             elif cmd == "/session-save":
                 cmd_session_save(agent, session_stats, cmd_args)
@@ -2380,6 +2387,10 @@ def main():
         "--image", action="store_true",
         help="Enable image analysis and drawing tools (diff_images, screen_ocr, canvas drawing)",
     )
+    parser.add_argument(
+        "--tmux", action="store_true",
+        help="Enable tmux multi-screen tools (create, send, read, list, destroy, wait)",
+    )
     parser.add_argument(
         "--mcp", action="append", metavar="URL_OR_CMD", dest="mcp",
         help="Connect an MCP server. Use a URL for HTTP servers or a shell command for stdio servers. Can be repeated for multiple servers.",
@@ -2396,6 +2407,7 @@ def main():
     browser_enabled = args.browser or get_env_bool("BPSA_BROWSER")
     gui_enabled = args.gui_x11 or get_env_bool("BPSA_GUI")
     image_enabled = args.image or get_env_bool("BPSA_IMAGE")
+    tmux_enabled = args.tmux or get_env_bool("BPSA_TMUX")
     env_mcp = get_env("BPSA_MCP", "")
     env_mcp_list = [s.strip() for s in env_mcp.splitlines() if s.strip()]
     mcp_servers = _parse_mcp_servers((args.mcp or []) + env_mcp_list) or None
@@ -2404,15 +2416,15 @@ def main():
     if not sys.stdin.isatty() and args.command is None:
         task = sys.stdin.read().strip()
         if task:
-            run_one_shot(task, skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+            run_one_shot(task, skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
         else:
             fail("No input provided via pipe.")
         return
 
     if args.command == "run":
-        run_one_shot(args.task, skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+        run_one_shot(args.task, skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
     else:
-        run_repl(skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, mcp_servers=mcp_servers)
+        run_repl(skip_instructions=skip_instructions, auto_approve=auto_approve, browser_enabled=browser_enabled, gui_enabled=gui_enabled, image_enabled=image_enabled, tmux_enabled=tmux_enabled, mcp_servers=mcp_servers)
 
 
 if __name__ == "__main__":