Configuration

Flux merges defaults, ~/.flux/config.json, and ./.flux/config.json in that order. Environment variables then override provider credentials and Ollama address settings; CLI flags override the active startup values.

{
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "effort": "medium",
  "maxTokens": 16384,
  "maxIterations": 800,
  "errorRetries": 5,
  "permissionMode": "ask",
  "allowedTools": ["read_file", "run_command:npm run *"],
  "systemPrompt": "Follow the conventions documented in this repository.",
  "hooks": {
    "afterEdit": "npm run typecheck",
    "afterShell": "git status --short",
    "preCommit": "npm test"
  },
  "theme": {
    "userLabel": "blue",
    "agentLabel": "magenta",
    "promptColor": "green"
  },
  "mcpServers": {}
}

#Fields

Field	Values or behavior
`provider`	`anthropic`, `openai`, `gemini`, or `ollama`
`model`	Provider-specific model identifier
`effort`	`low`, `medium`, `high`, or `max`; invalid values fall back to `medium`
`maxTokens`	Maximum output tokens per model response
`maxIterations`	Maximum agent/tool iterations; must be a positive integer
`errorRetries`	Transient provider retries; must be zero or greater
`permissionMode`	`ask`, `auto-accept`, or `deny-writes`
`allowedTools`	Tool names or scoped patterns that can run without confirmation
`systemPrompt`	Additional project instructions
`hooks`	Optional commands for `afterEdit`, `afterShell`, and `preCommit`
`theme`	Partial terminal color overrides
`mcpServers`	Named stdio MCP server definitions

Project allowedTools entries are added to global entries rather than replacing them. The generated top-level template object in project configuration is documentation metadata and is removed before runtime merging.