Headroom

CLAUDE_CONFIG_DIR explained: what it keeps separate

CLAUDE_CONFIG_DIR points Claude Code at a different configuration folder. Here is what lives in it, how the macOS Keychain follows it, and where it is ignored.

ยท 6 min read

CLAUDE_CONFIG_DIR is an environment variable that tells Claude Code where to keep its configuration. Without it, Claude Code uses the ~/.claude folder plus a ~/.claude.json file in your home folder. Set it to another folder and Claude Code keeps both there instead, with that folder's own settings, session history, plugins and sign-in. That is how you keep two accounts apart on one machine.

Anthropic's environment variable reference puts it plainly: it overrides the configuration directory, and "All settings, session history, and plugins are stored under this path" (environment variables). The step-by-step setup is in How to use several Claude Code accounts on one Mac; this post is the reference for what the variable does and where it stops.

What lives in the folder

From Anthropic's documentation, the folder named by CLAUDE_CONFIG_DIR holds:

  • your user settings
  • your session history
  • your plugins
  • the .claude.json file, which holds account details, MCP server configurations and other app state
  • your sign-in, whether that is a claude.ai login or an API key

The .claude.json line is the one people miss. For the default setup it sits outside the folder, at ~/.claude.json, so your main account is split across ~/.claude/ and ~/.claude.json. Anthropic's page on the .claude directory says that if you set CLAUDE_CONFIG_DIR, every ~/.claude path "lives under that directory instead", and "The same applies to .claude.json, which otherwise sits at ~/.claude.json" (.claude directory). The same page warns not to delete ~/.claude.json, ~/.claude/settings.json or ~/.claude/plugins/, because they hold your account details, preferences and installed plugins.

The authentication page says each directory has its own "settings, session history, and claude.ai login or API key" (authentication). So a second folder starts empty: new settings, no history, no plugins, and no one signed in. That is the point, and also the usual surprise when you first try it. You set up the second account from scratch.

Anthropic's example for work and personal accounts is:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

The variable is set only for that one command, so the folder applies to that session and nothing else in your shell.

Where the sign-in is stored on macOS

On macOS, Claude Code stores credentials in the encrypted macOS Keychain. If the Keychain rejects the write (for example when it is locked over SSH), Claude Code stores the login in ~/.claude/.credentials.json with file mode 0600 instead.

With CLAUDE_CONFIG_DIR set, Claude Code keeps that .credentials.json fallback file inside the folder instead, and "keys the macOS Keychain entry to that directory too, so a session with a different CLAUDE_CONFIG_DIR reads a different entry" (authentication). Two folders therefore mean two Keychain entries, one per account.

One caveat. Users reported that on some versions different folders shared a single Keychain entry, so the second sign-in replaced the first (GitHub issue 20553, still open as of November 2026, and a later duplicate, issue 70697). The current documentation describes one entry per folder. If you see the same account in two folders, update Claude Code and sign in again in the folder that is wrong.

What the variable does not separate

Console sign-ins made without an API key. Anthropic's documentation says separate directories do not keep two Claude Console sign-ins made without an API key apart, because that kind of sign-in is stored outside the configuration directory. If you need two Console identities, do not rely on folders to separate them.

The plan's limits. The folder separates logins, not what the plan counts. Anthropic says "your usage of all different Claude product surfaces (claude.ai, Claude Code, Claude Desktop) counts towards the same usage limit" (usage and length limits). Two folders signed in to the same account share one set of limits; two folders signed in to two accounts each draw on their own account's limits.

Other apps. A variable set in Terminal reaches only what you start from that Terminal. Claude Desktop's Code tab uses the account signed in to the app (Claude Code with Team and Enterprise), and the VS Code extension takes the variable through its own setting (see the path rules below). Run two Claude Code accounts at the same time covers both.

The path rules

Where the value goes decides how to write it.

  • In your shell, write it as in the alias above. The shell expands ~/.claude-work before Claude Code sees it.
  • In a Claude Code settings file, write an absolute path with no ~. The reference explains that values in a settings file are not processed by a shell, so ~ stays as typed (environment variables).
  • In project and local settings it is ignored. The reference says CLAUDE_CONFIG_DIR is ignored in project and local settings, so a repository cannot move your configuration folder.
  • In the VS Code extension's environmentVariables setting, a CLAUDE_CONFIG_DIR entry "applies only when its value is an absolute path; the extension doesn't expand ~ and ignores a relative value" (VS Code).

So a .claude/settings.json committed to a repo cannot change where your sign-in lives. The reference lists the places it does work: your shell, user settings, or managed settings.

Folder naming and what finds them

If you also use Headroom, a free Mac menu bar app that is independent of Anthropic, name each extra folder .claude- followed by a short name in your home folder, such as ~/.claude-work. Headroom finds every folder in the home folder named .claude or starting with .claude- that holds a signed-in account, and shows each one as a row with its session and weekly use. It reads the sign-in Claude Code already saved on your Mac. A folder with any other name or location is outside what Headroom looks for. Download it from the Headroom home page.

  • Sessions in the same folder share a login. Anthropic says parallel sessions on one machine "share a saved login and coordinate its renewal". This is why a second terminal in the same folder is signed in as the first, and why running two accounts at the same time needs two folders.
  • /logout is not folder housekeeping. Logging out "removes all stored credentials, including the plaintext file's contents, saved MCP server logins, and plugin sensitive values" (troubleshooting). The docs do not spell out what it does to other folders, so run it only in a session started with the folder you mean. Switch Claude Code accounts without logging out explains why you rarely need it.
  • An API key is not kept per folder. An ANTHROPIC_API_KEY exported in your shell profile is in the environment of every alias you define, and Claude Code can use it instead of your subscription. See Claude Code API key overrides subscription.

Checking a folder

Start Claude Code with the variable and run /status. The Status tab shows version, model, account and connectivity (commands). From a shell, claude auth status shows authentication status, but put the variable in front of it too, or it checks the default folder. If the account shown is not the one you expect, the variable was probably not set for that command.