How Path Rewriting Handles Claude Configuration Directories in Plugin Converters

Path rewriting automatically transforms Claude-specific configuration directory references into target-platform equivalents using regex-based replacements in converter modules, ensuring seamless plugin migration across OpenCode, Gemini, Cursor, and other AI coding platforms.

When converting AI coding plugins from Claude to alternative platforms, path rewriting ensures that hard-coded references to Claude configuration directories remain functional in the new environment. In the EveryInc/compound-engineering-plugin repository, dedicated converter modules handle this transformation through systematic string replacement patterns that map Claude-specific paths to their target-platform equivalents.

The Core Path Rewriting Logic

The central mechanism for handling Claude configuration directories resides in the rewriteClaudePaths function. This utility performs two distinct regex replacements to handle both global user configuration and plugin-local settings.

Global Configuration Paths (~/.claude/)

Claude stores user-wide settings in the ~/.claude/ directory. When converting to OpenCode, the rewriter targets this pattern specifically:

// From src/converters/claude-to-opencode.ts
function rewriteClaudePaths(body: string): string {
  return body
    .replace(/~\/\.claude\//g, "~/.config/opencode/")
    .replace(/\.claude\//g, ".opencode/")
}

This transforms absolute paths like ~/.claude/settings.json into ~/.config/opencode/settings.json, aligning with OpenCode's XDG-compliant configuration structure.

Plugin-Relative Paths (.claude/)

Plugins often reference local configuration stored in .claude/ directories relative to the plugin root. The second regex handles these relative references:

.replace(/\.claude\//g, ".opencode/")

This ensures that paths like .claude/plugin-config.json become .opencode/plugin-config.json, maintaining the plugin's internal structure while adopting the target platform's naming convention.

How Each Target Converter Handles Path Rewriting

The compound-engineering-plugin implements this path rewriting pattern across multiple target converters, each adapting the replacement strings to match their respective platform conventions.

Converter	Target Suffix	Global Path Replacement	Code Location
Claude → OpenCode	.opencode/	~/.config/opencode/	src/converters/claude-to-opencode.ts (lines 47-50)
Claude → Gemini	.gemini/	~/.gemini/	src/converters/claude-to-gemini.ts (lines 96-99)
Claude → Cursor	.cursor/	~/.cursor/	src/converters/claude-to-cursor.ts (lines 102-103)
Claude → Codex	.codex/	~/.codex/	src/converters/claude-to-codex.ts (lines 126-127)
Claude → Pi	.pi/	~/.pi/	src/converters/claude-to-pi.ts (lines 84-86)
Claude → Droid	.droid/	~/.droid/	src/converters/claude-to-droid.ts (lines 84-86)

Each implementation follows the identical two-step regex approach, ensuring consistent behavior across all conversion targets. For example, the Gemini converter applies:

// From src/converters/claude-to-gemini.ts
return body
  .replace(/~\/\.claude\//g, "~/.gemini/")
  .replace(/\.claude\//g, ".gemini/")

Why Path Rewriting Matters for Configuration Directories

Path rewriting serves a critical function in maintaining plugin functionality across different AI coding platforms. Without these transformations, hard-coded paths would break when plugins migrate from Claude to alternative environments.

User-Wide Configuration Preservation

The ~/.claude/ directory contains global settings such as settings.json and authentication credentials. When the converter transforms these paths to ~/.config/opencode/ (or the target-specific equivalent), it ensures that the converted plugin references the correct location for user preferences in the new environment. Without this rewrite, the plugin would attempt to access non-existent Claude paths on a system running only OpenCode or Gemini.

Plugin-Relative Configuration Integrity

Local configuration files stored in .claude/ directories (such as .claude/plugin.json) contain plugin-specific metadata and settings. The path rewriter updates these to .opencode/, .gemini/, or other target-specific directories, preserving the plugin's internal logic while adapting to the target platform's expected directory structure. This maintains the relationship between the plugin code and its associated configuration assets.

Testing Path Rewriting Logic

The compound-engineering-plugin includes comprehensive test coverage to verify that path rewriting correctly handles Claude configuration directories across all target converters. Unit tests located in the tests/ directory validate that no ".claude/" or "~/.claude/" substrings remain after conversion.

For the OpenCode converter specifically, tests/converter.test.ts (lines 217-218) contains assertions that verify the transformation of both global and relative paths. These tests ensure that edge cases—such as multiple path references within a single file or paths appearing in different string contexts—are handled correctly by the regex-based replacement logic.

Summary

• Path rewriting in the compound-engineering-plugin uses regex-based replacements to transform Claude-specific configuration directories into target-platform equivalents.
• The rewriteClaudePaths function in src/converters/claude-to-opencode.ts handles two patterns: ~/.claude/ (global config) and .claude/ (plugin-relative).
• Six target converters implement identical logic with platform-specific replacements: OpenCode, Gemini, Cursor, Codex, Pi, and Droid.
• This transformation ensures that user-wide settings and plugin-local configuration files remain accessible after conversion to different AI coding platforms.
• Comprehensive unit tests in tests/converter.test.ts verify that all Claude path references are eliminated during the conversion process.

Frequently Asked Questions

What specific paths does the path rewriter target in Claude configuration directories?

The path rewriter targets two specific patterns: absolute paths referencing the user's home directory (~/.claude/) and relative paths from the plugin root (.claude/). The first pattern handles global configuration files like settings.json, while the second manages plugin-specific assets stored within the project directory.

How does the OpenCode converter differ from other target converters in path handling?

The OpenCode converter differs from other targets by using ~/.config/opencode/ for global configuration paths instead of ~/.opencode/. This follows the XDG Base Directory Specification, whereas converters for Gemini, Cursor, Codex, Pi, and Droid use the simpler ~/.<target>/ pattern for their global configuration directories.

Where can I find the implementation of path rewriting for the Cursor target?

The Cursor target's path rewriting implementation resides in src/converters/claude-to-cursor.ts at lines 102-103. This file contains the regex-based replacement logic that substitutes ~/.claude/ with ~/.cursor/ and .claude/ with .cursor/ to ensure configuration references remain valid in the Cursor environment.

How is path rewriting tested in the compound-engineering-plugin?

Path rewriting is tested through unit tests located in the tests/ directory, specifically in files like tests/converter.test.ts. These tests verify that both global (~/.claude/) and relative (.claude/) path patterns are completely replaced with target-specific equivalents, ensuring no Claude-specific path references remain in the converted output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}