Skip to content
Quern

Getting Started

Prerequisites

Section titled “Prerequisites”

You need two things before installing:

  • Xcode — Full Xcode from the App Store, not just the Command Line Tools. You need it for simulators, xcodebuild (app and WDA builds), signing, and provisioning. Sign in to your Apple Developer account in Xcode > Settings > Accounts to manage signing identities.
  • Homebrew — brew.sh. Quern uses Homebrew to install most of its dependencies (idb, mitmproxy, libimobiledevice, etc.). Setup will not install Homebrew itself — if it’s missing, you’ll be told.
  • Android Studio (optional) — Only needed if you’re working with Android. Provides adb, emulator, and the SDK tools. Quern auto-discovers these from your PATH or the standard SDK install locations.

Install

Section titled “Install”
Terminal window
curl -fsSL https://quern.dev/install.sh | bash

That’s it. The installer downloads the latest release to ~/.local/share/quern, then runs quern setup, which does everything else:

  1. Installs Python (via Homebrew) if you don’t already have a supported one (3.11–3.14), then creates a virtual environment and installs server dependencies
  2. Checks for system tools and offers to install what’s missing:
    • Xcode Command Line Tools — for simctl (simulator control) and devicectl (iOS 17+ devices)
    • idb + idb-companion — for simulator UI automation (accessibility tree, tapping, typing)
    • pymobiledevice3 — for physical device screenshots, logs, and tunneling
    • mitmproxy — for network traffic interception
    • Node.js — for the MCP wrapper
  3. Builds the MCP server (TypeScript → JavaScript)
  4. Registers the MCP server with Claude Code (writes to ~/.claude.json)
  5. Adds quern to your PATH (via ~/.local/bin)
  6. Tracks what it installed in ~/.quern/installed-by-setup.json so quern uninstall can cleanly remove only what it added

Setup prompts before installing anything — it won’t surprise you with Homebrew packages you didn’t agree to. If a tool is already installed, it skips it.

Where you run it from

Section titled “Where you run it from”

Two moments, two spellings, and it is worth knowing which you are in.

During the first setup there is nothing on your PATH yet, so you run it by path — ./quern setup if you are standing in the directory. Quern installs to ~/.local/share/quern, which is probably not where your terminal is, so if you are elsewhere give the full path: ~/.local/share/quern/quern setup.

Afterwards, just type quern. Setup puts it on your PATH, so it works from any directory and you never need to know where Quern lives. The rest of these guides are written that way.

If the very next command reports command not found: quern, the shell is caching where commands live and has not noticed a new one. Run rehash (zsh) or open a new terminal.

Quern’s own messages follow the same rule — when something goes wrong it names the command the way you can type it, so if it prints a full path, that is because the short name would not have worked from where you are.

When everything’s ready, you’ll see a summary like this:

──────────────────────────────────────────────────
  Quern Setup Summary
──────────────────────────────────────────────────
  ✓ Platform: macOS 26.3.1
  ✓ Homebrew: Homebrew 5.0.16
  ✓ Python: 3.12.12
  ✓ Virtual env: ~/.local/share/quern/.venv
  ✓ libimobiledevice: idevicesyslog 1.4.0
  ✓ ideviceinstaller: ideviceinstaller 1.2.0
  ✓ Xcode CLI Tools: Installed (simctl available)
  ✓ mitmdump: 12.2.1
  ✓ Node.js: v20.19.5
  ✓ idb_companion: installed
  ✓ idb (fb-idb): installed
  ✓ pymobiledevice3: 7.7.1
  ✓ tunneld: Running on http://127.0.0.1:49151
  ✓ VPN Detection: No active VPN detected
  ✓ mitmproxy CA Cert: ~/.mitmproxy/mitmproxy-ca-cert.pem
  ✓ Crash dialog: Disabled (crash reports still saved to disk)
  ✓ Wrapper script: Installed to ~/.local/bin/quern
  ✓ MCP server: Built successfully
──────────────────────────────────────────────────
  All checks passed — ready to go!

Not everything needs to be green. If you’re only working with simulators, you won’t have tunneld or libimobiledevice — that’s fine. Setup tells you what’s missing and what it affects.

Manual install (for contributors / development)
Terminal window
git clone https://github.com/quern-dev/quern.git
cd quern
./quern setup
./quern mcp-install

./quern because you are in the clone. After setup quern also works from anywhere — though in a clone, prefer ./quern: with more than one checkout the bare name resolves to whichever one setup last pointed it at.

For Physical iOS Devices (iOS 17+)

Section titled “For Physical iOS Devices (iOS 17+)”

Setup automatically installs the tunneld LaunchDaemon (it will ask for your sudo password). This creates persistent tunnels to connected iOS 17+ devices — required for screenshots, logs, and WDA on modern iPhones. See Device Pool for why this exists.

