CtxRelay (MVP)

CtxRelay is a small CLI tool for cross-AI collaboration.

It treats markdown chat archives as the core unit, then packages them into continuation prompts for different AI tools.

Why

Different AI products have inconsistent export behavior. Even when you can export markdown, moving context across tools and devices is still annoying. CtxRelay helps you store, package, and sync those archives.

MVP Commands

• ctxrelay ingest: save a chat archive markdown
• ctxrelay list: list recent archives
• ctxrelay show: preview latest archive
• ctxrelay export: generate continuation prompt from archive
• ctxrelay relay: one-shot clipboard relay (ingest + export + copy)
• ctxrelay watch: monitor plugin export folder and auto-relay new files
• ctxrelay checkpoint-show: show incremental relay checkpoint for a route
• ctxrelay checkpoint-reset: reset incremental relay checkpoint for a route
• ctxrelay project-show: show stable latest files for one project
• ctxrelay sync-status: check local archive + Git sync status
• ctxrelay state-init: initialize shared memory board
• ctxrelay state-show: view current shared state
• ctxrelay state-prompt: generate AI prompt for state update
• ctxrelay state-update: apply JSON update from AI
• ctxrelay state-history: list state snapshots

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

Quick Start

# Ingest from a file
ctxrelay ingest --input chat.md --project my-server-migration --source gemini

# Or ingest from stdin
pbpaste | ctxrelay ingest --project my-server-migration --source chatgpt

# List and preview
ctxrelay list
ctxrelay show

# Export prompt for next AI
ctxrelay export --target chatgpt --project my-server-migration

# One-shot relay from clipboard (recommended for web/app chat)
ctxrelay relay --from chatgpt --to gemini --project my-server-migration
# Then directly paste in Gemini; relay text is already in clipboard.

# Incremental auto relay (only new part after last checkpoint)
ctxrelay relay --from chatgpt --to gemini --project my-server-migration --auto
ctxrelay checkpoint-show --from chatgpt --to gemini --project my-server-migration
ctxrelay project-show --project my-server-migration

# Auto-monitor export folder (plugin-friendly workflow)
ctxrelay watch --dir ~/Downloads --pattern "*.md" --from chatgpt --to gemini --project my-server-migration
# Dry-run once:
ctxrelay watch --dir ~/Downloads --pattern "*.md" --from chatgpt --to gemini --project my-server-migration --once
# Note: do not watch `.ctxrelay/` itself (loop protection is enabled).

# Exported prompt contains sync metadata:
# - route (from -> to)
# - transfer mode (full / incremental)
# - previous sync timestamp (if auto mode)
# - fallback reason (when auto-match is weak and system falls back)

# Check sync readiness
ctxrelay sync-status

# Initialize shared state board
ctxrelay state-init --project my-server-migration --goal "finish server migration"

# Generate prompt for GPT/Gemini to update state
ctxrelay state-prompt --target chatgpt --output state_update_prompt.md

# Paste AI JSON response back into state
pbpaste | ctxrelay state-update --editor chatgpt

# Review current board and history
ctxrelay state-show
ctxrelay state-history

Data Folder

CtxRelay stores local data in:

• .ctxrelay/conversations/ archived markdown logs
• .ctxrelay/exports/ packaged prompt outputs
• .ctxrelay/latest_conversation.txt latest pointer
• .ctxrelay/checkpoints.json incremental relay checkpoints
• .ctxrelay/projects/<project>/latest_conversation.md stable latest conversation file
• .ctxrelay/projects/<project>/latest_export_<from>_to_<to>.md stable latest export file
• .ctxrelay/state/current.json shared memory board
• .ctxrelay/state/history/ board snapshots

Legacy compatibility:

• If .ctxrelay/ does not exist but .mindbridge/ exists, CtxRelay auto-migrates data from .mindbridge/ into .ctxrelay/ on first run.

Notes

This MVP is fully local and does not require running any model. For cross-device sync, use a private Git repo (recommended) or your preferred cloud folder.

Browser Plugin (MVP)

If you want browser-side one-click export, use the included unpacked Chrome extension:

• extensions/chrome-chatgpt-export

Quick setup:

1. Open chrome://extensions
2. Enable Developer mode
3. Load unpacked extensions/chrome-chatgpt-export
4. On ChatGPT page, click Export to .md
5. Start watcher:
   • ctxrelay watch --dir ~/Downloads/ctxrelay-exports --pattern "*.md" --from chatgpt --to gemini --project my-project

Edge support:

• This extension also works in Edge (edge://extensions) because Edge is Chromium-based.