# How SwarmForge Honors tmux base-index and pane-base-index Settings

> SwarmForge respects your tmux base-index and pane-base-index settings. Discover how it dynamically adjusts window and pane targeting to match your custom configurations for seamless integration.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: internals
- Published: 2026-08-30

---

**SwarmForge detects your tmux numbering configuration at startup and dynamically adjusts all window and pane targeting to match your custom base-index and pane-base-index values.**

SwarmForge is a multi-agent orchestration tool that launches AI coding agents in tmux panes. Because tmux users often customize their indexing—starting windows at 1 instead of 0, for example—SwarmForge reads these settings to ensure commands hit the correct panes. This article explains exactly how SwarmForge implements this detection and applies it throughout its execution flow.

## Detecting tmux base-index and pane-base-index

When SwarmForge starts, `run-main!` invokes `detect-tmux-base-indexes` to query your active tmux configuration.

This function runs `tmux show-options` against two specific settings:

- **Global session option** `base-index` — stored as `:tmux-window-base-index`
- **Window-local option** `pane-base-index` — stored as `:tmux-pane-base-index`

If either value is non-numeric or unset, SwarmForge defaults to 0. Both values are persisted in the application context for downstream use.

```clojure
;; From swarmforge/scripts/swarmforge.bb (lines 88-96)
(defn detect-tmux-base-indexes [ctx]
  (let [base-index (or (get-tmux-option "base-index") "0")
        pane-base-index (or (get-tmux-option "pane-base-index") "0")]
    (assoc ctx
           :tmux-window-base-index (parse-long base-index)
           :tmux-pane-base-index (parse-long pane-base-index))))

```

The `get-tmux-option` helper shells out to `tmux show-options -g` to retrieve these values from your running tmux server.

## Building Correct tmux Target Strings

With base indexes captured, SwarmForge constructs tmux target strings that respect your numbering scheme. The `tmux-agent-target` function formats targets as `session:window.pane`, plugging in the detected `pane-base-index`:

```clojure
;; From swarmforge/scripts/swarmforge.bb (lines 75-77)
(defn tmux-agent-target [window pane-base-index session]
  (str session ":" window "." pane-base-index))

```

This target string is consumed by all tmux commands that interact with agent panes.

## Sending Commands to the Correct Pane

The `launch-role!` function demonstrates this in practice. When launching an agent, it builds the target using your detected `:tmux-pane-base-index` and passes it to `tmux send-keys`:

```clojure
;; From swarmforge/scripts/swarmforge.bb (lines 65-69)
(sh "tmux" "-S" (:tmux-socket ctx) "send-keys" "-t"
    (tmux-agent-target display (:tmux-pane-base-index ctx) session)
    command "Enter")

```

If your `pane-base-index` is set to 1, `(:tmux-pane-base-index ctx)` evaluates to 1, and the target becomes `session:window.1` rather than the default `session:window.0`. This prevents SwarmForge from sending keystrokes to the wrong pane when non-default indexing is in effect.

## Complete Usage Example

Here is how the pieces fit together in a typical workflow:

```clojure
;; 1. Detect indexes at startup (called by run-main!)
(def ctx (detect-tmux-base-indexes ctx))
;; ctx now contains:
;;   :tmux-window-base-index → 1 (or your base-index)
;;   :tmux-pane-base-index   → 1 (or your pane-base-index)

;; 2. Build target for a specific agent
(let [session "swarmforge-coder"
      window  "editor"
      pane    (:tmux-pane-base-index ctx)]
  (tmux-agent-target window pane session))
;; => "swarmforge-coder:editor.1"

;; 3. Send command to that pane
(sh "tmux" "-S" (:tmux-socket ctx) "send-keys" "-t"
    (tmux-agent-target "editor" (:tmux-pane-base-index ctx) "swarmforge-coder")
    "claude --version" "Enter")

```

## How the Detection Is Tested

The test suite validates this behavior explicitly. The test `swarmforge-detects-nonzero-pane-base-index` in `test/swarmforge/script_test.clj` (lines 818-828):

1. Creates a temporary [`tmux.conf`](https://github.com/unclebob/swarm-forge/blob/main/tmux.conf) with `base-index 2` and `pane-base-index 3`
2. Starts a tmux server with that configuration
3. Calls `detect-tmux-base-indexes`
4. Asserts that the returned context contains the expected non-zero values

This ensures SwarmForge continues to respect custom tmux configurations across releases.

## Summary

- **Detection:** `detect-tmux-base-indexes` queries `tmux show-options` for `base-index` and `pane-base-index` at startup
- **Storage:** Values are stored as `:tmux-window-base-index` and `:tmux-pane-base-index` in the application context
- **Application:** `tmux-agent-target` builds target strings using the detected pane base index
- **Execution:** `launch-role!` and other functions use these targets to send commands to the correct tmux panes
- **Verification:** The test suite includes explicit coverage for non-zero base index configurations

## Frequently Asked Questions

### What happens if tmux base-index is not set?

If `base-index` or `pane-base-index` are unset or non-numeric, SwarmForge defaults both values to 0. This matches tmux's default behavior, so standard configurations work without modification.

### Does SwarmForge support any base-index value, or just 0 and 1?

SwarmForge supports any numeric base-index and pane-base-index value. The detection logic parses the raw integer from tmux without constraints, and the test suite explicitly validates non-zero values like 2 and 3.

### Where is tmux base-index detection called in the codebase?

The detection is triggered once per session in `run-main!`, the primary entry point in `swarmforge/scripts/swarmforge.bb`. This ensures the context is populated before any agents are launched.

### Can I override the detected values manually?

The source code does not expose manual override flags—the values are strictly read from your tmux server via `tmux show-options`. To change SwarmForge's behavior, modify your tmux configuration file and restart the tmux server.