claude-desktop-to-code

An MCP server that routes work from a Claude Desktop chat into Claude Code, either headlessly, or by opening a terminal you can take over.

The point is the handoff. You ask a question in chat, it runs headlessly in the right directory, and when you want to drive it yourself the same session opens in a real terminal with its history intact.

Profiles

A profile is a directory containing a CLAUDE.md. That is the whole definition. Each one has its own instructions and its own folder-scoped memory, so "which profile" is really "which agent".

Everyone organises these differently, so setup reads three layers rather than assuming one convention:

1. Names you already chose. If your shell rc defines a CLAUDE_PROFILES map, those names and paths are used as-is and always survive --limit. Nobody has to adopt anyone else's naming scheme. The written list is alphabetical, not ranked.
2. Where you actually work. ~/.claude.json records every directory you have run Claude Code in and when, so the list is ranked by real use rather than by guesswork. Worktrees, temp dirs, and $HOME are filtered out.
3. A filesystem scan, for a machine with no history yet.

Each layer degrades to the next, so a fresh install with no conventions at all still produces a sensible list. --limit caps how many are kept (12 by default).

Every tool runs inside a named profile. There is no free-form path parameter. A directory that is not in your config cannot be touched.

Install

Paste this repo's URL to your coding agent and say "install this". It will read AGENTS.md, work out your profiles, show them to you, and ask before writing anything.

By hand:

git clone https://github.com/abhaymettu/claude-desktop-to-code
cd claude-desktop-to-code
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m cc_handoff setup --dry-run    # see the plan first
.venv/bin/python -m cc_handoff setup --default <one of your profiles>
.venv/bin/python -m cc_handoff doctor             # confirm it works

setup walks a few roots for CLAUDE.md files, detects which terminal you use and pins it, writes ~/.config/cc-handoff/config.toml, and registers itself in claude_desktop_config.json (backing up whatever was there). Restart Claude Desktop afterward.

Re-running setup keeps every profile already in the file and only refreshes the terminal and default. Pass --rescan to look for new profiles, which adds but never drops. The file is rewritten rather than patched, so comments and any keys cc-handoff does not know about are lost; keep notes elsewhere.

It over-collects on purpose. Open the toml and delete what you do not want:

default_profile = "scratch"

[profiles]
brain   = "/Users/you/Documents/Brain"
scratch = "/Users/you/scratch"

Other commands: cc-handoff profiles, cc-handoff terminals, cc-handoff doctor. The console script is cc-handoff; python -m cc_handoff is equivalent.

setup --dry-run prints the plan and writes nothing. Add --json to either setup or doctor for machine-readable output, which is what an agent driving the install uses. doctor exits non-zero when something fatal is wrong.

Tools

Tool	What it does
list_profiles()	Names, paths, and a one-line gist from each CLAUDE.md
ask_claude_code(prompt, profile, allow_edits=False)	Headless claude -p; returns the answer and a session_id
handoff_to_terminal(session_id, profile, terminal)	Reopens that session in a terminal via --resume
open_in_claude_code(brief, profile, terminal)	Writes <profile>/.claude/HANDOFF.md, opens a terminal there

allow_edits defaults to false and must be set deliberately.

Permissions do not survive the handoff

allow_edits applies only to the headless run. handoff_to_terminal resumes that session with no permission flags, so once a window is open you are under ordinary interactive Claude Code rules and approve actions yourself.

This is deliberate. A read-only headless answer becoming a read-only terminal would be the wrong default: you are at the keyboard now, and the interactive permission prompt is a better gate than a flag inherited from a chat message. But it does mean a restricted headless call can be continued into an unrestricted session, so do not treat allow_edits=False as a durable sandbox.

Terminals

Terminal	Status	How it launches
Ghostty	tested	open -na
Terminal.app	tested	AppleScript
iTerm2	tested	AppleScript
kitty	untested	needs its CLI
WezTerm	untested	needs its CLI
Alacritty	untested	needs its CLI

Untested means never run, not "probably works". Expect the three that need a CLI to fail unless you have installed it: kitty, WezTerm and Alacritty ship their command line tool inside the .app bundle and do not put it on PATH on their own. cc-handoff looks on PATH first and then inside the bundle, and refuses to select a terminal it cannot actually launch, so the failure is an error message rather than a hang.

