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.

bun.lock

@@ -28,7 +28,6 @@
         "@opentelemetry/sdk-trace-base": "2.6.1",
         "@opentelemetry/sdk-trace-node": "2.6.1",
         "@opentelemetry/semantic-conventions": "1.40.0",
-        "@vscode/ripgrep": "^1.17.1",
         "ajv": "8.18.0",
         "auto-bind": "5.0.1",
         "axios": "1.15.0",
@@ -462,8 +461,6 @@
 
     "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
-    "@vscode/ripgrep": ["@vscode/ripgrep@1.17.1", "", { "dependencies": { "https-proxy-agent": "^7.0.2", "proxy-from-env": "^1.1.0", "yauzl": "^2.9.2" } }, "sha512-xTs7DGyAO3IsJYOCTBP8LnTvPiYVKEuyv8s0xyJDBXfs8rhBfqnZPvb6xDT+RnwWzcXqW27xLS/aGrkjX7lNWw=="],
-
     "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
 
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
@@ -494,8 +491,6 @@
 
     "bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="],
 
-    "buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
-
     "buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
 
     "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
@@ -614,8 +609,6 @@
 
     "fast-xml-parser": ["fast-xml-parser@5.5.8", "", { "dependencies": { "fast-xml-builder": "^1.1.4", "path-expression-matcher": "^1.2.0", "strnum": "^2.2.0" }, "bin": { "fxparser": "src/cli/cli.js" } }, "sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ=="],
 
-    "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
-
     "fflate": ["fflate@0.8.2", "", {}, "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A=="],
 
     "figures": ["figures@6.1.0", "", { "dependencies": { "is-unicode-supported": "^2.0.0" } }, "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg=="],
@@ -794,8 +787,6 @@
 
     "path-to-regexp": ["path-to-regexp@8.4.1", "", {}, "sha512-fvU78fIjZ+SBM9YwCknCvKOUKkLVqtWDVctl0s7xIqfmfb38t2TT4ZU2gHm+Z8xGwgW+QWEU3oQSAzIbo89Ggw=="],
 
-    "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
-
     "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
 
     "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
@@ -810,7 +801,7 @@
 
     "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
 
-    "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
+    "proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
 
     "qrcode": ["qrcode@1.5.4", "", { "dependencies": { "dijkstrajs": "^1.0.1", "pngjs": "^5.0.0", "yargs": "^15.3.1" }, "bin": { "qrcode": "bin/qrcode" } }, "sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg=="],
 
@@ -962,8 +953,6 @@
 
     "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
 
-    "yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
-
     "yoctocolors": ["yoctocolors@2.1.2", "", {}, "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug=="],
 
     "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
@@ -1380,8 +1369,6 @@
 
     "@smithy/uuid/tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
-    "axios/proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
-
     "cli-highlight/chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="],
 
     "cli-highlight/yargs": ["yargs@16.2.0", "", { "dependencies": { "cliui": "^7.0.2", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.0", "y18n": "^5.0.5", "yargs-parser": "^20.2.2" } }, "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw=="],
@@ -1442,8 +1429,6 @@
 
     "@aws-sdk/nested-clients/@smithy/util-base64/@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
 
-    "@mendable/firecrawl-js/axios/proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
-
     "@opentelemetry/exporter-trace-otlp-grpc/@opentelemetry/core/@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.28.0", "", {}, "sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA=="],
 
     "@opentelemetry/exporter-trace-otlp-grpc/@opentelemetry/otlp-transformer/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.57.2", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-uIX52NnTM0iBh84MShlpouI7UKqkZ7MrUszTmaypHBu4r7NofznSnQRfJ+uUeDtQDj6w8eFGg5KBLDAwAPz1+A=="],
@@ -1524,8 +1509,6 @@
 
     "cliui/wrap-ansi/ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
 
-    "firecrawl/axios/proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
-
     "form-data/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
 
     "qrcode/yargs/cliui": ["cliui@6.0.0", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.0", "wrap-ansi": "^6.2.0" } }, "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ=="],

package.json

@@ -74,7 +74,6 @@
     "@opentelemetry/sdk-trace-base": "2.6.1",
     "@opentelemetry/sdk-trace-node": "2.6.1",
     "@opentelemetry/semantic-conventions": "1.40.0",
-    "@vscode/ripgrep": "^1.17.1",
     "ajv": "8.18.0",
     "auto-bind": "5.0.1",
     "axios": "1.15.0",

scripts/build.ts

@@ -472,11 +472,6 @@ ${exports}
     '@aws-sdk/credential-providers',
     '@azure/identity',
     'google-auth-library',
-    // @vscode/ripgrep ships a platform-specific binary alongside its
-    // index.js and resolves the path via __dirname at runtime. Bundling
-    // would freeze the build host's absolute path into dist/cli.mjs, so we
-    // keep it external and rely on the npm package being installed.
-    '@vscode/ripgrep',
   ],
 })
 

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/ripgrep.test.ts

