Order of Precedence for Configuration Resolution in Reasonix: Flag → Project → User → Defaults

Reasonix resolves configuration in a strict hierarchy where command-line flags override project files, which override user settings, which finally fall back to built-in defaults.

Reasonix (DeepSeek-Reasonix) implements a deterministic four-layer configuration system that merges settings from multiple sources. Understanding the order of precedence for configuration resolution is essential for debugging unexpected behavior and structuring your reasonix.toml files correctly. The precedence chain ensures that temporary overrides via CLI take effect while preserving permanent customizations in project and user directories.

The Four-Layer Configuration Hierarchy

Reasonix loads configuration by merging sources in a specific sequence where each layer can only populate missing fields—it never overwrites values already set by higher-priority sources.

1. Command-Line Flags (Highest Priority)

Values supplied directly on the CLI take precedence over all other sources. For example, --max-steps 10 immediately shadows any value defined in project files or user configuration.

2. Project Configuration

The reasonix.toml file located in the project root (./reasonix.toml) provides repository-scoped settings. This allows teams to commit shared defaults without affecting other projects on the same machine.

3. User-Level Configuration

Global settings stored in the operating system's user-config directory (e.g., ~/.config/reasonix/config.toml) apply across all projects. These are ideal for personal preferences like UI themes or network proxies that should persist across repositories.

4. Built-In Defaults (Lowest Priority)

Hard-coded defaults shipped with the Reasonix binary guarantee a complete configuration even when no user or project files exist. These ensure the application can start with sensible values in any environment.

How the Resolution Logic Works in Code

The merging logic is implemented in internal/config/load.go within the LoadForRoot function. This function orchestrates the precedence chain by loading sources sequentially and applying a "fill-only-if-missing" strategy.

According to the package documentation in internal/config/config.go (lines 1-4), the resolution order is explicitly defined as flags → project → user → defaults. This documentation serves as the canonical specification for the configuration system's behavior.

When Reasonix renders a TOML configuration file for display or documentation purposes, internal/config/render.go (lines 46-50) generates a header that dynamically inserts the user config path while reiterating this exact precedence chain. This ensures users see the hierarchy every time they inspect their effective configuration.

The same precedence description appears in the internationalization layer at internal/i18n/messages_en.go (lines 406-408), ensuring UI messages consistently communicate the resolution order to end users.

Practical Configuration Loading Examples

To load the fully resolved configuration for the current working directory, use the Load function from the config package:

// Load configuration respecting the precedence chain:
// flags → ./reasonix.toml → ~/.config/reasonix/config.toml → defaults
cfg, err := config.Load()
if err != nil {
    log.Fatalf("config load failed: %v", err)
}

When executing Reasonix programmatically, remember that environment variables or explicit flags take precedence over file-based settings:

// Example: overriding a value at runtime via command-line flag
cmd := exec.Command("reasonix", "run", "--max-steps", "5")
// The --max-steps flag will shadow any value in reasonix.toml or user config

This behavior ensures that CI/CD pipelines can inject temporary overrides without modifying committed configuration files.

Summary

• Command-line flags always win—they are parsed first and shadow all other sources.
• Project files (reasonix.toml) provide repository-specific defaults that apply unless overridden by flags.
• User configuration stores machine-wide preferences that apply across all projects unless a project file exists.
• Built-in defaults guarantee Reasonix can start with valid settings even when no configuration files are present.

Frequently Asked Questions

What is the exact order of precedence for configuration resolution in Reasonix?

The exact order is: command-line flags → project configuration (./reasonix.toml) → user configuration (~/.config/reasonix/config.toml) → built-in defaults. This sequence is documented in the package comment of internal/config/config.go and rendered in the TOML header output by internal/config/render.go.

Can a project reasonix.toml override a command-line flag?

No. Configuration resolution in Reasonix uses a "higher wins" strategy where flags are processed first. A project file can only populate values that are not already set by a flag. If you specify --max-steps 10 on the CLI, the value in reasonix.toml is ignored for that execution.

Where does Reasonix store user-level configuration files?

Reasonix follows OS conventions for user configuration storage. On Linux, this is typically ~/.config/reasonix/config.toml. The exact path is dynamically inserted into help text and rendered headers, as seen in internal/config/render.go (lines 46-50), to ensure users always know which file is being sourced.

What happens if a configuration key is missing from all files?

If a key is absent from flags, project files, and user configuration, Reasonix falls back to its built-in defaults defined in the source code. This guarantees that the application always starts with a complete, valid configuration structure even in fresh environments.

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