Path Rewriting

The problem

AI coding sessions are full of absolute paths. Every file read, edit, and tool call references the exact location on disk:

/Users/alice/projects/billing-api/src/routes/invoices.ts

If you pull that session onto Bob’s Linux machine, those paths do not exist. Claude will try to read /Users/alice/... and fail. The conversation becomes unusable.

The solution: two-pass rewriting

When you pull a session, CodeTeleport rewrites every path inside the JSONL conversation logs using a two-pass approach:

Pass 1: User directory swap

Replace the source user’s home directory with the target user’s home directory.

/Users/alice  -->  /home/bob

Every occurrence of /Users/alice in the session data becomes /home/bob. This handles the most common case: different usernames or different operating systems.

Pass 2: Project path anchoring

After the user directory swap, the source project path may still not match the target. For example, Alice had the project at ~/projects/billing-api but Bob cloned it to ~/work/billing:

/home/bob/projects/billing-api  -->  /home/bob/work/billing

This second pass catches any remaining mismatches between the rewritten source path and the actual target directory.

Note

Pass 2 only runs if the paths differ after pass 1. If you happen to have the same directory structure as the source machine, no anchoring is needed.

Using --target-dir

By default, CodeTeleport only performs pass 1 (user directory swap). If your project lives at a different path, use --target-dir to tell CodeTeleport where it is:

codeteleport pull c3a05473 --target-dir /home/bob/work/billing

Or via MCP:

Pull session c3a05473 to /home/bob/work/billing.

This triggers both passes, ensuring all paths in the session point to the correct location.

Home directory detection

CodeTeleport auto-detects the user’s home directory from the stored source path using these patterns:

Pattern	Example	Detected home
macOS	/Users/alice/projects/app	/Users/alice
Linux	/home/bob/work/app	/home/bob
Root user	/root/app	/root

If the path does not match any of these patterns, CodeTeleport will raise an error and ask you to specify the target directory explicitly.

Before and after

Here is a concrete example. Alice pushes a session from her laptop:

Source machine (Alice’s laptop)

User dir:    /Users/alice
Project dir: /Users/alice/projects/billing-api

Target machine (Bob’s Ubuntu desktop)

User dir:    /home/bob
Project dir: /home/bob/work/billing

Bob pulls with --target-dir /home/bob/work/billing. Here is what happens to a path inside the session:

Step	Path
Original	/Users/alice/projects/billing-api/src/routes/invoices.ts
After pass 1	/home/bob/projects/billing-api/src/routes/invoices.ts
After pass 2	/home/bob/work/billing/src/routes/invoices.ts

The final path points to the correct file on Bob’s machine. Claude can resume the conversation and all file references work.

Related

• Pull a session — CLI reference with --target-dir examples
• Sessions — what gets bundled and how session data is structured