Quern

Eyes, ears, and hands for AI-assisted mobile development.

Quern is a local debug server that lets AI coding agents — Claude Code, Cursor, Windsurf, and others — actually see what your app is doing. Logs, network traffic, crash reports, screenshots, UI state: instead of guessing from stack traces and stale error messages, your agent gets live, structured access to everything happening on the device.

No cloud. No telemetry. Just a daemon on your Mac that bridges the gap between "build succeeded" and "it actually works."

Supports iOS simulators, physical iOS devices (via WebDriverAgent), Android emulators, and physical Android devices.

Simulator / Device
    │
Quern (localhost:9110)
    ├── Log capture (device, simulator, crash reports, build output)
    ├── Network proxy (intercept, mock, replay HTTP traffic)
    ├── Device control (boot, screenshot, tap, swipe, type)
    │
    ├── HTTP API ──→ Any tool or script
    └── MCP tools ──→ Claude Code, Cursor, etc.

AI agents are good at writing code. They're bad at knowing whether it worked -- especially on mobile devices. A build error gets caught; a silent API failure, a wrong screen, or a crash on launch usually doesn't — unless you paste logs back into the chat yourself.

Quern closes that loop. It gives agents direct, token-efficient access to everything they need to diagnose and fix problems autonomously: structured logs, network request/response pairs, parsed crash reports, screenshots, and the ability to interact with the running appon a simulator or real device.

Quern isn't a cloud testing platform. It's local infrastructure that makes the AI tools you already use actually effective at debugging and testing mobile apps.

• Local-first — No cloud, no accounts, no third-party API keys. Your code and logs never leave your machine, unless you point quern at another Mac you've paired with.
• Works with your existing AI — Not a replacement for Claude, Cursor, or Codex. It makes them better by giving them live access to what your app is actually doing.
• Built for your editor and CLI — Designed for agents already in your workflow, not a separate QA portal.
• Great for QA and SDET workflows — Pair with an agent during manual testing. Let it intercept network calls, mock error responses, or verify analytics payloads while you drive the app — no more juggling Charles Proxy and a terminal.
• Free and open source — Apache 2.0 licensed. Run it free, forever, on your own hardware.

A 20-minute deep dive generated by Google NotebookLM from the Quern repository. Good overview of the architecture and use cases. This is definitely 'AI slop', and may be either useful, entertaining, or horrifying for you to listen to. You have been warned; choose wisely.

• Log capture — device, simulator, Android and macOS logs, crash reports and build output, deduplicated into one queryable buffer with LLM-ready summaries.
• Network proxy — capture HTTP/HTTPS traffic with mitmproxy, then query, inspect, intercept, mock and replay it. Simulators can be captured per app with no system proxy; physical devices through their Wi-Fi proxy setting.
• Device control — boot and manage simulators and emulators, install and launch apps, take screenshots, read the accessibility tree, and tap, swipe and type. Physical iPhones are driven through WebDriverAgent.
• Shared and remote servers — reserve devices so several agents can share one server, and pair another Mac to use its devices.
• App knowledge base — a map of your app, built with your agent and kept in your repo: its screens, how to reach each one, and the pop-ups that get in the way. Quern loads it every session, recognises which screen is showing, and checks that taps landed, so the agent stops relearning your app each time. See the app knowledge base guide.

How each of those works, with every log source and proxy option, is in What Quern does.

Once the server is installed and the MCP is registered, open your mobile project with your AI coding assistant (Claude Code, Cursor, etc.) and just ask it to do things:

"Boot an iPhone 16 simulator, make sure the proxy is capturing traffic, then build and install my app. Log in with testuser / password123 and give me a summary of all the API calls you see during login."

The agent will use Quern's MCP tools to boot the simulator, configure the proxy, install your app, drive the UI to log in, and then query the captured network traffic — all without you touching the simulator or pasting logs into chat.

Other things you can ask:

• "Take a screenshot and tell me what's on screen"
• "Mock the /api/users endpoint to return a 500 error and see how the app handles it"
• "Find the last crash report and figure out what caused it"
• "Set up the proxy on my physical iPhone and capture traffic while I browse"
• "Show me what analytics events get sent when I open the settings screen"
• "Open a live preview of my iPhone's screen so I can see what's happening"
• "Run the app on 3 simulators in parallel and compare the network traffic"

• macOS
• Python 3.11+
• Node.js 22.19+ to run; 22.23.4+, 24.22.1+ or 26.12.1+ for the fix to CVE-2026-111497 (quern warns on anything older)
• For iOS: Xcode and Command Line Tools
• For Android: Android Studio or adb via Homebrew

