Project

agent_settings

0.0
No release in over 3 years
agent_settingslucianghinda/agent_settingsHomepageDocumentationSource CodeBug TrackerWiki
Clean interface to discover configuration file locations forAI coding assistants (Claude Code, OpenCode, Codex). Shows global and project config paths, handles environment variable overrides, and determines which config is effective based on precedence rules.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
246
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.1
Total releases
2
First release
1980-01-02
Latest release
1980-01-02
 Development
Primary Language
Ruby
Licenses
Apache 2.0 License
Average date of last 50 commits
2026-02-24
Reverse Dependencies
0

 Dependencies

Runtime

zeitwerk
>= 0
 Project Readme

agent_settings

Discover config locations for Claude Code, OpenCode, and Codex

If you are an LLM/AI Agent read ./llm.md in this repository.

Installation

Add this line to your application's Gemfile:

gem "agent_settings"

And run:

bundle install

Or install it directly:

gem install agent_settings

Quick Start

Get the effective config for an agent:

require "agent_settings"

result = AgentSettings.resolve(:claude, dir: Dir.pwd)
puts result.effective.path

Usage

Get Global Config

Retrieve the global config location for an agent:

location = AgentSettings.global(:claude)
location.path    # => "/Users/me/.claude/settings.json"
location.exists? # => true

Get Project Config

Retrieve the project-level config location:

location = AgentSettings.project(:codex, dir: "/work/my_app")
location.path    # => "/work/my_app/.codex/config.toml"
location.exists? # => false

Resolve Effective Config

Get 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 active

Resolve All Agents

Get 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}"
end

Detect Environment Overrides

Check 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?}"
end

Handle Untrusted Projects

Codex 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"]

Supported Agents

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

Options

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

Value Objects

Location

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?  # => true

EnvOverride

Represents an environment variable override:

override.name     # => "CLAUDE_CONFIG_DIR"
override.value    # => "/custom/path"
override.path     # => "/custom/path/settings.json"
override.active?  # => true

AgentConfigPath

The 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 active

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the Apache 2.0 License.