claude-mrc

Grab your Claude Code session on your phone.

mrc launch <project> opens a real, visible terminal window on your machine and starts claude --remote-control <name> inside it. That session registers with claude.ai and shows up as grabbable in the Claude mobile app. It's a true handoff, not a copy: what you type on your phone is the same conversation shown in the terminal tab, live, in both directions.

What it is not: a way to start a session by tapping something on your phone. You start it at your machine — mrc launch — and pick it up on the phone afterward. Triggering a brand-new session from the phone with nothing running yet is not built. See Roadmap.

Status and platform support

Early (0.1.0), actively developed, 400+ tests. Windows and Linux are supported now; macOS is not yet.

• Windows — fully supported, the primary development platform. Both Windows Terminal (wt.exe) and the plain console (start via cmd.exe) work as launch targets.
• Linux — supported and CI-tested. Terminal presets ship for gnome-terminal, konsole, alacritty, wezterm, kitty, and tmux. Honestly: no test in this repo spawns a real terminal on any platform, on any OS — presets and templates are validated (argv construction, placeholder substitution, quoting rules) against a fake terminal binary, not launched for real. CI is green on windows-latest and ubuntu-latest.
• macOS — not yet verified. There is no macOS CI runner and nothing in this project has ever actually been executed on a Mac. The native Terminal.app and iTerm2 presets that once existed were deliberately removed: the AppleScript that drove them left project names unquoted, which is unsafe with names containing quotes or shell metacharacters. If you have alacritty, wezterm, kitty, or tmux installed, mrc setup should find one of those and things should work — but this is untested, not guaranteed. A stock Mac with none of those installed will find no terminal at all, and mrc setup will ask you to paste a custom command template. macOS support, testing, and PRs are welcome.

Install

npm install -g claude-mrc

Requires Node.js 20+.

60-second quickstart

mrc setup            # interactive: finds claude, picks a terminal, scans for projects
mrc launch my-app    # opens a terminal tab running `claude --remote-control my-app`

Open the sessions list in claude.ai/code or the Claude mobile app — my-app is there. Type from your phone; it appears in the terminal tab on your machine, and vice versa.

Commands

| Command | What it does | |---|---| | mrc setup | Interactive wizard: detects the claude binary, offers an installed terminal preset (or asks for a custom command template if none is found), scans directories for projects, and writes ~/.mrc/config.json. Run with --non-interactive for a scripted install. | | mrc launch <project> | Opens a terminal tab in the project's directory and starts claude --remote-control <name> inside it. <project> matches by name, alias, or substring. Add --json for one line of machine-readable output. | | mrc list | Lists registered projects, grouped. | | mrc add <path> | Registers a project directory. --name <name> to override the derived name, --group <label> to tag it. | | mrc doctor | Runs every pre-flight check mrc launch depends on — claude binary and version, remote-control-blocking environment variables, terminal availability, project paths, hazardous project names/paths for the configured terminal, the session log directory, duplicate registry entries, and trust state — and reports all of them at once instead of failing on the first one at launch time. |

mrc setup --non-interactive flags: --claude-path <path>, --preset <id> (e.g. windows-terminal, wezterm, tmux), --template "<argv tokens>" for a hand-written terminal command, --scan-root <path> (repeatable), --all to register everything a scan finds, --import <file> to bring in a legacy projects.json, and --force to overwrite an existing config.

Requirements

• Node.js 20+.
• The Claude Code CLI installed, version 2.1.51 or newer (mrc setup auto-detects it on PATH, or accepts --claude-path).
• A Claude subscription login — the interactive login flow, not an API key. Remote control does not register under API-key or custom-endpoint auth. Three environment variables disable it outright: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and a non-default ANTHROPIC_BASE_URL. mrc doctor and mrc launch both detect these ahead of time and fail fast, naming the offending variable, instead of waiting out the full ~35-second registration timeout to report a generic "did not register." (mrc also strips every CLAUDE_CODE* variable — including a headless/CI CLAUDE_CODE_OAUTH_TOKEN — from the environment the launched session gets, so a setup token sitting in your shell does not interfere with remote control.)

Known limitations

• macOS is unverified. See Status and platform support.
• The interactive setup wizard (mrc setup, no --non-interactive) has no automated test coverage. It needs a real TTY to run at all, so it is exercised by hand, not by CI. --non-interactive mode shares the same underlying config-building logic and is fully tested.
• No test spawns a real terminal application, on any platform. Terminal templates are validated (correct argv, correct quoting, correct placeholder substitution) against a fake terminal binary; nothing in CI confirms that, say, real Windows Terminal or real gnome-terminal accepts the constructed command line the way the fake one does.
• The windows-console preset routes values through cmd.exe. As a result, project names and paths containing ", %, &, ^, <, >, |, or raw control characters are rejected outright rather than escaped — there is no verified-safe way to quote all of them for cmd.exe, so mrc add/mrc setup/mrc launch refuse instead of risking a silently broken or hijacked command line.
• Trust state is advisory only. mrc doctor reports untrusted project folders as a warning, never an error — a project this codebase was developed against registered a session successfully despite carrying hasTrustDialogAccepted: false, so an unaccepted trust prompt is not a confirmed blocker, just one possible explanation offered when a launch doesn't register.
• One global config, at ~/.mrc/config.json (override with MRC_CONFIG). No per-workspace or per-team configuration yet.

Roadmap

• A phone-triggered daemon: start a brand-new session from the mobile app with nothing already running on the machine. Not built. Everything today requires you to run mrc launch at the machine first.
• Verified macOS support, including a safe (properly quoted) native Terminal.app/iTerm2 preset.
• Real-terminal integration tests, not just template validation.

License

MIT — see LICENSE.