Module: AgentSettings

Defined in:
lib/agent_settings.rb,
lib/agent_settings/version.rb,
lib/agent_settings/location.rb,
lib/agent_settings/registry.rb,
lib/agent_settings/env_override.rb,
lib/agent_settings/adapters/codex.rb,
lib/agent_settings/adapters/claude.rb,
lib/agent_settings/adapters/opencode.rb,
lib/agent_settings/agent_config_path.rb,
lib/agent_settings/location_discovery.rb

Overview

Discover config locations for Claude Code, OpenCode, and Codex.

This gem provides a clean interface to find where agent configuration files are located, whether they exist, and which one is currently effective based on precedence rules and environment variable overrides.

Trusted vs Untrusted Projects

The trusted parameter controls whether project-level config is included in resolution. This is a security feature for Codex:

  • Trusted projects (trusted: true): Project config is included in resolution. Use this for projects you own or have reviewed.
  • Untrusted projects (trusted: false): Project config is ignored for Codex. This prevents untrusted code repositories from injecting malicious configuration. A warning is added if a .codex/config.toml file exists but is ignored.

Claude Code and OpenCode do not use the trust model - their project configs are always included regardless of the trusted parameter.

Examples:

Get global config location

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

Resolve effective config with all details

result = AgentSettings.resolve(:opencode, dir: "/work/my_app")
result.effective.path   #=> the active config path
result.custom_config?   #=> true if env override is active

Resolve all agents at once

results = AgentSettings.all(dir: Dir.pwd)
results.each do |agent, config_path|
  puts "#{agent}: #{config_path.effective.path}"
end

Untrusted project (Codex ignores project config)

result = AgentSettings.resolve(:codex, dir: "/untrusted/repo", trusted: false)
result.project   #=> nil (ignored for security)
result.warnings  #=> ["Project config ignored for untrusted project"]

Defined Under Namespace

Modules: Adapters, LocationDiscovery, Registry Classes: AgentConfigPath, EnvOverride, Error, Location, UnknownAgentError

Constant Summary collapse

VERSION =

Current gem version.

"0.1.1"

Class Method Summary collapse

Class Method Details

.all(dir:, env: ENV, trusted: true) ⇒ Hash{Symbol => AgentConfigPath}

Resolve config paths for all supported agents.

Returns a hash mapping each agent symbol to its AgentConfigPath result. Useful for getting an overview of all agent configurations at once.

Examples:

results = AgentSettings.all(dir: "/work/my_app")
results.each do |agent, config_path|
  puts "#{agent}: #{config_path.effective.path}"
  puts "  exists: #{config_path.effective.exists?}"
end

Parameters:

  • project directory path (required)

  • (defaults to: ENV)

    environment variables hash (default: ENV)

  • (defaults to: true)

    whether the project is trusted (default: true)

Returns:

  • map of agent to config path



148
149
150
 
# File 'lib/agent_settings.rb', line 148

def all(dir:, env: ENV, trusted: true)
  LocationDiscovery.all(dir: dir, env: env, trusted: trusted)
end

.global(agent, env: ENV, dir: Dir.pwd, trusted: true) ⇒ Location?

Get the global config location for an agent.

The global config is typically stored in the user's home directory and applies across all projects.

Examples:

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

Parameters:

  • the agent identifier (:claude, :opencode, :codex)

  • (defaults to: ENV)

    environment variables hash (default: ENV)

  • (defaults to: Dir.pwd)

    project directory path (default: Dir.pwd)

  • (defaults to: true)

    whether the project is trusted (default: true)

Returns:

  • the global config location, or nil if not found



71
72
73
 
# File 'lib/agent_settings.rb', line 71

def global(agent, env: ENV, dir: Dir.pwd, trusted: true)
  LocationDiscovery.global(agent, env: env, dir: dir, trusted: trusted)
end

.project(agent, dir:, env: ENV, trusted: true) ⇒ Location?

Get the project-level config location for an agent.

Project configs are stored within the project directory and apply only to that specific project.

Note: For Codex, project config is ignored when trusted: false. This is a security measure to prevent untrusted repositories from injecting malicious configuration. In this case, returns nil and a warning is added to the resolve result.

Examples:

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

Parameters:

  • the agent identifier (:claude, :opencode, :codex)

  • project directory path (required)

  • (defaults to: ENV)

    environment variables hash (default: ENV)

  • (defaults to: true)

    whether the project is trusted (default: true)

Returns:

  • the project config location, or nil if not applicable



95
96
97
 
# File 'lib/agent_settings.rb', line 95

def project(agent, dir:, env: ENV, trusted: true)
  LocationDiscovery.project(agent, dir: dir, env: env, trusted: trusted)
end

.resolve(agent, dir:, env: ENV, trusted: true) ⇒ AgentConfigPath

Resolve the complete config path information for an agent.

This is the primary method for discovering all config-related information for an agent. It returns an AgentConfigPath object containing the effective config location, global and project locations, all layers by precedence, environment variable overrides, and any warnings.

The effective location is determined by:

  1. Active environment variable overrides (highest precedence)
  2. First existing layer in precedence order
  3. First layer if none exist

Examples:

Basic usage

result = AgentSettings.resolve(:claude, dir: Dir.pwd)
result.effective.path   #=> the active config path
result.effective.exists? #=> whether the config file exists
result.custom_config?   #=> true if env override is active

With environment overrides

env = { "OPENCODE_CONFIG" => "/custom/config.json" }
result = AgentSettings.resolve(:opencode, dir: Dir.pwd, env: env)
result.env_overrides.first.name   #=> "OPENCODE_CONFIG"
result.env_overrides.first.active? #=> true (if file exists)

Parameters:

  • the agent identifier (:claude, :opencode, :codex)

  • project directory path (required)

  • (defaults to: ENV)

    environment variables hash (default: ENV)

  • (defaults to: true)

    whether the project is trusted (default: true)

Returns:

  • complete config path information



128
129
130
 
# File 'lib/agent_settings.rb', line 128

def resolve(agent, dir:, env: ENV, trusted: true)
  LocationDiscovery.resolve(agent, dir: dir, env: env, trusted: trusted)
end