curl -fsSL https://quern.dev/install.sh | bash

This downloads the latest release to ~/.local/share/quern, creates a virtualenv, installs dependencies, checks system tools, registers the MCP server with Claude Code, installs a Claude Code pre-commit checklist hook, and adds quern to ~/.local/bin on your PATH.

After this, run quern from anywhere — you do not need to be in the install directory, and you do not need to know where it is. Everything below is written that way. If your shell reports command not found: quern in the session you installed from, run rehash (zsh) or open a new terminal: the shell caches where commands live and does not notice a new one appearing.

To install by hand, provision a machine with no terminal (quern setup -y), or uninstall, see Installing Quern. It also covers the pre-commit checklist hook, and how to turn it off.

Setup installs a Quern app in your menu bar, and for most people it is all they need after installing: start, stop and restart the server from it, with no terminal. It also shows the server's state, the active device and the proxy's port, opens a live screen mirror of a device, and picks the update channel. Quitting the app leaves the server running. See the Quern app guide.

From the terminal, or in a script:

quern start                # start as a background daemon
quern start -f             # run in the foreground (Ctrl-C to stop)
quern status               # check status
quern stop                 # stop
quern update               # update to latest release and rebuild
quern update --tools       # ...and upgrade external tools (pipx/brew) too
quern grant-full-perms     # allow all quern MCP tools in Claude Code without prompting
quern mcp-install          # register quern MCP server with AI coding tools
quern mcp-install --remote NAME   # ...pointed at a paired remote quern instead of this Mac's
quern uninstall            # remove Quern and its dependencies

The server prints connection info on startup — URL, API key, and proxy port. All state is stored in ~/.quern/. The full list of commands, and what each file there is for, is in the command reference.

The installer registers Quern's MCP server with Claude Code for you, so if that is your agent there is nothing to do. For another agent, register it with quern mcp-install and the agent's name: claude-desktop, cursor, codex or opencode, or all for every one of them.

quern mcp-install cursor    # one agent
quern mcp-install all       # Claude Code, Claude Desktop, Cursor, Codex and opencode

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

Tip: Call the ensure_server MCP tool first. It starts the server if it isn't running and returns connection info.

For writing scripts that perform repeatable actions available in Quern. These can augment or replace XCUITests if you wish

API_KEY=$(cat ~/.quern/api-key)

# Health check (no auth)
curl http://localhost:9110/health

# Tail recent logs
curl -H "Authorization: Bearer $API_KEY" \
     "http://localhost:9110/api/v1/logs/query?limit=20&level=error"

# Get an LLM-optimized summary
curl -H "Authorization: Bearer $API_KEY" \
     "http://localhost:9110/api/v1/logs/summary?window=5m"

All endpoints require Authorization: Bearer <key> except /, /health, /api/v1/health, /tools, /docs, /redoc, /openapi.json, and /api/v1/proxy/cert. The key is at ~/.quern/api-key; the server's URL and port are in ~/.quern/state.json.

Everything the MCP tools do is also reachable over plain HTTP. The complete reference — every tool, the endpoint behind it, and the endpoints that have no tool — is in the API reference.

When started as a daemon, Quern makes a single HTTPS request to quern.dev/api/check-update to check if a newer version is available. This request includes only your current version number (and commit SHA for git-based installs) — no device info, no IP logging, no telemetry. Cloudflare's edge analytics count daily requests, giving us a rough sense of how many people use Quern. No data is stored.

To turn it off, untick Check for updates automatically in the Quern app's Settings, or run quern set-update-check off. Channels, how updates handle dependencies and external tools, and quern doctor are covered in Updates and diagnostics.

# Clone and set up for development
git clone https://github.com/quern-dev/quern.git
cd quern
./quern setup                # creates venv, installs deps, checks tools, adds quern to ~/.local/bin
./quern mcp-install          # builds MCP server, adds to ~/.claude.json

# `./quern` while you are in the clone. After setup, `quern` works from
# anywhere — but keep using `./quern` here if you have several checkouts, since
# the bare name resolves to whichever one setup last pointed it at.

# Enable the repo's git hooks (one-time, per clone)
git config core.hooksPath scripts/git-hooks

# Run tests (venv auto-detected)
.venv/bin/pytest tests/ -v

# Build MCP server
cd mcp && npm run build

# Run with debug logging
quern start -f --verbose

Before changing anything, read CONTRIBUTING.md: the architecture, conventions and review process, including the repo's git hooks.

Apache 2.0. See LICENSE.