cc-handoff looks for each .app in /Applications and ~/Applications, since casks and manual installs land in either.

Auto-selection prefers tested recipes. An untested one is only chosen if it is the terminal you are currently running in, or if nothing tested is installed.

setup picks your terminal once and writes it to the config, so it is a decision you can see and edit rather than a guess made on every call. Selection order at runtime: the tool's terminal argument, then terminal in the config, then $CC_HANDOFF_TERMINAL, then whatever is running (TERM_PROGRAM), then whatever is installed. macOS only for now.

One window per profile

open_in_claude_code checks whether a session is already running in that directory. If one is, it updates HANDOFF.md and tells you to switch to that window and say "reread .claude/HANDOFF.md" instead of stacking up another. Pass new_window=true to override.

Tabs are not an option: open -na has to start a separate instance to pass -e, plain open -a ignores --args, Ghostty's +new-window action is Linux-only, and macOS native tabbing cannot merge windows across instances.

Ghostty is launched with open -na Ghostty.app --args ... -e <command>, which is what Ghostty's own help tells you to do: running the bundle binary directly is unsupported on macOS, starts a fresh instance per call, restores every saved tab, and makes macOS re-prompt for permission to exec the CLI each time.

--window-save-state=never is passed so a handoff window opens empty rather than restoring an old session. Reusing an already-running instance is not possible. Plain open -a accepts --args and silently ignores them.

Quoting

The brief never meets a shell. It is written with Path.write_text and never enters an argv. Commands are built as argv lists and run with shell=False for four of the six terminals; iTerm2 and Terminal.app are the exception, see below.

iTerm2 and Terminal.app are the exception: AppleScript takes a command string, not an argv, so those recipes build cd <dir> && <command> with shlex.quote and then escape the result for the AppleScript literal. That string is run by a shell.

tests/quoting_probe.py covers both halves. It pushes a hostile brief through the wire and asserts the file on disk is byte identical, then takes ten hostile arguments, including newlines, quotes, backslashes and AppleScript injection bait, generates the real Terminal.app script, compiles it with osascript, and asserts the command comes back unchanged. Reverting the escaper to a version that does not handle newlines makes the probe fail, which is the point.

Environment

Variable	Default
CC_HANDOFF_CLI	claude
CC_HANDOFF_CONFIG	~/.config/cc-handoff/config.toml
CC_HANDOFF_TERMINAL	auto-detected
CC_HANDOFF_TIMEOUT	600
CC_HANDOFF_DRY_RUN	unset; when set, terminal launches return the argv instead of opening a window

Pointing CC_HANDOFF_CLI at another agent CLI mostly works, as long as it accepts -p and --resume.

Tests

.venv/bin/python tests/run_all.py              # protocol and quoting
.venv/bin/python tests/run_all.py --with-e2e   # adds ask -> handoff, spends real tokens

Individually: stdio_probe.py does a real MCP handshake over a pipe to a subprocess, quoting_probe.py covers the brief and the AppleScript escaping, and e2e_probe.py runs a headless prompt and hands the session to a terminal. Only the last one costs anything.

Relation to other projects

This is not a fork. It shares no code with any other project and was written from scratch.

The closest existing thing is steipete/claude-code-mcp (JavaScript, MIT), which wraps the Claude Code CLI in a single claude_code tool for one-shot delegation. If all you want is "let my MCP client run a Claude Code prompt", use that. It is mature and widely used.

That server is not one-shot: its claude_code tool takes a sessionId, and repeated calls with the same id resume the same session. Session continuity is not the difference. The differences are:

• Handing a session to a human. cc-handoff opens the session in a real terminal window with its history intact, so you stop being the relay between a chat box and your own machine. That is the whole reason this exists.
• Profile routing. Work is addressed to a named directory rather than a path supplied per call, so "which agent" is a first-class argument and directories not in your config cannot be reached at all.
• Permission default. allow_edits is false unless asked for. That server defaults to bypassPermissions for backwards compatibility, with a permissionMode argument to opt out.

It is also Python rather than JavaScript, and macOS only, where that server is cross-platform. If you want a mature, cross-platform way to run a Claude Code prompt from an MCP client, use theirs.

Requirements

macOS, Python 3.10+, mcp (2.x or 1.x, the import is version-guarded), and the claude CLI on PATH.