# How Swarm-Forge Implements Project-Isolated TMUX Socket Naming Conventions

> Discover Swarm-Forge's project-isolated tmux socket naming. Learn how it uses user temp directories and CRC32 checksums for unique, isolated sockets, preventing project conflicts.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-10

---

**Swarm-Forge generates a unique TMUX socket for each project by combining a per-user temporary directory with a CRC32 checksum of the absolute working directory path, ensuring complete isolation between concurrent projects.**

The **TMUX socket naming convention** in Swarm-Forge is designed to prevent session collisions when multiple projects run simultaneously. According to the `unclebob/swarm-forge` source code, this isolation is achieved through deterministic path generation and explicit socket targeting in all TMUX commands.

## Understanding the Socket Path Structure

Swarm-Forge constructs the full socket path using two components:

| Component | Derivation | Result |
|-----------|-----------|--------|
| **Socket directory** | `/tmp/swarmforge-` + current user UID (or `user.name` fallback) | Per-user temp folder |
| **Socket filename** | CRC32 checksum of absolute working directory + `.sock` | Unique per project |

The complete path follows this pattern:

```bash
/tmp/swarmforge-<uid>/<crc32-of-working-dir>.sock

```

This structure guarantees that two different projects—even for the same user—receive distinct socket files because the **absolute project directory** feeds into the checksum calculation.

## How the Socket Is Generated

In [`swarmforge/scripts/swarmforge.bb`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.bb), the `context` function implements the **TMUX socket naming convention** at lines 64-66:

```clojure
(defn context [working-dir]
  (let [working-dir (fs/absolutize (fs/path working-dir))
        crc (java.util.zip.CRC32.)
        _ (.update crc (.getBytes (str working-dir) java.nio.charset.StandardCharsets/UTF_8))
        socket-id (str (.getValue crc))                         ;; ← unique per project
        tmux-socket-dir (fs/path "/tmp"
                                 (str "swarmforge-"
                                      (or (System/getenv "UID")
                                          (System/getProperty "user.name"))))
        tmux-socket (str (fs/path tmux-socket-dir (str socket-id ".sock")))]
    {:tmux-socket-dir tmux-socket-dir
     :tmux-socket     tmux-socket}))

```

The `socket-id` variable captures the CRC32 value, which serves as the **project fingerprint**. Because it derives from the full absolute path, renaming or moving a project changes its socket identity.

## Project Isolation Mechanism

Swarm-Forge enforces **project isolation** through three concrete steps:

1. **Directory creation** — `fs/create-dirs` ensures the per-user socket directory exists before any TMUX interaction
2. **State persistence** — The socket path is written to `.swarmforge/tmux-socket` for subprocess discovery
3. **Explicit socket targeting** — Every TMUX command uses the `-S` flag with the generated path

This last step is critical. Here's how Swarm-Forge creates a detached session using the isolated socket:

```bash

# Example TMUX command using the generated socket

tmux -S /tmp/swarmforge-1000/12345678.sock new-session -d -s my-session sleep 120

```

And here's session cleanup with the same isolation guarantee:

```clojure
;; Checking/cleaning a session belonging to this project
(when (sh-ok? "tmux" "-S" (:tmux-socket ctx) "has-session" "-t" (:session row))
  (sh "tmux" "-S" (:tmux-socket ctx) "kill-session" "-t" (:session row)))

```

The `-S` flag appears in every TMUX invocation, ensuring commands only affect the current project's session space.

## Socket Persistence and Discovery

Swarm-Forge persists the socket path so that external processes and terminal adapters can reconnect to the correct session:

```clojure
;; Persist the socket path so other scripts can read it
(spit (str (:tmux-socket-file ctx))
      (str (:tmux-socket ctx) "\n"))

```

Shell wrappers in [`swarmforge/scripts/terminal-adapters/*.sh`](https://github.com/unclebob/swarm-forge/tree/main/swarmforge/scripts/terminal-adapters) read this value and execute:

```bash
exec tmux -S "$TMUX_SOCKET" attach-session -t "$SESSION_NAME"

```

This allows seamless handoff between Swarm-Forge's Clojure core and external terminal processes while maintaining **project-scoped isolation**.

## CRC32 Collision Resistance

A 32-bit CRC32 provides 4,294,967,296 possible values. For the **TMUX socket naming convention**, this is practically collision-free given that:

- Socket directories are already segmented by user UID
- Projects typically number in the dozens per user, not millions
- The absolute path includes high-entropy components like usernames and deep directory structures

The deterministic nature also means the same project always receives the same socket path on restart, enabling idempotent session management.

## Summary

- **Swarm-Forge** uses `/tmp/swarmforge-<uid>/<crc32>.sock` as its **TMUX socket naming convention**
- The CRC32 checksum of the absolute working directory ensures **project-isolated** sockets
- All TMUX commands explicitly target the socket via `-S`, preventing cross-project interference
- Socket paths are persisted to `.swarmforge/tmux-socket` for subprocess discovery
- The implementation lives primarily in `swarmforge/scripts/swarmforge.bb` lines 64-66

## Frequently Asked Questions

### What happens if two users run Swarm-Forge on the same project directory?

Each user receives a distinct socket directory due to the UID/username component (`/tmp/swarmforge-1000/` vs `/tmp/swarmforge-1001/`). The CRC32 portion may match, but the full paths remain unique, ensuring no socket collision occurs.

### Can I change where Swarm-Forge stores its TMUX sockets?

The source code hardcodes `/tmp` as the base directory in the `context` function. To relocate sockets, you would need to modify `swarmforge.bb` and rebuild. There is no configuration flag for this path.

### Why does Swarm-Forge use CRC32 instead of a cryptographic hash?

CRC32 is sufficient for **unique identification** without the computational overhead of SHA or MD5. TMUX socket names don't require cryptographic security—only collision avoidance and deterministic generation.

### How does Swarm-Forge clean up old socket files?

The codebase does not implement automatic socket cleanup. Socket files persist in `/tmp` until system reboot or manual deletion. However, since sockets are recreated on each project start, stale files have no functional impact.