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. The coding agent (Claude Code, Codex, or Antigravity) 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 session data using a two-pass approach. The two-pass concept — home swap, then cwd anchoring — is the same for every agent; only the mechanism differs per agent (see Text vs binary rewriting below):

• Claude Code and Codex store their transcripts (and memory) as text, so paths are rewritten with plain text replacement over JSONL and Markdown.
• Antigravity stores its conversation as protobuf BLOBs inside a SQLite database, so paths are rewritten with length-prefix-aware binary rewriting.

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.

Text vs binary rewriting

The same two-pass logic (home swap, then cwd anchoring) applies to every agent, but how the bytes are edited depends on how the agent stores its session:

• Claude Code and Codex — text replacement. Their transcripts are JSONL and their memory is Markdown, so rewriting is a plain string replacement (the /Users/alice --> /home/bob examples below).
• Antigravity — binary, length-prefix-aware protobuf rewriting. Antigravity’s conversation lives in a SQLite database whose payloads are protobuf BLOBs, so the paths are embedded inside the binary wire format. CodeTeleport walks the protobuf wire format and recomputes every length-delimited field prefix, because changing a path’s byte length would otherwise corrupt the message framing. This keeps the BLOBs valid after the rewrite — the same home-then-cwd passes apply, just over binary data instead of text.

Note

Reading and rewriting Antigravity’s (and Codex’s) SQLite session state uses the built-in node:sqlite module, so the CLI requires Node.js >= 22.5.0. node:sqlite is cross-platform, so this works on Windows as well as macOS and Linux. Path rewriting and home detection are cross-OS — see Cross-OS rewriting below.

Cross-OS rewriting

The two-pass rewrite works across operating systems, not just usernames. A session pushed from Windows restores correctly on macOS or Linux, and a session pushed from macOS or Linux restores correctly on Windows. CodeTeleport detects each path’s style from the string itself — not from the host OS — because a bundle’s source paths come from whatever machine pushed it.

Cross-OS rewriting handles:

• Windows drive letters — a source root like C:\Users\alice is recognized and relocated, drive-letter and all.
• Separator translation — backslash (\), forward slash (/), and JSON-escaped backslash (\\) are all recognized as separators on input. On output, each relocated path’s separators are re-emitted in the target’s native style (backslashes for a Windows target, forward slashes for a Unix target), and re-escaped for JSONL so the transcript stays valid JSON.
• Case-insensitive drive letters — the drive-letter component (e.g. C: vs c:) matches either case, since Windows drive letters are case-insensitive. The rest of the path is matched exactly.
• Per-OS home detection — home directories are detected by shape: C:\Users\alice (Windows), /Users/alice (macOS), /home/alice (Linux), and /root (root user). See Home directory detection below.

Windows source  -->  macOS target
C:\Users\alice\projects\billing-api  -->  /Users/bob/work/billing

macOS source  -->  Windows target
/Users/alice/projects/billing-api  -->  C:\Users\bob\work\billing

Beyond the conversation logs

The same two-pass rewriting is not limited to the main transcript. It reaches into the agent-specific session stores too, and exactly which stores depends on the bundle’s recorded agent.

Claude Code

~/.claude/projects/<encoded-cwd>/<id>.jsonl is the primary example. On pull, rewriting also applies to:

• The main transcript and subagent JSONLs — every absolute path inside the conversation and its subagent logs.
• Project memory — the contents of restored memory .md files are rewritten so any paths they reference point at the new machine.
• Extra working/temp files — the restore target path for each included extra file is rewritten before the file is written, so it lands in the right place on the target machine.

Codex

Codex stores its transcript at ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl plus a thread-inventory row in ~/.codex/state_5.sqlite. On pull, rewriting applies to:

• The rollout JSONL transcript — plain text replacement, the same as Claude Code.
• The thread-inventory row — the string fields of the matching row in ~/.codex/state_5.sqlite are rewritten so codex resume <id> finds the session at its new location.

Note

On pull, Codex writes the rollout transcript and upserts the thread-inventory row in ~/.codex/state_5.sqlite so codex resume <id> finds the session. If state_5.sqlite does not exist yet on the target machine, the transcript is still restored but the thread row is not — run Codex once, then re-pull.

Antigravity

Antigravity’s conversation lives entirely in ~/.gemini/antigravity-cli/conversations/<id>.db (the SQLite DB is the session), with supporting text under ~/.gemini/antigravity-cli/brain/<id>/. On pull, rewriting applies to:

• The conversation DB — the absolute paths embedded inside protobuf BLOBs across the whole database are rewritten with the length-prefix-aware binary rewriting described above.
• The brain text files — transcripts, artifacts, and scratch files under ~/.gemini/antigravity-cli/brain/<id>/ are rewritten as plain text.

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. Detection is by path shape, not by host OS, so a Windows path is detected correctly even when restoring on macOS or Linux (and vice versa):

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

On Windows, the config and agent directories live under the user profile — for example C:\Users\alice\.codeteleport\config.json — while on macOS and Linux they live under $HOME (~/.codeteleport/config.json).

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. The coding agent can resume the conversation and all file references work.

The resume command differs per agent — Claude Code claude --resume <id>, Codex codex resume <id>, Antigravity agy --conversation <id> — and pull derives the correct one from the bundle’s own recorded agent, not the puller’s local config. A bundle made by one agent restores and resumes correctly even on a machine configured for a different agent.

Related

• Pull a session — CLI reference with --target-dir examples
• Sessions — what gets bundled and the on-disk layout for each agent (Claude Code, Codex, Antigravity)
• Configure the agent — choose which agent is bundled locally (pull still uses the bundle’s own recorded agent)
• Setup — interactive agent selection