@@ -5,15 +5,16 @@ import { resolveRipgrepConfig, wrapRipgrepUnavailableError } from './ripgrep.js'
 
 const MOCK_BUILTIN_PATH = path.normalize(
   process.platform === 'win32'
-    ? `node_modules/@vscode/ripgrep/bin/rg.exe`
+    ? `vendor/ripgrep/${process.arch}-win32/rg.exe`
-    : `node_modules/@vscode/ripgrep/bin/rg`,
+    : `vendor/ripgrep/${process.arch}-${process.platform}/rg`,
 )
 
-test('falls back to system rg when @vscode/ripgrep cannot be resolved', () => {
+test('ripgrepCommand falls back to system rg when builtin binary is missing', () => {
   const config = resolveRipgrepConfig({
     userWantsSystemRipgrep: false,
     bundledMode: false,
-    builtinCommand: null,
+    builtinCommand: MOCK_BUILTIN_PATH,
+    builtinExists: false,
     systemExecutablePath: '/usr/bin/rg',
     processExecPath: '/fake/bun',
   })
@@ -25,11 +26,12 @@ test('falls back to system rg when @vscode/ripgrep cannot be resolved', () => {
   })
 })
 
-test('uses builtin @vscode/ripgrep path when the package resolves', () => {
+test('ripgrepCommand keeps builtin mode when bundled binary exists', () => {
   const config = resolveRipgrepConfig({
     userWantsSystemRipgrep: false,
     bundledMode: false,
     builtinCommand: MOCK_BUILTIN_PATH,
+    builtinExists: true,
     systemExecutablePath: '/usr/bin/rg',
     processExecPath: '/fake/bun',
   })
@@ -41,59 +43,10 @@ test('uses builtin @vscode/ripgrep path when the package resolves', () => {
   })
 })
 
-test('honors USE_BUILTIN_RIPGREP=0 by selecting system rg even when builtin is available', () => {
-  const config = resolveRipgrepConfig({
-    userWantsSystemRipgrep: true,
-    bundledMode: false,
-    builtinCommand: MOCK_BUILTIN_PATH,
-    systemExecutablePath: '/usr/bin/rg',
-    processExecPath: '/fake/bun',
-  })
-
-  expect(config).toMatchObject({
-    mode: 'system',
-    command: 'rg',
-    args: [],
-  })
-})
-
-test('keeps embedded mode for Bun-compiled standalone executables', () => {
-  const config = resolveRipgrepConfig({
-    userWantsSystemRipgrep: false,
-    bundledMode: true,
-    builtinCommand: null,
-    systemExecutablePath: '/usr/bin/rg',
-    processExecPath: '/opt/openclaude/bin/openclaude',
-  })
-
-  expect(config).toMatchObject({
-    mode: 'embedded',
-    command: '/opt/openclaude/bin/openclaude',
-    args: ['--no-config'],
-    argv0: 'rg',
-  })
-})
-
-test('falls through to system rg as a last resort even when not on PATH', () => {
-  const config = resolveRipgrepConfig({
-    userWantsSystemRipgrep: false,
-    bundledMode: false,
-    builtinCommand: null,
-    systemExecutablePath: 'rg',
-    processExecPath: '/fake/bun',
-  })
-
-  expect(config).toMatchObject({
-    mode: 'system',
-    command: 'rg',
-    args: [],
-  })
-})
-
 test('wrapRipgrepUnavailableError explains missing packaged fallback', () => {
   const error = wrapRipgrepUnavailableError(
     { code: 'ENOENT', message: 'spawn rg ENOENT' },
-    { mode: 'builtin', command: 'C:\\fake\\node_modules\\@vscode\\ripgrep\\bin\\rg.exe', args: [] },
+    { mode: 'builtin', command: 'C:\\fake\\vendor\\ripgrep\\rg.exe', args: [] },
     'win32',
   )
 

src/utils/ripgrep.ts

@@ -5,6 +5,7 @@ import memoize from 'lodash-es/memoize.js'
 import { homedir } from 'os'
 import * as path from 'path'
 import { logEvent } from 'src/services/analytics/index.js'
+import { fileURLToPath } from 'url'
 import { isInBundledMode } from './bundledMode.js'
 import { logForDebugging } from './debug.js'
 import { isEnvDefinedFalsy } from './envUtils.js'
@@ -14,6 +15,13 @@ import { logError } from './log.js'
 import { getPlatform } from './platform.js'
 import { countCharInString } from './stringUtils.js'
 
+const __filename = fileURLToPath(import.meta.url)
+// we use node:path.join instead of node:url.resolve because the former doesn't encode spaces
+const __dirname = path.join(
+  __filename,
+  process.env.NODE_ENV === 'test' ? '../../../' : '../',
+)
+
 type RipgrepConfig = {
   mode: 'system' | 'builtin' | 'embedded'
   command: string
@@ -27,31 +35,11 @@ function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error
 }
 
-/**
- * Returns the ripgrep binary path provided by the @vscode/ripgrep package.
- * The package downloads a platform/arch-specific binary at npm install time
- * (cached under the package's bin/ directory). Returns null when the package
- * cannot be resolved — for example when running as a Bun-compiled standalone
- * executable that doesn't ship node_modules.
- */
-function resolveBuiltinRgPath(): string | null {
-  try {
-    // Lazy require so the resolution failure path stays graceful at import
-    // time. The package only exports `rgPath`, so we do not need the rest.
-    const mod = require('@vscode/ripgrep') as { rgPath?: string }
-    if (mod.rgPath && existsSync(mod.rgPath)) {
-      return mod.rgPath
-    }
-  } catch {
-    // Falls through to null — caller decides the fallback.
-  }
-  return null
-}
-
 type ResolveRipgrepConfigArgs = {
   userWantsSystemRipgrep: boolean
   bundledMode: boolean
-  builtinCommand: string | null
+  builtinCommand: string
+  builtinExists: boolean
   systemExecutablePath: string
   processExecPath?: string
 }
@@ -60,6 +48,7 @@ export function resolveRipgrepConfig({
   userWantsSystemRipgrep,
   bundledMode,
   builtinCommand,
+  builtinExists,
   systemExecutablePath,
   processExecPath = process.execPath,
 }: ResolveRipgrepConfigArgs): RipgrepConfig {
@@ -77,7 +66,7 @@ export function resolveRipgrepConfig({
     }
   }
 
-  if (builtinCommand) {
+  if (builtinExists) {
     return { mode: 'builtin', command: builtinCommand, args: [] }
   }
 
@@ -85,9 +74,7 @@ export function resolveRipgrepConfig({
     return { mode: 'system', command: 'rg', args: [] }
   }
 
-  // Last resort — leaves error reporting to the executor when no binary
+  return { mode: 'builtin', command: builtinCommand, args: [] }
-  // can be located. wrapRipgrepUnavailableError() surfaces an install hint.
-  return { mode: 'system', command: 'rg', args: [] }
 }
 
 const getRipgrepConfig = memoize((): RipgrepConfig => {
@@ -95,13 +82,19 @@ const getRipgrepConfig = memoize((): RipgrepConfig => {
     process.env.USE_BUILTIN_RIPGREP,
   )
   const bundledMode = isInBundledMode()
-  const builtinCommand = resolveBuiltinRgPath()
+  const rgRoot = path.resolve(__dirname, 'vendor', 'ripgrep')
+  const builtinCommand =
+    process.platform === 'win32'
+      ? path.resolve(rgRoot, `${process.arch}-win32`, 'rg.exe')
+      : path.resolve(rgRoot, `${process.arch}-${process.platform}`, 'rg')
+  const builtinExists = existsSync(builtinCommand)
   const { cmd: systemExecutablePath } = findExecutable('rg', [])
 
   return resolveRipgrepConfig({
     userWantsSystemRipgrep,
     bundledMode,
     builtinCommand,
+    builtinExists,
     systemExecutablePath,
   })
 })

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;