How to Configure Config File Paths and Precedence in Reasonix

Reasonix loads configuration from a hierarchy of built‑in defaults, legacy JSON, global TOML, workspace TOML, project‑level TOML, environment variables, and CLI flags, with later sources overriding earlier ones according to the precedence defined in internal/config/load.go.

The DeepSeek-Reasonix project implements a sophisticated configuration system that merges multiple sources according to a strict precedence order. Understanding how to configure config file paths and precedence in Reasonix is essential for controlling behavior across global user settings, workspace-specific requirements, and temporary overrides. The configuration logic resides in the internal/config package and supports TOML, JSON, and environment-based configuration.

Configuration Precedence Hierarchy

Reasonix applies a seven-layer configuration stack, implemented primarily in [internal/config/load.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/load.go). The system merges successive layers using config.Mutate() from [internal/config/mutate.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/mutate.go), with each layer overwriting conflicting keys from previous layers.

The precedence order from lowest to highest priority is:

1. Built‑in defaults – Hard‑coded fallback values defined in [internal/config/default_test.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/default_test.go).
2. Legacy global config – The JSON configuration at $HOME/.reasonix/config.json, maintained for v0.x compatibility as handled in [internal/config/migrate.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/migrate.go).
3. Global TOML config – The user‑wide configuration file located at $REASONIX_HOME/config.toml, resolved via config.MemoryUserDir() in [internal/config/paths.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/paths.go).
4. Workspace TOML config – The reasonix.toml file at the root of the current workspace.
5. Project TOML config – The .reasonix/config.toml file inside a specific project directory, referenced in [internal/config/load_project_default_test.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/load_project_default_test.go).
6. Environment variables – Variables prefixed with REASONIX_ (e.g., REASONIX_LOG_LEVEL), processed by [internal/config/environment_config.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/environment_config.go).
7. Command‑line flags – Arguments passed directly to the reasonix CLI, parsed in the cmd/ directory.

Config File Path Resolution

Global Configuration Directory

The global user configuration location is determined by config.MemoryUserDir() in [internal/config/paths.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/paths.go). This function follows OS‑specific conventions: it respects XDG directories on Linux and %APPDATA% on Windows. The function config.ReasonixManagedConfigPaths() returns the set of Reasonix‑owned files that may be written outside the workspace, including config.toml and credentials.json. Writes to these managed files are controlled by an interactive approval flow defined in [internal/tool/builtin/managed_config.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/tool/builtin/managed_config.go).

Workspace and Project Configuration

When Reasonix opens a workspace, it automatically searches for reasonix.toml at the workspace root. This file overrides any global settings. Additionally, individual projects may contain a .reasonix/config.toml file that is merged on top of the workspace configuration, allowing repository‑specific settings to travel with the code.

Practical Configuration Examples

Reading Configuration Programmatically

To access the fully merged configuration in Go code:

import (
    "fmt"
    "reasonix/internal/config"
)

func example() {
    cfg := config.Default()               // loads with full precedence
    logLevel := cfg.GetString("log.level") // e.g., "info" or "debug"
    fmt.Println("Current log level:", logLevel)
}

This example references the config.Default() function from [internal/config/config.go](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/config.go).

Overriding via Environment Variables

Any configuration key can be overridden using the REASONIX_ prefix:

export REASONIX_LOG_LEVEL=debug
reasonix run mytask

The environment_config.go module processes these variables after all file‑based configurations have been merged.

Using Custom Global Config Paths

You can redirect the global configuration location using the REASONIX_HOME environment variable or specify an explicit file via CLI flags:

export REASONIX_HOME=/custom/path
reasonix --config /custom/path/config.toml run mytask

Note that the explicit --config flag takes the highest precedence among all configuration sources.

Creating a Workspace Configuration

Create a reasonix.toml file at your workspace root to set local defaults:

[log]
level = "warn"

[sandbox]
allow_write = ["$HOME/tmp", "./data"]

When you execute reasonix within this workspace, the sandbox allow_write list from this file overrides global defaults, while the log.level setting affects only this workspace unless superseded by environment variables or flags.

Summary

• Reasonix uses a seven‑layer precedence stack: built‑in defaults → legacy JSON → global TOML → workspace TOML → project TOML → environment variables → CLI flags.
• Path resolution relies on config.MemoryUserDir() for global directories and supports XDG/%APPDATA% conventions via internal/config/paths.go.
• Workspace and project configs use reasonix.toml and .reasonix/config.toml respectively, loaded by internal/config/load.go.
• Environment variables prefixed with REASONIX_ override file settings and are handled in internal/config/environment_config.go.
• Managed config writes to global files require interactive approval through internal/tool/builtin/managed_config.go.

Frequently Asked Questions

What is the exact order of precedence for Reasonix configuration files?

Reasonix loads configuration in the following order, with each step overwriting conflicts from the previous: built‑in defaults, legacy $HOME/.reasonix/config.json, global $REASONIX_HOME/config.toml, workspace reasonix.toml, project .reasonix/config.toml, REASONIX_* environment variables, and finally CLI flags. This hierarchy is implemented in internal/config/load.go and merged using config.Mutate().

How do I temporarily override a specific configuration value without editing files?

Use environment variables with the REASONIX_ prefix followed by the uppercase key name. For example, setting REASONIX_LOG_LEVEL=debug will override the log level for that session without modifying any TOML files. The internal/config/environment_config.go file handles this resolution after all file configurations are loaded.

Where does Reasonix store global user configuration by default?

The global configuration directory is resolved by config.MemoryUserDir() in internal/config/paths.go, which follows OS conventions: typically ~/.config/reasonix/ on Linux (respecting $XDG_CONFIG_HOME), %APPDATA%\reasonix\ on Windows, and ~/Library/Application Support/reasonix/ on macOS. The main configuration file is config.toml within this directory.

Can I prevent Reasonix from writing to global config files automatically?

Yes. Writes to Reasonix‑managed global config files (such as config.toml and credentials.json) are gated by an interactive approval system defined in internal/tool/builtin/managed_config.go. This ensures that automated processes cannot modify global settings without explicit user consent.

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