Install and connect agents
How the zeptap command gets on your PATH, how to teach Claude Code, Codex and Cursor to use it, and how it gets through agent sandboxes.
Install
There's nothing to install separately. When Zeptap runs from your Applications folder, it links ~/.local/bin/zeptap to the tool inside the app and keeps the link current across updates. If ~/.local/bin isn't on your shell's PATH, it adds one guarded line to ~/.zshenv (or ~/.bash_profile for bash), once.
Settings › Connectors › Command line shows the status, and has an Install button if the link is missing.
With Homebrew, brew install --cask zeptap/tap/zeptap links the same tool.
The Beta build installs zeptap-beta, which talks only to Zeptap Beta. It also takes zeptap while no other copy of Zeptap has it.
Check it
zeptap doctordoctor checks the command, PATH, the app, the connection, the license, the phones and the agent skills, and says how to fix whatever is wrong.
Teach your agents
Settings › Connectors › Command line lists the agents found on this Mac. Add does two things for each one:
| Agent | Skill | Also allows zeptap to run |
|---|---|---|
| Claude Code | ~/.claude/skills/zeptap/SKILL.md | Bash(zeptap:*) in permissions.allow, and Zeptap's socket folder in sandbox.network.allowUnixSockets, in ~/.claude/settings.json |
| Codex | ~/.agents/skills/zeptap/SKILL.md | ~/.codex/rules/zeptap.rules: prefix_rule(pattern = ["zeptap"], decision = "allow") |
| Cursor | ~/.cursor/skills/zeptap/SKILL.md | |
| Other agents | ~/.agents/skills/zeptap/SKILL.md (Gemini CLI, OpenCode, ...) |
The skill is short. It tells the agent to run zeptap --help first, so the manual always matches the installed version. zeptap skill install writes the same skill files from a terminal, without the permission rules.
Use either the CLI or MCP for an agent, not both: two sets of instructions for one phone tend to confuse it.
Agent sandboxes
Codex's sandbox, and Claude Code's when it's turned on, block every way a shell command could reach a local app: TCP, Unix sockets and launching apps. zeptap talks to Zeptap over a Unix socket in ~/Library/Application Support/Zeptap/run/, so one exception covers it:
- Claude Code: the socket folder in
sandbox.network.allowUnixSockets. Add in Settings writes it. - Codex: the
allowrule above. Codex then runszeptapwithout asking, outside its sandbox.
When a sandbox blocks it, zeptap exits with code 8 and prints the setting for the agent it's running in. Agents should call it by its bare name, zeptap, not a full path: permission and sandbox rules match the command as typed.
How it connects
If Zeptap isn't running, zeptap opens it in the background and waits for it (up to 20 s). Inside a sandbox it can't, so the user has to open Zeptap first.
The command finds the running app through ~/Library/Application Support/Zeptap/run/server.json. The app rewrites that file on every launch with its process id, TCP port, socket path and version. The command then sends MCP requests over the Unix socket zeptap.sock in the same folder. That folder is readable only by your user (mode 0700), so only your own processes can connect. If the app is too old to have the socket, the command falls back to http://127.0.0.1:47801/mcp.
CLI overview
The zeptap command drives your iPhone from any shell. It saves screenshots as files, reads the screen as text with refs, holds phones with leases, batches steps, and returns exit codes agents can act on.
Output and exit codes
Where zeptap saves screenshots, how @t refs work, the JSON it prints with --json, and what each exit code means.