Install in your agent
Register the Parallax MCP server and skill with Claude Code or Codex, see exactly what changes, and add the optional parts.
You do this once per machine, in any folder. Each command prints what it will change as a diff, asks, and only then applies it.
A one-step setup is coming.
npx -y @parallax-rn/mcp@0.1.0-beta.2 setup claude --allow-read-only-tools # Claude Code
npx -y @parallax-rn/mcp@0.1.0-beta.2 setup codex # CodexFor Claude Code, --allow-read-only-tools also offers, as a separate question, to allow the read-only tools. Without it Claude Code asks before every Parallax tool, including status, until you allow them (see Permissions).
The device tools (screenshot, tap, type) need AXe. Install it now, or the first device tool fails with axe_missing:
brew install cameroncooke/axe/axeUse this same version (0.1.0-beta.2) for the SDK and the build plugin in your app (see Update and undo). Start a new agent session afterwards and ask it for status.
What it changes
- Runs the agent's own
mcp addto register a server namedparallax. For Claude Code it is registered at user scope and passes thePARALLAX_TABvariable through. - Writes
skills/parallax/SKILL.mdunder~/.claudeor~/.codex. - For Codex, adds
env_vars = ["PARALLAX_TAB"]to the[mcp_servers.parallax]table.
Nothing else. An entry or a skill that already exists is reported as "already present, not added". One that is not Parallax's is never touched.
PARALLAX_TAB is set by the Parallax window in its terminal tabs, so the server knows which tab an agent runs in. Outside the window it is empty and nothing changes.
Codex and terminal tabs
The Codex terminal UI usually talks to a shared background daemon that starts MCP servers with its own environment, so PARALLAX_TAB does not reach the server. Parallax then reports the tab as unknown and never guesses one. To get the tab, start Codex with codex --no-daemon in a Parallax terminal tab. The cost: that session is not part of the daemon's shared agent list and background threads.
Flags
| Flag | What it does |
|---|---|
--dry-run | Prints the diff and changes nothing |
--yes | Skips the question (the diff is still printed) |
--scope project | Claude Code only: registers in <repo>/.mcp.json and installs the skill in <repo>/.claude/skills. Add --project <repo>; Claude Code asks once to approve a project server. Codex has no project scope, so it is always global |
--update | Moves an existing Parallax registration or skill to this version |
--undo | Removes what setup added (see Update and undo) |
--hook | Optional: the nudge hook and session events (below) |
--answer-approvals | Optional: answer the agent's permission prompts from the window (see Approvals) |
--strict-approvals | Optional: tools that act wait for your approval in the window (below) |
--allow-read-only-tools | Claude Code: also allow the read-only tools without a prompt (below) |
--local, --package <spec> | Choose what npx runs |
The full list is in the CLI reference.
With the desktop app installed
If the Parallax app is in /Applications or ~/Applications, setup registers the app's own copy of the server instead of the npm package. The hooks start faster and no Node is needed. The diff names the route. An existing npm registration moves to the app only with --update.
Permissions (optional)
Claude Code asks before every MCP tool until a permission rule allows it. setup claude --allow-read-only-tools (the command at the top of this page) offers, as a separate question after its own diff, to add the read-only tools to permissions.allow as mcp__parallax__<tool>. Tools that act (tap, type, swipe, open URL, launch, reload, run command, boot) are never added.
Codex asks only for destructive or open-world tools. To stop its prompts for Parallax, set default_tools_approval_mode = "approve" under [mcp_servers.parallax] in ~/.codex/config.toml yourself; setup never writes it. If the first start after a cold npm cache is slow, startup_timeout_sec = 30 in the same table raises Codex's 10 s limit.
The nudge hook (optional)
setup <agent> --hook adds hooks in one opt-in and one diff, each running the server's hook <agent> command:
UserPromptSubmitcarries the nudge: when you sent the agent something from the Parallax window, it tells the agent once per turn to callparallax_inbox. After 3 unanswered nudges the item is marked "not picked up".- Six more events (Claude Code:
SessionStart,PermissionRequest,PostToolUse,PostToolUseFailure,Stop,SessionEnd; Codex: the same withInterruptinstead ofPostToolUseFailure) only tell the window which session is running and whether it works, waits for you or is idle. They send ids and names only: never your prompt, the agent's text, or a tool's input or output.
The hooks answer nothing, print nothing, give up after 1.5 s when the window is not running, and never fail the agent's turn. For Claude Code the entries go into settings.json (settings.local.json with --scope project); for Codex into ~/.codex/hooks.json. Other hooks are never touched.
On Codex, a new hook is marked "Hooks need review": open /hooks in Codex once and trust it, or it does not run.
Strict approvals (optional)
setup <agent> --strict-approvals makes the tools that act wait for your approval in the Parallax window, and fail with a clear error when the window is not running. It writes a small config.json next to the Parallax run directory and switches off the agent's own prompt for Parallax's tools (Claude Code: mcp__parallax in permissions.allow; Codex: default_tools_approval_mode = "approve" and tool_timeout_sec = 120). A Codex setting you already made is never overwritten. doctor shows which mode is active.
What strict approvals do not protect against
They protect against an agent that uses the Parallax tools, and against one that goes around them to the core's socket. They do not protect against a process of the same macOS user that is out to defeat them: it can read the run directory's token, send input to the simulator without Parallax at all, and drive the window with synthetic events. The approval card is a speed bump and a record for a cooperating agent, not a sandbox. The only complete defence is running the agent as another user or in a sandbox without the run directory.
A call that waits for an approval, or any call that takes long, sends progress notifications every 8 s when the agent asks for them.
What it costs in the agent
The tool schemas are loaded in every session where the server is registered, also in projects that are not React Native (the schemas cost context tokens in each session). Codex loads all tool schemas into every session. If that matters, use --scope project with Claude Code.
Check it
Ask the agent for status first: it is the short check. If it reports a problem, or you want the full list, ask for doctor, or run it yourself in your app's project root: npx -y @parallax-rn/mcp@0.1.0-beta.2 doctor.
A good doctor starts with Parallax doctor: device tools ready; app tools ready. Right after install the app tools stay "NOT ready" until Metro and your app are running. Every failed or warned check has a Fix: line; see Troubleshooting.