SwarmForge Configuration File Location: Where swarmforge.conf Lives and How to Edit It

The SwarmForge configuration file is located at swarmforge/swarmforge.conf relative to the repository root, and each runnable branch contains its own local copy that the wrapper script automatically discovers.

This guide explains exactly where SwarmForge stores its configuration, how the startup process resolves the file path, and how to work with the config in daily development. The information below is drawn directly from the unclebob/swarm-forge source code as implemented in the launch scripts and documentation.

---

Where Is the SwarmForge Configuration File?

SwarmForge follows a predictable, project-relative convention for its configuration. The definitive location is:

swarmforge/swarmforge.conf

This file sits inside the swarmforge/ directory at the top level of any runnable branch. The design intentionally co-locates configuration with code, ensuring that each branch can carry its own environment-specific settings without cross-contamination.

Path Resolution at Runtime

The startup mechanism constructs this path programmatically in swarmforge/scripts/swarmforge.bb. The relevant code at lines 458–472 builds the configuration file path using:

:config-file (fs/path swarm-forge-dir "swarmforge.conf")

Here, swarm-forge-dir resolves to the swarmforge/ directory adjacent to the repository root. This indirection allows the wrapper to remain portable across different branches and working copies.

---

How the Wrapper Finds Your Configuration

The entry point wrapper (./swarm or equivalent) automates configuration discovery. According to the README (lines 19–20 and 93–94), each runnable branch:

• Contains its own swarmforge/swarmforge.conf
• Has that local configuration loaded automatically when the wrapper launches

This means you never need to pass --config flags or set environment variables manually—the tool assumes the standard location and fails gracefully if the file is missing or malformed.

---

Working with swarmforge.conf

Viewing the Current Configuration

# Display the active configuration file

cat swarmforge/swarmforge.conf

Editing Configuration Settings

# Open in your preferred editor

vim swarmforge/swarmforge.conf

# Or with nano

nano swarmforge/swarmforge.conf

Verifying Configuration Load

# Run the wrapper—the output will confirm or fail based on config parsing

./swarm

If the parser rejects your edits, the error message typically references the line number in swarmforge/swarmforge.conf, making debugging straightforward.

---

Validation and Testing

The test suite at test/swarmforge/script_test.clj (lines 98–119) exercises the configuration file mechanism directly. These tests:

• Write temporary swarmforge/swarmforge.conf files
• Exercise the same path-resolution logic used in production
• Validate round-trip read/write behavior

Running the test suite provides confidence that your local configuration changes won't break startup:

# Run configuration-related tests (adjust for your test runner)

clojure -M:test -n swarmforge.script-test

---

Key Files Governing Configuration Behavior

File	Purpose
swarmforge/scripts/swarmforge.bb	Builds and consumes the :config-file path at startup (lines 458–472)
README.md	Documents the branch-local configuration pattern (lines 19–21, 93–94)
test/swarmforge/script_test.clj	Automated coverage for configuration file I/O (lines 98–119)

---

Summary

• Primary location: swarmforge/swarmforge.conf at repository root
• Resolution method: fs/path construction in swarmforge.bb using swarm-forge-dir
• Branch behavior: Each runnable branch maintains its own isolated configuration
• Wrapper integration: Zero-configuration discovery via the ./swarm entry point
• Test coverage: Validated in script_test.clj with temporary file round-trips

---

Frequently Asked Questions

Can I relocate swarmforge.conf to a different directory?

No—the path is hardcoded in swarmforge/scripts/swarmforge.bb at line 458. The fs/path call concatenates swarm-forge-dir with the string "swarmforge.conf". To use a custom location, you would need to modify the source and rebuild the wrapper.

Does SwarmForge support environment-specific overrides?

Yes, through branch-local configurations. Since every runnable branch carries its own swarmforge/swarmforge.conf, you achieve environment separation by checking out or deploying the appropriate branch rather than maintaining external override files.

What happens if swarmforge.conf is missing?

The wrapper launched via ./swarm will fail during startup because the :config-file entry is expected in the options map built at lines 458–472. The error typically surfaces as a Babashka exception with a clear message about the missing file path.

How do I validate my configuration changes before committing?

Run the project's test suite, specifically the namespace exercised in test/swarmforge/script_test.clj. The tests at lines 98–119 simulate configuration file operations and will catch syntax errors or structural problems before they reach production branches.

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