ThreadRelink for VS Code

简体中文完整指南

Keep local Codex conversations connected to a project after its folder is renamed or moved.

ThreadRelink stores a stable local project UUID and uses it to resume the original Codex thread at the project's current path. It is local-only, has no telemetry, and never modifies Codex transcripts.

All ThreadRelink actions are available from the sidebar, context menus, and the VS Code Command Palette. It does not provide a separate ThreadRelink CLI.

How it works

ThreadRelink does not move or rewrite conversations. It builds a small local index around metadata provided by the installed Codex app-server:

Set up project
      ↓
Stable project UUID
      ↓
Read local Codex metadata
      ↓
Conservative matching
      ↓
Remember old and current paths
      ↓
Resume the original thread at the resolved new path

Stable project identity

Selecting Set Up This Project creates a random UUID. Git projects store it as threadrelink.projectId in local .git/config; standalone directories use .threadrelink/project.json. Neither value is committed or uploaded. A nested workspace always asks whether its boundary is the current directory or the parent Git repository.

Because the identity moves with the folder, a new absolute path can still be recognized as the same project. ThreadRelink records both old and current paths as aliases and produces a one-time recovery report when it first observes the new location.

Local metadata and conservative matching

After consent and explicit project setup, ThreadRelink starts codex app-server over local standard input/output and requests active and archived conversation listings. It keeps thread ID, title/preview, timestamps, recorded cwd, archive state, Codex/model information, and available Git remote/commit metadata. It does not request full message bodies or parse transcript files.

Conflicting Git remotes prevent broad parent repositories from claiming unrelated conversations.

Safe recovery at the new path

ThreadRelink stores project records, path aliases, metadata snapshots, links, and project-scoped ignored matches in ~/.threadrelink/registry.json. It never writes to ~/.codex.

For a conversation that originally ran in /old/project/packages/api, ThreadRelink stores packages/api relative to the project root and resolves it under the new root before resuming. The resolved path must exist, be a directory, and stay inside the project even after following symlinks. Otherwise, the extension warns and falls back to the project root.

The extension then opens an integrated terminal with:

codex resume --cd <resolved-project-path> <thread-id>

Removing a thread creates an ignored match for only that project. Moving it creates an explicit link to the target project and prevents the old project from claiming it again. Restoring it clears the ignored match.

Installation

Install ThreadRelink from the VS Code Marketplace, or run:

code --install-extension ascendho.threadrelink

VS Code automatically installs Marketplace updates when extension auto-update is enabled. A manually installed VSIX does not receive automatic updates by default.

Quick start

1. Open the original project and select Set Up This Project.
2. Allow the metadata-only scan when prompted.
3. Finish the active Codex session and close its terminal.
4. Rename or move the folder, then open the new path in VS Code.
5. Expand Codex Conversations and select the continue icon beside the original conversation.

ThreadRelink opens:

codex resume --cd <current-project-path> <thread-id>

When the original conversation started in a project subdirectory, ThreadRelink resumes from the corresponding subdirectory at the new location. Missing or unsafe subdirectories fall back to the project root with a warning.

Recovery tools

• Find Old Conversations shows suggested or unrelated local metadata only when requested.
• Review Ignored Conversations restores a conversation previously removed from this project.
• Right-click a linked conversation to remove and ignore it, or move it to another registered project.
• A newly detected project location produces a one-time recovery report in the ThreadRelink output.
• Relink Previous Project Path associates an old absolute path when the project was renamed before setup.
• Forget Project removes only ThreadRelink identity and link records after confirmation. Codex conversations are never deleted.
• Run Diagnostics checks Node.js, Git, Codex app-server access, project identity, and the local registry.

An unconfigured project never displays all global conversations. A nested folder also never inherits a parent Git project without an explicit choice.

Local data and privacy

No metadata scan occurs until the project is explicitly set up and consent is granted. Registry version 1 migrates automatically to version 2 on the next update. Downgrading to ThreadRelink 0.4 afterward is not recommended.

ThreadRelink is an independent project and is not an official OpenAI Codex extension.