ChatAnchor

中文：README.md

This extension grew out of the problem discussed in official Codex issue 26836: existing threads may no longer be automatically reattached after a project directory is renamed or moved. ChatAnchor gives each project a path-independent local identity and uses signals such as Git remotes, commits, and previous paths to recognize the project at its new location and reconnect its threads. We also documented this approach and shared it with OpenAI in this comment.

Name note: this extension was formerly ThreadRelink and is now ChatAnchor. Marketplace extension IDs cannot change after publishing, so the Marketplace URL and extension ID remain ascendho.threadrelink, and command/setting prefixes remain threadrelink.*.

Features

• Detects Codex, Cursor Agent CLI, and OpenCode independently, showing only providers with a local CLI or history so one missing agent never blocks the others
• Automatically reconnects after a project is renamed or moved, based on conservative evidence such as Git remote + commit and path aliases — never links by directory name alone
• Resume existing conversations or start new Codex / Cursor / OpenCode sessions directly from the ChatAnchor view
• Continue work in another agent with one action: build a layered local handoff from one conversation and start the target agent in the current project
• Build a complete local project context pack from linked conversations for multi-session archival, @path access, and deterministic local search
• Organize conversations with custom descriptions, hide / unhide controls, and Find Old Conversations
• Runs entirely locally — no telemetry, nothing uploaded

OpenCode conversations live in the local opencode.db and do not have standalone raw files, so Reveal / Copy @ Path is unavailable for them. To continue in another agent, use Continue in Another Agent...; use Export OpenCode JSON and Copy @ Path when you need a generated JSON @path. An explicit export can use a read-only database fallback even when the OpenCode CLI is temporarily unavailable.

Getting started

[!NOTE] ChatAnchor's default scan only reads local metadata. It never uploads data and reads selected message bodies only for explicit export, compact transcript, agent-handoff, or context-pack actions. Before first use, you must explicitly grant consent and set up each project.

1. Install the extension

   • Install from the Visual Studio Marketplace, or run:

     code --install-extension ascendho.threadrelink
     

   • Or download the latest VSIX from GitHub Releases and run:

     code --install-extension threadrelink.vsix
     

2. Open the ChatAnchor view: click the ChatAnchor icon in the Activity Bar; if it is hidden, right-click the Activity Bar and enable ChatAnchor.

3. Enable metadata scan: click "Enable Local Metadata Scan" to allow reading metadata for locally available Codex / Cursor / OpenCode conversations. Providers are detected independently, so a missing agent never blocks the others; projects are never scanned without explicit consent.

4. Set up the current project: click "Set Up This Project". If the folder is inside a parent Git repository, you will be asked to choose an independent directory identity or the parent repository identity.

5. Rename and reopen the folder: close the Codex terminal, rename the folder outside VS Code, reopen it, then click "Refresh Conversations".

6. Resume the original conversation or start a new one: hover a conversation row and click the continue icon. ChatAnchor opens an integrated terminal running codex resume --cd <new-path> <thread-id>, agent --resume <chat-id> --workspace <new-path>, or opencode <new-path> --session <id> at the new path. You can also use the title-bar plus button, or the plus button on a provider group, to start a new Codex / Cursor / OpenCode session directly in the project.

7. Organize the list: right-click a conversation to edit its description, hide it, generate compact context, or run Reveal Conversation File for Codex / Cursor conversations. The title-bar eye button shows hidden conversations or unhides them all.

8. Continue in another agent: right-click a historical conversation, choose Continue in Another Agent..., then select Codex, Cursor, or OpenCode. ChatAnchor preserves the complete original and readable conversation, creates an entry file containing the current working set, copies its @path, and starts the target agent in the current project.

9. Build a project context pack: run Create or Update Project Context Pack and select any number of linked conversations. ChatAnchor shows the source size first, copies the complete original records locally, creates readable Markdown transcripts, and copies the index @path. Use Search Project Context or Copy Project Context @ Path later.

Cross-agent conversation handoffs

