feat(config): add OPENCLAUDE_CONFIG_DIR env var as preferred alias for CLAUDE_CONFIG_DIR (#454)

The legacy CLAUDE_CONFIG_DIR name was the only way to point openclaude
at a non-default config home, which leaked Anthropic branding for a
fork that has otherwise rebranded to OpenClaude. Add OPENCLAUDE_CONFIG_DIR
as the preferred name. CLAUDE_CONFIG_DIR continues to work for
backward compatibility; when both are set with different values,
OPENCLAUDE_CONFIG_DIR wins and a one-time warning is logged.

- src/utils/envUtils.ts: introduce resolveConfigDirEnv() that picks
  OPENCLAUDE_CONFIG_DIR over CLAUDE_CONFIG_DIR and emits a conflict
  warning. Memoize cache key now tracks both env vars so changing
  either invalidates the cached result.
- src/utils/env.ts: getGlobalClaudeFile() previously read
  CLAUDE_CONFIG_DIR directly, missing the new alias. Route through
  resolveConfigDirEnv() so the global config file path follows the
  same precedence.
- src/utils/secureStorage/macOsKeychainHelpers.ts: the "is default
  dir" check used by keychain service-name scoping now considers
  both env vars.
- src/utils/swarm/spawnUtils.ts: forward OPENCLAUDE_CONFIG_DIR to
  teammate processes alongside the legacy var.
- src/utils/openclaudePaths.test.ts: +6 unit tests covering the new
  alias, fallthrough, conflict warning, and resolveConfigDirEnv()
  in isolation.
- .env.example: document both env vars and the precedence rule.

Verified locally on Linux: with only OPENCLAUDE_CONFIG_DIR set, with
only CLAUDE_CONFIG_DIR set (legacy still works), with both set
matching (silent), with both set conflicting (warn once + OPENCLAUDE
wins), with neither set (default ~/.openclaude). Memo cache
invalidates across 4 sequential env transitions. Built dist/cli.mjs
honors the new var and emits the conflict warning to the user.

.env.example

@@ -421,3 +421,16 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # WEB_CUSTOM_ALLOW_HTTP=false                — set "true" to allow http:// URLs
 # WEB_CUSTOM_ALLOW_PRIVATE=false             — set "true" to target localhost/private IPs
 #                                               (needed for self-hosted SearXNG)
+
+# ── Config directory override ───────────────────────────────────────
+#
+# By default openclaude stores per-user state under ~/.openclaude
+# (and falls back to ~/.claude for installs that pre-date the rename).
+# Set this to point openclaude at a different directory — useful for
+# isolating profiles or sharing config across machines.
+#
+# OPENCLAUDE_CONFIG_DIR=/path/to/dir         — preferred name
+# CLAUDE_CONFIG_DIR=/path/to/dir             — legacy alias (still works)
+#
+# When both are set with different values, OPENCLAUDE_CONFIG_DIR wins
+# and a warning is logged once per process.

src/components/PromptInput/PromptInput.tsx

@@ -111,7 +111,7 @@ import { BackgroundTasksDialog } from '../tasks/BackgroundTasksDialog.js';
 import { shouldHideTasksFooter } from '../tasks/taskStatusUtils.js';
 import { TeamsDialog } from '../teams/TeamsDialog.js';
 import VimTextInput from '../VimTextInput.js';
-import { detectModeEntry, getModeFromInput, getValueFromInput } from './inputModes.js';
+import { getModeFromInput, getValueFromInput } from './inputModes.js';
 import { FOOTER_TEMPORARY_STATUS_TIMEOUT, Notifications } from './Notifications.js';
 import PromptInputFooter from './PromptInputFooter.js';
 import type { SuggestionItem } from './PromptInputFooterSuggestions.js';
@@ -878,22 +878,24 @@ function PromptInput({
     abortPromptSuggestion();
     abortSpeculation(setAppState);
 
-    // Strip the mode character from the buffer when entering bash mode — the
+    // Check if this is a single character insertion at the start
-    // mode itself is shown via the prompt prefix in the UI. Without this,
+    const isSingleCharInsertion = value.length === input.length + 1;
-    // typing `!` into empty input would enter bash mode but leave the literal
+    const insertedAtStart = cursorOffset === 0;
-    // `!` in the buffer (issue #662).
+    const mode = getModeFromInput(value);
-    const modeEntry = detectModeEntry({
+    if (insertedAtStart && mode !== 'prompt') {
-      value,
+      if (isSingleCharInsertion) {
-      prevInputLength: input.length,
+        onModeChange(mode);
-      cursorOffset,
+        return;
-    });
+      }
-    if (modeEntry) {
+      // Multi-char insertion into empty input (e.g. tab-accepting "! gcloud auth login")
-      onModeChange(modeEntry.mode);
+      if (input.length === 0) {
-      const cleaned = modeEntry.strippedValue.replaceAll('\t', '    ');
+        onModeChange(mode);
-      pushToBuffer(input, cursorOffset, pastedContents);
+        const valueWithoutMode = getValueFromInput(value).replaceAll('\t', '    ');
-      trackAndSetInput(cleaned);
+        pushToBuffer(input, cursorOffset, pastedContents);
-      setCursorOffset(cleaned.length);
+        trackAndSetInput(valueWithoutMode);
-      return;
+        setCursorOffset(valueWithoutMode.length);
+        return;
+      }
     }
     const processedValue = value.replaceAll('\t', '    ');
 

src/components/PromptInput/inputModes.test.ts

@@ -1,104 +0,0 @@
-import { describe, expect, it } from 'bun:test'
-import {
-  detectModeEntry,
-  getModeFromInput,
-  getValueFromInput,
-  isInputModeCharacter,
-  prependModeCharacterToInput,
-} from './inputModes.js'
-
-describe('inputModes', () => {
-  describe('getModeFromInput', () => {
-    it('returns bash mode for input starting with !', () => {
-      expect(getModeFromInput('!')).toBe('bash')
-      expect(getModeFromInput('!ls')).toBe('bash')
-    })
-
-    it('returns prompt mode for non-bash input', () => {
-      expect(getModeFromInput('')).toBe('prompt')
-      expect(getModeFromInput('hello')).toBe('prompt')
-      expect(getModeFromInput(' !')).toBe('prompt')
-    })
-  })
-
-  describe('getValueFromInput', () => {
-    it('strips the leading ! when entering bash mode', () => {
-      expect(getValueFromInput('!')).toBe('')
-      expect(getValueFromInput('!ls -la')).toBe('ls -la')
-    })
-
-    it('returns input unchanged in prompt mode', () => {
-      expect(getValueFromInput('')).toBe('')
-      expect(getValueFromInput('hello')).toBe('hello')
-    })
-  })
-
-  describe('isInputModeCharacter', () => {
-    it('returns true only for the bare ! character', () => {
-      expect(isInputModeCharacter('!')).toBe(true)
-      expect(isInputModeCharacter('!ls')).toBe(false)
-      expect(isInputModeCharacter('')).toBe(false)
-    })
-  })
-
-  describe('prependModeCharacterToInput', () => {
-    it('prepends ! when mode is bash', () => {
-      expect(prependModeCharacterToInput('ls', 'bash')).toBe('!ls')
-      expect(prependModeCharacterToInput('', 'bash')).toBe('!')
-    })
-
-    it('returns input unchanged in prompt mode', () => {
-      expect(prependModeCharacterToInput('hello', 'prompt')).toBe('hello')
-    })
-  })
-
-  describe('detectModeEntry', () => {
-    // Regression for #662 — typing `!` into empty input must switch to bash
-    // mode AND yield an empty stripped buffer. Before the fix the single-char
-    // path returned without stripping, leaving `!` visible in the buffer.
-    it('strips the mode character when typing ! into empty input', () => {
-      expect(
-        detectModeEntry({ value: '!', prevInputLength: 0, cursorOffset: 0 }),
-      ).toEqual({ mode: 'bash', strippedValue: '' })
-    })
-
-    it('strips the mode character when pasting !cmd into empty input', () => {
-      expect(
-        detectModeEntry({ value: '!ls -la', prevInputLength: 0, cursorOffset: 0 }),
-      ).toEqual({ mode: 'bash', strippedValue: 'ls -la' })
-    })
-
-    it('returns null when the cursor is not at the start', () => {
-      expect(
-        detectModeEntry({ value: '!', prevInputLength: 0, cursorOffset: 1 }),
-      ).toBeNull()
-    })
-
-    it('returns null when the value does not start with !', () => {
-      expect(
-        detectModeEntry({ value: 'hello', prevInputLength: 0, cursorOffset: 0 }),
-      ).toBeNull()
-    })
-
-    it('returns null when typing ! after existing text', () => {
-      // value="ab!" with prevInputLength=2 is a single-char insertion but does
-      // not start with ! — getModeFromInput returns 'prompt'.
-      expect(
-        detectModeEntry({ value: 'ab!', prevInputLength: 2, cursorOffset: 0 }),
-      ).toBeNull()
-    })
-
-    it('returns null when prepending ! to non-empty existing text', () => {
-      // Single-char insertion at start that produces "!ab" from "ab" — value
-      // length is 3, prevInputLength is 2, so isSingleCharInsertion is true
-      // and isMultiCharIntoEmpty is false. We accept the mode change here so
-      // that typing ! at the start of existing text still toggles mode.
-      const result = detectModeEntry({
-        value: '!ab',
-        prevInputLength: 2,
-        cursorOffset: 0,
-      })
-      expect(result).toEqual({ mode: 'bash', strippedValue: 'ab' })
-    })
-  })
-})

src/components/PromptInput/inputModes.ts

@@ -31,30 +31,3 @@ export function getValueFromInput(input: string): string {
 export function isInputModeCharacter(input: string): boolean {
   return input === '!'
 }
-
-export type ModeEntryDecision = {
-  mode: HistoryMode
-  strippedValue: string
-}
-
-/**
- * Decide whether an onChange `value` should switch the input mode (e.g.
- * `prompt` → `bash`) and what the stripped buffer value should be.
- *
- * Returns null when no mode change applies. Returns a decision otherwise so
- * callers run a single update path — no separate single-char vs multi-char
- * branches that can drift apart.
- */
-export function detectModeEntry(args: {
-  value: string
-  prevInputLength: number
-  cursorOffset: number
-}): ModeEntryDecision | null {
-  if (args.cursorOffset !== 0) return null
-  const mode = getModeFromInput(args.value)
-  if (mode === 'prompt') return null
-  const isSingleCharInsertion = args.value.length === args.prevInputLength + 1
-  const isMultiCharIntoEmpty = args.prevInputLength === 0
-  if (!isSingleCharInsertion && !isMultiCharIntoEmpty) return null
-  return { mode, strippedValue: getValueFromInput(args.value) }
-}

src/utils/env.ts

@@ -3,7 +3,11 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { fileSuffixForOauthConfig } from '../constants/oauth.js'
 import { isRunningWithBun } from './bundledMode.js'
-import { getClaudeConfigHomeDir, isEnvTruthy } from './envUtils.js'
+import {
+  getClaudeConfigHomeDir,
+  isEnvTruthy,
+  resolveConfigDirEnv,
+} from './envUtils.js'
 import { findExecutable } from './findExecutable.js'
 import { getFsImplementation } from './fsOperations.js'
 import { which } from './which.js'
@@ -22,7 +26,11 @@ export const getGlobalClaudeFile = memoize((): string => {
   }
 
   const oauthSuffix = fileSuffixForOauthConfig()
-  const configDir = process.env.CLAUDE_CONFIG_DIR || homedir()
+  const configDir =
+    resolveConfigDirEnv({
+      openClaudeConfigDir: process.env.OPENCLAUDE_CONFIG_DIR,
+      legacyConfigDir: process.env.CLAUDE_CONFIG_DIR,
+    }) ?? homedir()
 
   // Default to .openclaude.json. Fall back to .claude.json only if the new
   // file doesn't exist yet and the legacy one does (same migration pattern

src/utils/envUtils.ts

@@ -3,6 +3,39 @@ import { existsSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 
+/**
+ * Resolves the override env value for the config home directory.
+ * `OPENCLAUDE_CONFIG_DIR` is preferred — `CLAUDE_CONFIG_DIR` is the legacy
+ * Anthropic name kept working for backward compatibility. When both are set
+ * and disagree, `OPENCLAUDE_CONFIG_DIR` wins and we warn once so the user
+ * can clean up. Exported for tests.
+ */
+let warnedAboutConflictingConfigDirEnvs = false
+
+export function resolveConfigDirEnv(options?: {
+  openClaudeConfigDir?: string
+  legacyConfigDir?: string
+  warn?: (message: string) => void
+}): string | undefined {
+  const open = options?.openClaudeConfigDir
+  const legacy = options?.legacyConfigDir
+  if (open && legacy && open !== legacy && !warnedAboutConflictingConfigDirEnvs) {
+    warnedAboutConflictingConfigDirEnvs = true
+    options?.warn?.(
+      `Both OPENCLAUDE_CONFIG_DIR and CLAUDE_CONFIG_DIR are set to different values. Using OPENCLAUDE_CONFIG_DIR=${open}; ignoring CLAUDE_CONFIG_DIR=${legacy}.`,
+    )
+  }
+  return open || legacy || undefined
+}
+
+/**
+ * Test-only escape hatch — resets the once-per-process conflict warning so
+ * unit tests can re-trigger it.
+ */
+export function __resetConfigDirEnvWarningForTesting(): void {
+  warnedAboutConflictingConfigDirEnvs = false
+}
+
 export function resolveClaudeConfigHomeDir(options?: {
   configDirEnv?: string
   homeDir?: string
@@ -30,13 +63,21 @@ export function resolveClaudeConfigHomeDir(options?: {
   return openClaudeDir.normalize('NFC')
 }
 
-// Memoized: 150+ callers, many on hot paths. Keyed off CLAUDE_CONFIG_DIR so
+// Memoized: 150+ callers, many on hot paths. Keyed off both override env
-// tests that change the env var get a fresh value without explicit cache.clear.
+// vars so tests that change either get a fresh value without explicit
+// cache.clear.
 export const getClaudeConfigHomeDir = memoize(
   (): string => resolveClaudeConfigHomeDir({
-    configDirEnv: process.env.CLAUDE_CONFIG_DIR,
+    configDirEnv: resolveConfigDirEnv({
+      openClaudeConfigDir: process.env.OPENCLAUDE_CONFIG_DIR,
+      legacyConfigDir: process.env.CLAUDE_CONFIG_DIR,
+      warn: message => {
+        // eslint-disable-next-line no-console
+        console.warn(`[openclaude] ${message}`)
+      },
+    }),
   }),
-  () => process.env.CLAUDE_CONFIG_DIR,
+  () => `${process.env.OPENCLAUDE_CONFIG_DIR ?? ''}|${process.env.CLAUDE_CONFIG_DIR ?? ''}`,
 )
 
 export function getTeamsDir(): string {

src/utils/openclaudePaths.test.ts

@@ -51,7 +51,8 @@ describe('OpenClaude paths', () => {
     ).toBe(join(homedir(), '.claude'))
   })
 
-  test('uses CLAUDE_CONFIG_DIR override when provided', async () => {
+  test('uses CLAUDE_CONFIG_DIR override when provided (legacy)', async () => {
+    delete process.env.OPENCLAUDE_CONFIG_DIR
     process.env.CLAUDE_CONFIG_DIR = '/tmp/custom-openclaude'
     const { getClaudeConfigHomeDir, resolveClaudeConfigHomeDir } =
       await importFreshEnvUtils()
@@ -64,6 +65,83 @@ describe('OpenClaude paths', () => {
     ).toBe('/tmp/custom-openclaude')
   })
 
+  test('OPENCLAUDE_CONFIG_DIR overrides the default (issue #454)', async () => {
+    delete process.env.CLAUDE_CONFIG_DIR
+    process.env.OPENCLAUDE_CONFIG_DIR = '/tmp/oc-config-only'
+    const { getClaudeConfigHomeDir } = await importFreshEnvUtils()
+
+    expect(getClaudeConfigHomeDir()).toBe('/tmp/oc-config-only')
+  })
+
+  test('OPENCLAUDE_CONFIG_DIR wins when both env vars are set with different values', async () => {
+    process.env.OPENCLAUDE_CONFIG_DIR = '/tmp/oc-wins'
+    process.env.CLAUDE_CONFIG_DIR = '/tmp/legacy-loses'
+    const { getClaudeConfigHomeDir } = await importFreshEnvUtils()
+
+    expect(getClaudeConfigHomeDir()).toBe('/tmp/oc-wins')
+  })
+
+  test('CLAUDE_CONFIG_DIR is still honored when OPENCLAUDE_CONFIG_DIR is unset', async () => {
+    delete process.env.OPENCLAUDE_CONFIG_DIR
+    process.env.CLAUDE_CONFIG_DIR = '/tmp/legacy-only'
+    const { getClaudeConfigHomeDir } = await importFreshEnvUtils()
+
+    expect(getClaudeConfigHomeDir()).toBe('/tmp/legacy-only')
+  })
+
+  test('empty OPENCLAUDE_CONFIG_DIR falls through to CLAUDE_CONFIG_DIR', async () => {
+    process.env.OPENCLAUDE_CONFIG_DIR = ''
+    process.env.CLAUDE_CONFIG_DIR = '/tmp/legacy-fallback'
+    const { getClaudeConfigHomeDir } = await importFreshEnvUtils()
+
+    expect(getClaudeConfigHomeDir()).toBe('/tmp/legacy-fallback')
+  })
+
+  test('resolveConfigDirEnv prefers OPENCLAUDE over CLAUDE and warns on conflict', async () => {
+    const { resolveConfigDirEnv, __resetConfigDirEnvWarningForTesting } =
+      await importFreshEnvUtils()
+    __resetConfigDirEnvWarningForTesting()
+
+    const warnings: string[] = []
+    const result = resolveConfigDirEnv({
+      openClaudeConfigDir: '/a',
+      legacyConfigDir: '/b',
+      warn: m => warnings.push(m),
+    })
+
+    expect(result).toBe('/a')
+    expect(warnings.length).toBe(1)
+    expect(warnings[0]).toContain('OPENCLAUDE_CONFIG_DIR=/a')
+    expect(warnings[0]).toContain('CLAUDE_CONFIG_DIR=/b')
+  })
+
+  test('resolveConfigDirEnv does not warn when both env vars agree', async () => {
+    const { resolveConfigDirEnv, __resetConfigDirEnvWarningForTesting } =
+      await importFreshEnvUtils()
+    __resetConfigDirEnvWarningForTesting()
+
+    const warnings: string[] = []
+    const result = resolveConfigDirEnv({
+      openClaudeConfigDir: '/same',
+      legacyConfigDir: '/same',
+      warn: m => warnings.push(m),
+    })
+
+    expect(result).toBe('/same')
+    expect(warnings).toEqual([])
+  })
+
+  test('resolveConfigDirEnv returns undefined when neither env var is set', async () => {
+    const { resolveConfigDirEnv } = await importFreshEnvUtils()
+
+    expect(
+      resolveConfigDirEnv({
+        openClaudeConfigDir: undefined,
+        legacyConfigDir: undefined,
+      }),
+    ).toBeUndefined()
+  })
+
   test('project and local settings paths use .openclaude', async () => {
     const { getRelativeSettingsFilePathForSource } = await importFreshSettings()
 

src/utils/secureStorage/macOsKeychainHelpers.ts

@@ -34,7 +34,8 @@ export function getSecureStorageServiceName(
   serviceSuffix: string = '',
 ): string {
   const configDir = getClaudeConfigHomeDir()
-  const isDefaultDir = !process.env.CLAUDE_CONFIG_DIR
+  const isDefaultDir =
+    !process.env.OPENCLAUDE_CONFIG_DIR && !process.env.CLAUDE_CONFIG_DIR
 
   // Use a hash of the config dir path to create a unique but stable suffix
   // Only add suffix for non-default directories to maintain backwards compatibility

src/utils/swarm/spawnUtils.ts

@@ -117,7 +117,8 @@ const TEAMMATE_ENV_VARS = [
   'MISTRAL_BASE_URL',
   // Custom API endpoint
   'ANTHROPIC_BASE_URL',
-  // Config directory override
+  // Config directory override (preferred name + legacy alias)
+  'OPENCLAUDE_CONFIG_DIR',
   'CLAUDE_CONFIG_DIR',
   // CCR marker — teammates need this for CCR-aware code paths. Auth finds
   // its own way via /home/claude/.claude/remote/.oauth_token regardless;