For Android

Section titled “For Android”

Install Android Studio (or the standalone SDK tools). Quern finds adb and emulator automatically from your PATH, ANDROID_HOME, or the standard SDK install locations. No additional Quern setup needed.

Start the Server

Section titled “Start the Server”
Terminal window
quern start              # Runs in the background
quern start -f           # Foreground mode (useful for troubleshooting the server itself)

On startup, Quern finds available ports, checks which tools are installed, and starts its log/proxy/crash adapters. It writes everything to ~/.quern/state.json, which is how the MCP wrapper and CLI discover the server.

Verify It Works

Section titled “Verify It Works”

After starting, run quern status to confirm it’s up and see which tools were detected. Then in your AI agent, try:

“List my available devices”

or

“Take a screenshot of the simulator and show me in Preview”

If you see devices and get a screenshot, you’re good to go.

Using Quern with Your AI Agent

Section titled “Using Quern with Your AI Agent”

Claude Code

Section titled “Claude Code”

If you ran the installer, the MCP server is already registered. Just open Claude Code in your project and start asking:

“Boot an iPhone 16 simulator, install my app, and show me what API calls happen during login”

If you installed manually, run quern mcp-install to register. It registers Claude Code, Claude Desktop, Cursor, OpenCode and Codex with the absolute path of a Node 22+ binary, and prints which one, so each client runs that node rather than whichever node its own PATH finds. Run it again after changing Node versions in a way that removes that binary; quern doctor lists each client’s registration and says when that is needed.

Other MCP Clients

Section titled “Other MCP Clients”

Point your client at an absolute Node 22+ binary running ~/.local/share/quern/mcp/dist/launcher.cjs — for example command /opt/homebrew/bin/node (or ~/.local/share/fnm/aliases/default/bin/node, written out in full) with that launcher as its argument. A bare node is resolved on the client’s own PATH, which is the problem described below.

Use launcher.cjs rather than index.js. It checks the Node version first and tells you which binary it is running under if that version is too old — worth having, because MCP clients do not always pick the node you expect.

Which node a client gets depends on how the client was started. A client opened from the Dock doesn’t read your shell’s startup files, so a Node installed with fnm, nvm, mise or asdf is invisible to it even when every terminal finds it. quern doctor shows the node found in each place: this terminal, a login shell, a non-interactive shell, apps opened from the Dock, and the Quern app itself. For any place where it’s missing or older than 22, it gives the fix for that place.

For a client opened from the Dock, Homebrew does not help: launchd’s PATH is /usr/bin:/bin:/usr/sbin:/sbin, which /opt/homebrew/bin is not in. Set the client’s command to an absolute path to a Node 22+ binary, or add a directory to every GUI app’s PATH with sudo launchctl config user path … and log back in.

The MCP wrapper auto-discovers the running server via ~/.quern/state.json — no URL or API key configuration needed.

Server Lifecycle

Section titled “Server Lifecycle”
Terminal window
quern status             # Is it running? What port? What tools are available?
quern stop               # Graceful shutdown
quern restart            # Stop + start
quern update             # Pull latest changes, reinstall deps, rebuild
quern uninstall          # Remove Quern and everything setup installed

The server runs as a background daemon. It survives terminal closure and persists until you explicitly stop it or reboot. If Quern’s source code is updated (via quern update or git pull), restart the server to pick up changes.

Configuration

Section titled “Configuration”

Optional config at ~/.quern/config.json:

{
  "default_device_family": "iPhone",
  "local_capture": ["MobileSafari", "com.apple.WebKit.Networking"]
}
  • default_device_family: When your agent asks for a device without specifying what kind, default to this. Usually “iPhone”.
  • local_capture: Process names for transparent network capture. Safari and WebKit are a good default — your agent can add your app’s process name when it starts a debugging session. It is the whole list, not a set of additions: a process not named here is not captured.

Where Things Live

Section titled “Where Things Live”
PathWhat
~/.local/share/quern/Source code (installed by curl script)
~/.local/bin/quernCLI wrapper (on your PATH)
~/.quern/state.jsonHow everything finds the server (ports, PID)
~/.quern/config.jsonYour configuration (optional)
~/.quern/server.logServer logs (daemon mode)
~/.quern/api-keyAuthentication token
~/.quern/installed-by-setup.jsonWhat setup installed (for clean uninstall)
~/.quern/device-pool.jsonKnown devices and their state
~/.quern/cert-state.jsonProxy certificate installation state
~/.quern/app-states/Saved app state checkpoints
~/.quern/crashes/Pulled crash reports
~/.quern/wda/WDA build cache and runner logs

Next Steps

Section titled “Next Steps”