fix: replace $HOME/.claude/ paths during local install (#820)

The installer only rewrote ~/.claude/ but missed the $HOME/.claude/ variant
used in bash command contexts, causing MODULE_NOT_FOUND errors for local
installs. Centralizes all path replacement into replacePathPatterns() and
applies it consistently across all 5 copy sites.

Author: Ethan Hurst

CHANGELOG.md

@@ -6,6 +6,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Fixed
+- `$HOME/.claude/` paths not replaced during local install, causing `MODULE_NOT_FOUND` on projects outside `$HOME` (#820)
+
 ## [1.22.0] - 2026-02-27
 
 ### Added

bin/install.js

@@ -66,6 +66,21 @@ function getDirName(runtime) {
   return '.claude';
 }
 
+// Centralized path replacement for all install targets.
+// Handles ~/.claude/, $HOME/.claude/, ./.claude/, and runtime-specific variants.
+function replacePathPatterns(content, pathPrefix, runtime) {
+  const dirName = getDirName(runtime);
+  content = content.replace(/~\/\.claude\//g, pathPrefix);
+  content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
+  content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+  if (runtime === 'opencode') {
+    content = content.replace(/~\/\.opencode\//g, pathPrefix);
+  } else if (runtime === 'codex') {
+    content = content.replace(/~\/\.codex\//g, pathPrefix);
+  }
+  return content;
+}
+
 /**
  * Get the config directory path relative to home directory for a runtime
  * Used for templating hooks that use path.join(homeDir, '<configDir>', ...)
@@ -983,12 +998,7 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
       const destPath = path.join(destDir, destName);
 
       let content = fs.readFileSync(srcPath, 'utf8');
-      const globalClaudeRegex = /~\/\.claude\//g;
-      const localClaudeRegex = /\.\/\.claude\//g;
-      const opencodeDirRegex = /~\/\.opencode\//g;
-      content = content.replace(globalClaudeRegex, pathPrefix);
-      content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
-      content = content.replace(opencodeDirRegex, pathPrefix);
+      content = replacePathPatterns(content, pathPrefix, runtime);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeToOpencodeFrontmatter(content);
 
@@ -1042,12 +1052,7 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
       fs.mkdirSync(skillDir, { recursive: true });
 
       let content = fs.readFileSync(srcPath, 'utf8');
-      const globalClaudeRegex = /~\/\.claude\//g;
-      const localClaudeRegex = /\.\/\.claude\//g;
-      const codexDirRegex = /~\/\.codex\//g;
-      content = content.replace(globalClaudeRegex, pathPrefix);
-      content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
-      content = content.replace(codexDirRegex, pathPrefix);
+      content = replacePathPatterns(content, pathPrefix, runtime);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeCommandToCodexSkill(content, skillName);
 
@@ -1069,7 +1074,6 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
 function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false) {
   const isOpencode = runtime === 'opencode';
   const isCodex = runtime === 'codex';
-  const dirName = getDirName(runtime);
 
   // Clean install: remove existing destination to prevent orphaned files
   if (fs.existsSync(destDir)) {
@@ -1086,12 +1090,9 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
     if (entry.isDirectory()) {
       copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand);
     } else if (entry.name.endsWith('.md')) {
-      // Replace ~/.claude/ and ./.claude/ with runtime-appropriate paths
+      // Replace ~/.claude/, $HOME/.claude/, ./.claude/ with runtime-appropriate paths
       let content = fs.readFileSync(srcPath, 'utf8');
-      const globalClaudeRegex = /~\/\.claude\//g;
-      const localClaudeRegex = /\.\/\.claude\//g;
-      content = content.replace(globalClaudeRegex, pathPrefix);
-      content = content.replace(localClaudeRegex, `./${dirName}/`);
+      content = replacePathPatterns(content, pathPrefix, runtime);
       content = processAttribution(content, getCommitAttribution(runtime));
 
       // Convert frontmatter for opencode compatibility
@@ -1929,9 +1930,7 @@ function install(isGlobal, runtime = 'claude') {
     for (const entry of agentEntries) {
       if (entry.isFile() && entry.name.endsWith('.md')) {
         let content = fs.readFileSync(path.join(agentsSrc, entry.name), 'utf8');
-        // Always replace ~/.claude/ as it is the source of truth in the repo
-        const dirRegex = /~\/\.claude\//g;
-        content = content.replace(dirRegex, pathPrefix);
+        content = replacePathPatterns(content, pathPrefix, runtime);
         content = processAttribution(content, getCommitAttribution(runtime));
         // Convert frontmatter for runtime compatibility
         if (isOpencode) {
@@ -2333,6 +2332,7 @@ if (process.env.GSD_TEST_MODE) {
     convertClaudeCommandToCodexSkill,
     GSD_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,
+    replacePathPatterns,
   };
 } else {
 

tests/path-replacement.test.cjs

@@ -0,0 +1,118 @@
+/**
+ * GSD Tests - path-replacement.test.cjs
+ *
+ * Tests for replacePathPatterns() — centralised path replacement
+ * that handles ~/.claude/, $HOME/.claude/, ./.claude/, and
+ * runtime-specific variants during install.
+ */
+
+process.env.GSD_TEST_MODE = '1';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+
+const { replacePathPatterns } = require('../bin/install.js');
+
+// ─── Basic replacements ──────────────────────────────────────────────────────
+
+describe('replacePathPatterns', () => {
+  const globalPrefix = '/Users/x/.claude/';
+
+  test('replaces ~/.claude/ with pathPrefix', () => {
+    const input = 'Read ~/.claude/commands/foo.md';
+    const result = replacePathPatterns(input, globalPrefix, 'claude');
+    assert.strictEqual(result, 'Read /Users/x/.claude/commands/foo.md');
+  });
+
+  test('replaces $HOME/.claude/ with pathPrefix (bug fix)', () => {
+    const input = 'cat $HOME/.claude/commands/foo.md';
+    const result = replacePathPatterns(input, globalPrefix, 'claude');
+    assert.strictEqual(result, 'cat /Users/x/.claude/commands/foo.md');
+  });
+
+  test('replaces ./.claude/ with local dir for claude runtime', () => {
+    const input = 'Read ./.claude/commands/foo.md';
+    const result = replacePathPatterns(input, globalPrefix, 'claude');
+    assert.strictEqual(result, 'Read ./.claude/commands/foo.md');
+  });
+
+  test('replaces ./.claude/ with ./.opencode/ for opencode runtime', () => {
+    const input = 'Read ./.claude/commands/foo.md';
+    const result = replacePathPatterns(input, '/home/user/.config/opencode/', 'opencode');
+    assert.strictEqual(result, 'Read ./.opencode/commands/foo.md');
+  });
+
+  test('replaces ./.claude/ with ./.codex/ for codex runtime', () => {
+    const input = 'Read ./.claude/commands/foo.md';
+    const result = replacePathPatterns(input, '/home/user/.codex/', 'codex');
+    assert.strictEqual(result, 'Read ./.codex/commands/foo.md');
+  });
+
+  test('replaces ./.claude/ with ./.kimi/ for kimi runtime', () => {
+    const input = 'Read ./.claude/commands/foo.md';
+    const result = replacePathPatterns(input, '/home/user/.kimi/', 'kimi');
+    assert.strictEqual(result, 'Read ./.kimi/commands/foo.md');
+  });
+
+  // ─── Runtime-specific variants ─────────────────────────────────────────────
+
+  test('replaces ~/.opencode/ only when runtime is opencode', () => {
+    const prefix = '/home/user/.config/opencode/';
+    assert.strictEqual(
+      replacePathPatterns('path ~/.opencode/foo', prefix, 'opencode'),
+      'path /home/user/.config/opencode/foo'
+    );
+    // Should NOT replace when runtime is claude
+    assert.strictEqual(
+      replacePathPatterns('path ~/.opencode/foo', globalPrefix, 'claude'),
+      'path ~/.opencode/foo'
+    );
+  });
+
+  test('replaces ~/.codex/ only when runtime is codex', () => {
+    const prefix = '/home/user/.codex/';
+    assert.strictEqual(
+      replacePathPatterns('path ~/.codex/foo', prefix, 'codex'),
+      'path /home/user/.codex/foo'
+    );
+    // Should NOT replace when runtime is claude
+    assert.strictEqual(
+      replacePathPatterns('path ~/.codex/foo', globalPrefix, 'claude'),
+      'path ~/.codex/foo'
+    );
+  });
+
+  // ─── Pass-through ──────────────────────────────────────────────────────────
+
+  test('non-matching content passes through unchanged', () => {
+    const input = 'No paths here, just text.';
+    assert.strictEqual(
+      replacePathPatterns(input, globalPrefix, 'claude'),
+      input
+    );
+  });
+
+  // ─── Multiple patterns in one string ───────────────────────────────────────
+
+  test('replaces all pattern types in mixed content', () => {
+    const input = [
+      'global: ~/.claude/agents/foo.md',
+      'env: $HOME/.claude/agents/bar.md',
+      'local: ./.claude/commands/baz.md',
+    ].join('\n');
+
+    const result = replacePathPatterns(input, globalPrefix, 'claude');
+
+    assert.strictEqual(result, [
+      'global: /Users/x/.claude/agents/foo.md',
+      'env: /Users/x/.claude/agents/bar.md',
+      'local: ./.claude/commands/baz.md',
+    ].join('\n'));
+  });
+
+  test('replaces multiple occurrences of the same pattern', () => {
+    const input = '$HOME/.claude/a and $HOME/.claude/b';
+    const result = replacePathPatterns(input, globalPrefix, 'claude');
+    assert.strictEqual(result, '/Users/x/.claude/a and /Users/x/.claude/b');
+  });
+});