# How SwarmForge Isolates tmux Sessions for Different Projects > Learn how SwarmForge isolates tmux sessions for projects using unique Unix sockets and the -S flag for distinct, secure environments. Optimize your workflow today. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-08 --- **SwarmForge creates completely isolated tmux environments for each project by generating unique Unix socket files and binding every tmux command to that specific socket using the `-S` flag.** SwarmForge, the project orchestration tool from the `unclebob/swarm-forge` repository, ensures that concurrent projects never interfere with each other by running each inside its own dedicated tmux server. Rather than using the default system tmux socket, it dynamically constructs per-project socket paths that isolate sessions, windows, and panes from any other tmux instances on the host. ## Per-Project Socket Architecture SwarmForge establishes isolation at the filesystem level by creating unique socket directories and files for every project invocation. ### User-Specific Socket Directories When a SwarmForge run begins, it constructs a temporary directory under `/tmp` that is unique to both the current user and the specific project instance. In `swarmforge/scripts/swarmforge.bb` (lines 464-465), the socket directory is defined as: ```clojure (def tmux-socket-dir (fs/path "/tmp" (str "swarmforge-" (or (System/getenv "UID") (System/getProperty "user.name"))))) ``` This ensures that different users on a shared machine cannot access each other's SwarmForge tmux servers, providing the first layer of isolation. ### Unique Socket File Creation Inside that directory, SwarmForge generates a socket file with a random identifier (`socket-id`) to guarantee uniqueness across multiple runs. As implemented in `swarmforge.bb` (lines 465-466): ```clojure (def tmux-socket (str (fs/path tmux-socket-dir (str socket-id ".sock")))) ``` The resulting path—such as `/tmp/swarmforge-johndoe/abc123.sock`—serves as the dedicated communication endpoint for that project's tmux server. ## Persistent Socket State and Discovery To maintain isolation across process boundaries, SwarmForge persists the socket location and probes the new server for configuration details. ### Writing the Socket Path to Disk The absolute path to the generated socket is written to a state file within the project directory so that child processes and terminal adapters can locate it. According to `swarmforge.bb` (lines 246-247): ```clojure (spit (str (:tmux-socket-file ctx)) (str (:tmux-socket ctx) "\n")) ``` This creates a `.swarmforge/tmux-socket` file containing the path to the active socket, allowing external scripts to attach to the correct isolated environment without guessing the random identifier. ### Detecting Base Indexes On startup, SwarmForge queries the newly created socket to discover the tmux `base-index` and `pane-base-index` values (lines 88-97). By reading these directly from the isolated server rather than assuming defaults, SwarmForge ensures that window and pane numbering remains consistent within that project only, independent of any other tmux servers running on the host. ## Executing tmux Commands Against the Isolated Socket Every tmux operation is explicitly bound to the project-specific socket using the `-S` flag. This prevents commands from accidentally interacting with the user's default tmux sessions or other SwarmForge projects. The `tmux-agent-target` helper (lines 297-304) constructs commands such as: ```bash tmux -S $TMUX_SOCKET new-session -d -s swarmforge-coder ``` All subsequent operations—including creating windows, splitting panes, and querying options—use this same `-S $(cat .swarmforge/tmux-socket)` pattern. This strict socket binding guarantees that when you send commands to a SwarmForge-managed session, they affect only that specific project's environment. ## Session Cleanup and Isolation Guarantees When a project closes, SwarmForge terminates only the sessions belonging to its dedicated socket, leaving other tmux servers untouched. The cleanup logic in `swarmforge.bb` (lines 520-525) explicitly targets the isolated socket: ```clojure (defn kill-session! [tmux-socket session] (process/sh {:continue true} "tmux" "-S" tmux-socket "kill-session" "-t" session)) ``` By invoking `tmux -S $TMUX_SOCKET kill-session -t `, SwarmForge ensures that even if multiple instances are running simultaneously, closing one project never impacts the tmux sessions of another. ## Summary - **Unique socket directories**: SwarmForge creates user-specific directories under `/tmp` to prevent cross-user access. - **Randomized socket files**: Each run generates a unique `.sock` file with a random identifier to avoid collisions. - **State persistence**: The socket path is written to `.swarmforge/tmux-socket` for reliable discovery by child processes. - **Strict command binding**: Every tmux invocation uses the `-S` flag to target only the project-specific socket. - **Surgical cleanup**: Session termination targets only the isolated socket, ensuring other projects remain unaffected. ## Frequently Asked Questions ### Where does SwarmForge store the tmux socket files? SwarmForge stores tmux socket files in a directory under `/tmp` named `swarmforge-` (or using the `UID` environment variable if available). Inside this directory, it creates unique socket files with random identifiers and the `.sock` extension, such as `/tmp/swarmforge-johndoe/abc123.sock`. ### How does SwarmForge prevent interference with existing tmux sessions? SwarmForge prevents interference by never using the default tmux socket. Instead, it generates a unique Unix socket for each project and passes the `-S ` flag to every tmux command. This creates a completely separate tmux server instance that operates independently of any existing user sessions. ### Can multiple SwarmForge projects run simultaneously on the same machine? Yes. Because each SwarmForge invocation generates a unique socket file with a random `socket-id`, multiple projects can run concurrently without conflict. Each project operates within its own tmux server namespace, and the socket paths are stored separately in each project's `.swarmforge/` directory. ### How does SwarmForge clean up tmux sessions when a project closes? SwarmForge cleans up by explicitly killing sessions using the project-specific socket path. It reads the socket location from the state file and executes `tmux -S kill-session -t `, ensuring that only the sessions belonging to that specific project are terminated while leaving all other tmux servers and sessions untouched.