Discover config locations for Claude Code, OpenCode, and Codex
If you are an LLM/AI Agent read ./llm.md in this repository.
Add this line to your application's Gemfile:
gem "agent_settings"And run:
bundle installOr install it directly:
gem install agent_settingsGet the effective config for an agent:
require "agent_settings"
result = AgentSettings.resolve(:claude, dir: Dir.pwd)
puts result.effective.pathRetrieve the global config location for an agent:
location = AgentSettings.global(:claude)
location.path # => "/Users/me/.claude/settings.json"
location.exists? # => trueRetrieve the project-level config location:
location = AgentSettings.project(:codex, dir: "/work/my_app")
location.path # => "/work/my_app/.codex/config.toml"
location.exists? # => falseGet the active config with full details:
result = AgentSettings.resolve(:opencode, dir: "/work/my_app")
result.effective.path # the active config path
result.global # global location
result.project # project location
result.layers # all config layers by precedence
result.env_overrides # environment variable overrides
result.warnings # any warnings
result.custom_config? # true if env override is activeGet config paths for all supported agents:
results = AgentSettings.all(dir: "/work/my_app")
results.each do |agent, config_path|
puts "#{agent}: #{config_path.effective.path}"
endCheck if environment variables override config paths:
result = AgentSettings.resolve(:opencode, dir: Dir.pwd, env: ENV)
result.env_overrides.each do |override|
puts "#{override.name}=#{override.value}"
puts " active: #{override.active?}"
endCodex ignores project config for untrusted projects:
# trusted (default) - includes project config
result = AgentSettings.resolve(:codex, dir: dir, trusted: true)
# untrusted - excludes project config
result = AgentSettings.resolve(:codex, dir: dir, trusted: false)
result.warnings # => ["Project config ignored for untrusted project"]| Agent | Global Config | Project Config |
|---|---|---|
| Claude | ~/.claude/settings.json |
.claude/settings.json |
| OpenCode | ~/.config/opencode/opencode.json |
opencode.json |
| Codex | ~/.codex/config.toml |
.codex/config.toml |
All methods accept these keyword arguments:
| Option | Type | Default | Description |
|---|---|---|---|
agent |
Symbol | required | :claude, :opencode, or :codex |
dir |
String | Dir.pwd |
Project directory path |
env |
Hash | ENV |
Environment variables hash |
trusted |
Boolean | true |
Trust project for Codex |
Represents a config file location:
location.agent # => :claude
location.scope # => :global or :project
location.path # => "/Users/me/.claude/settings.json"
location.exists? # => true
location.active? # => trueRepresents an environment variable override:
override.name # => "CLAUDE_CONFIG_DIR"
override.value # => "/custom/path"
override.path # => "/custom/path/settings.json"
override.active? # => trueThe result of resolving an agent's config:
config.effective # => Location (highest precedence)
config.global # => Location or nil
config.project # => Location or nil
config.layers # => Array of Location
config.env_overrides # => Array of EnvOverride
config.warnings # => Array of String
config.custom_config? # => true if env override activeBug reports and pull requests are welcome on GitHub.
The gem is available as open source under the terms of the Apache 2.0 License.