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

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.

;; 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:

;; 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:

;; 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:

;; 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}