claude-desktop-to-code: Instructions file for Codex

Installing claude-desktop-to-code

You are an agent installing this for the person you are working with. Follow these steps in order. Stop and ask before step 5, which is the only step that writes anything.

This installs a local MCP server for Claude Desktop. It is macOS only.

The repo is claude-desktop-to-code; the installed command and Python module are both named cc-handoff / cc_handoff. That is expected, not a mistake.

1. Check the prerequisites

python3 --version                  # need 3.10 or newer
command -v claude || echo MISSING  # the Claude Code CLI must be on PATH

Do not use which claude. Many people wrap it in a shell function, and which prints the function body rather than a path, which is easy to misread in both directions. The authoritative check is doctor in step 6.

If claude is missing, stop and tell the user to install Claude Code first. Nothing else here will work without it.

2. Install

git clone https://github.com/abhaymettu/claude-desktop-to-code
cd claude-desktop-to-code
python3 -m venv .venv
.venv/bin/pip install -e .

Use the venv interpreter for every command below. Do not install into system Python.

3. Ask what it would do

.venv/bin/python -m cc_handoff setup --dry-run --json

This writes nothing. It returns the full plan as JSON:

• profiles, the directories it proposes, each with name, path, gist, exists, and new
• profile_source, whether these were discovered or kept from a config already present
• default_profile and default_valid
• terminal and terminal_tested
• desktop_config, where Claude Desktop's config lives and whether cc-handoff is in it

If profiles is empty, the user has no directories with a CLAUDE.md. Tell them that a profile is just a directory with its own CLAUDE.md, and that they should create one before continuing.

4. Show the user and get a decision

Do not skip this. Setup writes to their Claude Desktop config and decides which directories become reachable from a chat window.