Agent::Homedir

Find the home folder an AI coding agent uses, without reading contents.

Use Ruby 3.2 or newer. The gem ships with one runtime dependency: Zeitwerk 2.8.

Add this line to your application's Gemfile:

gem "agent_homedir"

Then run:

bundle install

Or install it directly:

gem install agent_homedir

Get a home path:

require "agent_homedir"

Agent::Homedir.home(:claude_code)

Check installation:

require "agent_homedir"

Agent::Homedir.installed?(:codex)

Expect a Pathname and a boolean.

The module facade is snapshotted on first access. That snapshots ENV and HOME for the rest of the process. If you need a different snapshot, instantiate Agent::Homedir::Resolver directly.

Fetch an agent:

require "agent_homedir"

agent = Agent::Homedir[:codex]

agent.name
agent.label
agent.home

Discover the catalog:

require "agent_homedir"

Agent::Homedir.names
Agent::Homedir.agents
Agent::Homedir.installed

Expect ordered, frozen arrays.

Use these names with every lookup method:

Inspect agent facts:

require "agent_homedir"

agent = Agent::Homedir[:claude_code]

agent.env_override
agent.verified_on
agent.candidates

Resolution order:

• Use a nonblank native override.
• Use the first existing directory candidate.
• Use the first candidate otherwise.

Agent facts:

• name is a Symbol.
• label is a String.
• home returns a Pathname.
• installed? returns a boolean.
• candidates returns an ordered, frozen array of Pathname objects.
• env_override is a String or nil.
• verified_on is a Date or nil.

Errors:

• Catch Agent::Homedir::UnknownAgent to list valid names.
• Catch Agent::Homedir::HomeNotResolvable for missing, blank, or nonabsolute HOME.

Pass env, home, and os explicitly. Instantiate a fresh resolver when you need a different environment snapshot. Do not stub global ENV.

require "agent_homedir"

resolver = Agent::Homedir::Resolver.new(
  env: { "CODEX_HOME" => "custom/codex" },
  home: "/Users/me",
  os: :linux
)

resolver.home(:codex)
# => #<Pathname:/Users/me/custom/codex>

Activate Ruby 3.2 or newer.

Run the tests before sending a change.

bundle install
bundle exec rake test

MIT