hats

English | 简体中文

Run Claude Code, Codex, and other command-line AI tools with different providers concurrently — without switching shared configuration.

Install

Homebrew (recommended)

brew install colafornia/tap/hats

Standalone installer

curl -fsSL https://raw.githubusercontent.com/Colafornia/hats/main/install.sh | sh

Quick start

Create a hat for any AI CLI:

hats add work claude
hats work

Each run applies that hat's environment only to the launched process. Other terminals keep running with their existing providers.

Run hats add without arguments for guided setup. To configure provider variables, use hats edit or see Advanced configuration.

Why

Your work terminal uses a company gateway. Another terminal uses a personal API account or a local model. Global switchers make only one shared configuration current.

hats applies each hat only to the process it launches, so both setups can keep running at the same time.

To prevent accidental overrides, hats removes inherited provider credentials such as ANTHROPIC_*, OPENAI_*, and CODEX_* before applying the variables configured for the selected hat.

See Advanced configuration for env references, local models, and manual configuration.

Use one environment across CLIs

Give the hat a default command, then replace it after -- when you want another CLI:

[profiles.work]
launch = "claude"
env_file = "~/.config/company-ai.env"

hats work
hats work -- codex

The -- boundary must immediately follow the hat name. Without it, trailing arguments are appended to the default command.

Optional: isolate CLI state

Provider environments are process-local by default, but hats for the same CLI still share the CLI's normal config home. Add --isolated when a hat also needs its own home:

hats add personal codex --isolated

Files stored in that home—including settings, MCP configuration, plugins, and history— remain separate. Built-in config-home isolation is available for Codex and Claude Code.

This isolates local CLI state. Authentication and OAuth behavior remain controlled by the underlying CLI.

Commands

hats add [<name> <command...>]    create a hat
hats <hat> [args...]              launch a hat (same as hats run <hat>)
hats <hat> -- <command...>        replace the hat's default command
hats edit                         open the config in $EDITOR
hats ls                           list hats

hats                              show hats and first-run hints
hats init                         write an example config
hats add <name> <command...> --isolated
hats exec <hat> -- <cmd>          run another command with the hat's env
hats which <hat>                  inspect a hat, with secrets masked
hats setenv <hat> --file .env     merge env vars from KEY=value lines
hats rm <hat>                     delete a hat
hats completion <shell>           output Bash, Zsh, or Fish completion code

Shell completion

Homebrew enables completion automatically. For other installs, add the command for your shell to its startup file:

eval "$(hats completion zsh)"

eval "$(hats completion bash)"

hats completion fish | source

Optional integrations

• HATS_PROFILE exposes the selected profile to scripts and status lines.
• tmux can show the active hat in pane borders.
• Herdr can show it in the Agent sidebar.

See Active hat indicators for setup examples.

Other CLIs and limitations

hats can still launch other CLIs with a process-local environment. If hats cannot infer a safe config home, --isolated returns an error:

• OpenCode stores credentials outside its config home. Use provider keys through the hat's env or env_file. hats does not redirect XDG_DATA_HOME because that would affect every XDG-aware process launched by the CLI.

Non-goals

• No global provider switching.
• No credential vault or OAuth management.
• No interactive hat picker. Launching stays explicit: hats <name>.

Support

Found a bug or have an idea? Open an issue.

License

MIT