Each handoff carries one conversation. The target agent first reads handoff.md, inspects the current project state, project instructions, Git status, and unfinished work, then presents a plan and waits for approval. It must not edit files, install dependencies, or commit changes before approval. Short conversations fit in the entry; long conversations continue from the last context-compaction boundary when available, otherwise keeping the initial goal and up to the latest 20 user turns. The target reads full-transcript.md or original/ only when the working set lacks details relevant to the current decision. Complete content remains in those layers, and ChatAnchor does not call a model to summarize or modify the source conversation.

Handoffs are reused when the same project, source conversation metadata, and complete source bytes are unchanged: ChatAnchor uses the existing local directory instead of copying and parsing it again. If the conversation gains a message, the source content changes, or source metadata changes, ChatAnchor creates a new directory and keeps the old one. This reuses local files; it does not transfer the previous agent's process, terminal, or model state.

Copy Compact @ Transcript remains available when you want a smaller file to pass manually without starting another agent.

Project context packs and CLI

A context pack is explicit, deterministic, fully local project memory. In context_pack.v2, context.md is the entry point, sources/ contains both a complete original copy and a readable transcript for every source, and manifest.json records sizes and SHA-256 digests. Nothing is redacted, removed, or truncated: system/developer messages, full tool input and output, credentials, cookies, and absolute paths are preserved. ChatAnchor therefore shows the source count, estimated size, and a sensitive-data warning before building. Atomic replacement leaves the existing pack unchanged if a source cannot be copied. Legacy context_pack.v1 packs remain readable and searchable.

The same workflow is available through a standalone npm CLI. The CLI never initializes projects; it only works with projects and conversations already set up and linked by the extension:

npx @ascendho/chatanchor-cli context list --cwd .
npx @ascendho/chatanchor-cli context build --cwd . --thread codex:<thread-id> --yes
npx @ascendho/chatanchor-cli context search --cwd . --query "release workflow"
npx @ascendho/chatanchor-cli context path --cwd .

Link Management Examples

For everyday cleanup, use Hide Conversation. Open link management only when a conversation belongs to the wrong ChatAnchor project.

Local data and privacy

ChatAnchor runs entirely on your machine. By default it only reads conversation metadata (title, timestamps, working directory, Git info), never reads message bodies, uploads nothing, and has no telemetry; scanning only happens after explicit project setup and consent.

Custom descriptions, hidden state, and project links are stored only in the local ChatAnchor registry. ChatAnchor does not modify the original Codex, Cursor, or OpenCode conversation data. ChatAnchor reads message bodies only for explicit export, compact transcript, agent-handoff, or context-pack actions, and generated files stay on your machine. Handoffs and full context packs are unredacted and require separate first-use consent; their build prompts describe the size and sensitive-data scope. They use 0700 directories and 0600 files on platforms with POSIX permissions. Forget Project also deletes generated handoffs and the context pack without deleting source conversations.

Roadmap

ChatAnchor currently runs fully locally and uploads nothing. Cross-device conversation history sync (for example via a private sync folder or a self-hosted backend) is not implemented yet, but it is under consideration.

Reporting bugs

Feedback is welcome. File reproducible bugs or feature requests in GitHub Issues — please search existing issues first. For security issues, use GitHub private vulnerability reporting instead of a public issue.

Feedback and contributing

Issues and pull requests are welcome:

• Contributions adding support for other coding agents (such as Claude Code, Gemini CLI, GitHub Copilot) are welcome; see the existing provider adapters in packages/core/src/;
• Remove absolute paths from screenshots and diagnostics; never upload ChatAnchor registry files, Codex transcripts, or unredacted local paths;
• Keep pull requests focused, describe the user impact, update tests or docs, and run pnpm check before submitting.

License

GPL-3.0 © 2026 ascendho

This project is licensed under GNU GPL-3.0. In short:

1. Attribution required — keep the copyright notice.
2. Derivatives must be open source — any modification, fork, or redistribution must be released under GPL-3.0 (or a compatible license) with full source code.
3. Free to use, modify, and redistribute — including commercial use; binary distributions must ship with the corresponding source.
4. No proprietary forks, paid-only redistribution, or relicensing to closed source.

Full terms: see LICENSE.