How SwarmForge Ensures Codex Trust for Worktree Directories

SwarmForge automatically modifies Codex's configuration to mark each worktree directory as trusted before launching any Codex-based role, preventing interactive confirmation prompts and ensuring seamless automated workflows.

Establishing codex trust for worktree directories is essential when treating the Codex LLM as a privileged agent in automated workflows. The unclebob/swarm-forge repository implements a deterministic verification system that programmatically amends the Codex configuration file at runtime. This guarantees that every worktree path used by a Codex role contains an explicit trust_level = "trusted" entry before any agent operations begin.

The Trust Verification Mechanism

When SwarmForge initiates a role configured to use the Codex agent, it executes a four-step validation process to guarantee the target directory is recognized as safe.

Detecting Codex Roles in launch-role!

The entry point for trust verification occurs within the launch-role! function defined in swarmforge/scripts/swarmforge.bb. Before creating the tmux session for a role, the code inspects the :agent key of the role configuration row. When the agent equals "codex", the system immediately invokes ensure-codex-trust! with the role's designated worktree path.

(defn launch-role! [ctx index row]
  (when (= "codex" (:agent row))
    (ensure-codex-trust! (:worktree-path row)))
  ;; ... continue with tmux session creation
  )

Locating the Codex Configuration Directory

The ensure-codex-trust! function first identifies where Codex stores its user-specific configuration. The codex-home helper function checks for the CODEX_HOME environment variable, falling back to the standard ~/.codex directory when the variable is unset.

(defn codex-home []
  (or (not-empty (System/getenv "CODEX_HOME"))
      (str (fs/path (System/getProperty "user.home") ".codex"))))

This ensures compatibility with both standard installations and custom Codex configurations regardless of the deployment environment.

Generating the Trust Configuration Entry

Before writing to the configuration file, SwarmForge generates a unique TOML table header that identifies the specific worktree directory. The project-table-header function creates a string that combines the [projects. prefix with the absolute, normalized path of the target directory.

(defn project-table-header [dir]
  (str "[projects." (pr-str (str (fs/absolutize dir))) "]"))

This produces a header like [projects."/absolute/path/to/worktree"] that serves as the configuration key for trust management.

Writing the Trust Level to config.toml

The core logic resides in ensure-codex-trust!, which checks for the existence of the generated table header within <codex-home>/config.toml. If the header is absent, the function creates the necessary directory structure and appends the trust configuration to the file while preserving existing content.

(defn ensure-codex-trust! [dir]
  (when-not (str/blank? (str dir))
    (let [home (codex-home)
          cfg  (fs/path home "config.toml")
          header (project-table-header dir)
          text (if (fs/exists? cfg) (slurp (str cfg)) "")]
      (when-not (str/includes? text header)
        (fs/create-dirs home)
        (spit (str cfg)
              (str (ensure-newline text)
                   "\n" header "\ntrust_level = \"trusted\"\n"))))))

This operation is idempotent; subsequent launches detect the existing entry via str/includes? and skip the write operation, minimizing filesystem I/O while maintaining codex trust for worktree directories across multiple executions.

Configuration File Structure

After SwarmForge processes a worktree directory, the Codex configuration file contains an entry that explicitly grants trusted status to that path:

[projects."/absolute/path/to/worktree"]
trust_level = "trusted"

With this entry present, the Codex agent recognizes the directory as safe and operates without prompting for user confirmation, enabling fully automated execution of SwarmForge roles.

Testing and Verification

The repository includes unit tests in test/swarmforge/script_test.clj that verify the trust mechanism functions correctly and writes entries exactly once. Developers can also manually invoke the trust helper using Babashka to validate specific paths:

bb swarmforge/scripts/swarmforge.bb --test-ensure-codex-trust /path/to/worktree

This command executes the same trust verification logic used during role launches, writing the necessary configuration entries to the local Codex configuration without requiring a full SwarmForge execution.

Summary

• Automatic detection: The launch-role! function in swarmforge/scripts/swarmforge.bb identifies Codex agents and triggers trust verification before tmux session creation.
• Dynamic configuration: The system reads the CODEX_HOME environment variable or defaults to ~/.codex to locate the user's Codex configuration.
• Idempotent writes: The ensure-codex-trust! function checks for existing trust entries before writing, ensuring the config.toml file receives each worktree directory entry exactly once.
• Non-interactive workflow: By pre-populating the trust configuration, SwarmForge eliminates confirmation prompts that would otherwise interrupt automated Codex operations.

Frequently Asked Questions

What happens if the CODEX_HOME environment variable is not set?

If CODEX_HOME is undefined, SwarmForge falls back to the standard user home directory, constructing the path ~/.codex using the user.home system property. This ensures the trust configuration is written to the default Codex configuration location regardless of environment-specific customizations.

Does SwarmForge overwrite existing Codex configuration entries?

No. The ensure-codex-trust! function explicitly checks for the existence of the project table header using str/includes? before writing. If the entry exists, the function skips the write operation entirely, preserving all existing configuration data and user customizations in config.toml.

Can I manually verify that a worktree directory is trusted?

Yes. After running SwarmForge or invoking the test helper, inspect the config.toml file in your Codex home directory (either $CODEX_HOME or ~/.codex). You should find a section matching [projects."/your/absolute/path"] with trust_level = "trusted" defined beneath it.

Is the trust verification performed for every role launch?

The verification logic executes during every call to launch-role! for Codex agents, but the actual disk write occurs only once per unique worktree path. Subsequent launches detect the existing trust entry and bypass the file modification, making the overhead negligible for repeated operations.

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