# How Path Rewriting Handles Claude Configuration Directories in Plugin Converters

> Learn how path rewriting transforms Claude configuration directories for seamless plugin migration across AI coding platforms like OpenCode, Gemini, and Cursor. Our regex replacements ensure compatibility.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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:

```typescript
// 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:

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

```

This ensures that paths like [`.claude/plugin-config.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude/plugin-config.json) become [`.opencode/plugin-config.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-opencode.ts) (lines 47-50) |
| Claude → Gemini | `.gemini/` | `~/.gemini/` | [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-gemini.ts) (lines 96-99) |
| Claude → Cursor | `.cursor/` | `~/.cursor/` | [`src/converters/claude-to-cursor.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-cursor.ts) (lines 102-103) |
| Claude → Codex | `.codex/` | `~/.codex/` | [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) (lines 126-127) |
| Claude → Pi | `.pi/` | `~/.pi/` | [`src/converters/claude-to-pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-pi.ts) (lines 84-86) |
| Claude → Droid | `.droid/` | `~/.droid/` | [`src/converters/claude-to-droid.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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:

```typescript
// 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.