sim-mirror 0.2.0__py3-none-any.whl

sim_mirror/tools/registry.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Which tools an agent is offered, and running a call to one.
+
+Tools come from providers: the device tools always, the build tools while ``build.tools`` is on -- and a host or a
+later version adds a provider rather than editing this. A manifest leaves out a tool the scope's connector cannot
+serve (a view-only mirror offers no `sim_act`), and a call to one anyway is refused with why (`context.ready_device`).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Collection, Sequence
+from typing import Any, Protocol
+
+from sim_mirror.build.provider import BuildToolProvider
+from sim_mirror.build.xcodebuild import BuildRefused
+from sim_mirror.config.model import SimConfig
+from sim_mirror.connectors.base import Capability
+from sim_mirror.core.actions import ActionError
+from sim_mirror.platform.simctl import SimctlError
+from sim_mirror.tools import act, app, device, screenshot, snapshot
+from sim_mirror.tools.context import Tool, ToolContext
+from sim_mirror.tools.results import Result, ToolRefused, text
+from sim_mirror.tools.schemas import LOOK_AND_ACT
+
+
+class ToolProvider(Protocol):
+    @property
+    def tools(self) -> tuple[Tool, ...]:
+        """Every tool this provider has, whether offered now or not."""
+        ...
+
+    def offered(self, config: SimConfig) -> bool:
+        """Whether a scope with these settings is offered the tools."""
+        ...
+
+    def instructions(self, config: SimConfig) -> str:
+        """What an agent is told, for these settings."""
+        ...
+
+
+class DeviceToolProvider:
+    """Looking at and touching the device, and its apps: always offered."""
+
+    tools: tuple[Tool, ...] = (device.TOOL, snapshot.TOOL, screenshot.TOOL, act.TOOL, app.TOOL)
+
+    def offered(self, config: SimConfig) -> bool:
+        return True
+
+    def instructions(self, config: SimConfig) -> str:
+        return LOOK_AND_ACT
+
+
+class ToolRegistry:
+    def __init__(self, providers: Sequence[ToolProvider] = (DeviceToolProvider(), BuildToolProvider())) -> None:
+        self._providers = tuple(providers)
+        self._tools = {tool.name: tool for provider in self._providers for tool in provider.tools}
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def manifest(self, config: SimConfig, capabilities: Collection[Capability]) -> dict[str, Any]:
+        """The tools a scope with these settings is offered on a connector with these capabilities, and how to use
+        them."""
+        can = frozenset(capabilities)
+        offered = [provider for provider in self._providers if provider.offered(config)]
+        return {
+            "tools": [tool.listing() for provider in offered for tool in provider.tools if tool.needs <= can],
+            "instructions": "".join(provider.instructions(config) for provider in self._providers),
+        }
+
+    async def call(self, name: object, arguments: object, ctx: ToolContext) -> Result:
+        """Run one tool call, answering with its result -- or with why not, as an error result."""
+        tool = self._tools.get(name) if isinstance(name, str) else None
+        if tool is None:
+            return text(f"there is no tool named {name!r}", error=True)
+        if not isinstance(arguments, dict):
+            return text("arguments must be an object", error=True)
+        try:
+            return await tool.handler(arguments, dataclasses.replace(ctx, tool=tool))
+        except (ToolRefused, ActionError, SimctlError, BuildRefused) as exc:
+            return text(str(exc), error=True)

sim_mirror/tools/results.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A tool's answer, shaped as MCP's: content blocks, and whether it is an error.
+
+Text first: an image is sent only when one was asked for, because an image costs an agent far more than the lines that
+say what is on the screen (`perception.snapshot`).
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence
+from typing import Any
+
+Result = dict[str, Any]
+
+
+class ToolRefused(Exception):
+    """A call a tool will not make, said so the agent knows what to do instead."""
+
+
+def text(value: str, *, error: bool = False) -> Result:
+    return {"content": [{"type": "text", "text": value}], "isError": error}
+
+
+def images(caption: str, jpegs: Sequence[bytes]) -> Result:
+    """A caption, then each JPEG."""
+    blocks = [
+        {"type": "image", "data": base64.b64encode(jpeg).decode("ascii"), "mimeType": "image/jpeg"} for jpeg in jpegs
+    ]
+    return {"content": [{"type": "text", "text": caption}, *blocks], "isError": False}

sim_mirror/tools/schemas.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Every agent tool's description and input schema, and the instructions an MCP client is given -- the one catalogue.
+
+The tool names are part of SimMirror's public surface: an agent's prompts, a plugin's skill and a host's permissions
+name them. `scripts/gen_docs.py` writes `docs/reference/tools.md` from here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sim_mirror.build.destination import KEYS as DESTINATION_KEYS
+from sim_mirror.build.destination import TEXT_MAX as DESTINATION_TEXT_MAX
+from sim_mirror.build.xcodebuild import TEST_ID_MAX, TESTS_MAX
+from sim_mirror.validation import XCODE_NAME_MAX
+
+LAUNCH_ARGS_MAX = 20
+LOG_SINCE_S = (1, 300)
+LOG_LINES = (1, 200)
+#: How long a build call waits before answering with its build id; within a relay's own limit for a call.
+BUILD_WAIT_S = 120
+BUILD_WAIT_BOUNDS = (0, 600)
+#: How many extra goes a failing test may be given. Bounded low: each one runs the test again, and a test that needs
+#: four attempts has told you what you needed to know by the second.
+TEST_RETRIES_BOUNDS = (0, 3)
+
+
+def schema(properties: dict[str, Any], required: tuple[str, ...] = ()) -> dict[str, Any]:
+    return {"type": "object", "properties": properties, "required": list(required), "additionalProperties": False}
+
+
+_NAME: dict[str, Any] = {"type": "string", "maxLength": XCODE_NAME_MAX}
+_BUILD_PROPERTIES: dict[str, Any] = {
+    "scheme": {**_NAME, "description": "needed only when the project has several"},
+    "project": {"type": "string", "description": "a .xcodeproj in your folder, when it has several"},
+    "workspace": {"type": "string", "description": "a .xcworkspace in your folder, when it has several"},
+    "configuration": {**_NAME, "description": "Debug unless the settings chose another"},
+    "warnings": {"type": "boolean", "description": "list warnings too, not only errors"},
+    "wait_s": {"type": "integer", "minimum": BUILD_WAIT_BOUNDS[0], "maximum": BUILD_WAIT_BOUNDS[1]},
+    "build_id": {"type": "string", "description": "a run that answered still running: wait for it again"},
+}
+_TEST_IDS = {
+    "type": "array",
+    "items": {"type": "string", "maxLength": TEST_ID_MAX},
+    "maxItems": TESTS_MAX,
+    "description": "tests as a failure names them: AppTests, AppTests/LoginTests or AppTests/LoginTests/testLogin",
+}
+_DESTINATION_TEXT: dict[str, Any] = {"type": "string", "maxLength": DESTINATION_TEXT_MAX}
+_DESTINATION = {
+    "type": "object",
+    "properties": {key: _DESTINATION_TEXT for key in sorted(DESTINATION_KEYS)},
+    "additionalProperties": False,
+    "description": 'another simulator on this Mac: {"name": "iPhone 17"} or {"udid": ...}, with "runtime": '
+    '"iOS 26.5" to choose between simulators of one name',
+}
+
+#: Each tool's description and input schema, by name, in the order a manifest lists them.
+SCHEMAS: dict[str, tuple[str, dict[str, Any]]] = {
+    "sim_device": (
+        "Your iOS Simulator. info: which device, its state and the xcodebuild destination (does not start it). boot: "
+        "start it and wait until it is ready. restart: shut it down and start it again -- for when its apps stop "
+        "answering sim_snapshot, as they can after UI tests. appearance: light or dark.",
+        schema(
+            {
+                "action": {"type": "string", "enum": ["info", "boot", "restart", "appearance"]},
+                "mode": {"type": "string", "enum": ["light", "dark"]},
+            }
+        ),
+    ),
+    "sim_snapshot": (
+        "What is on screen as short lines -- one per button, field, text or heading, each with a ref (e4) and where a "
+        "tap lands. Cheap: prefer it to a screenshot. mode diff (default) gives only what changed since you last "
+        "looked; full gives the whole screen.",
+        schema({"mode": {"type": "string", "enum": ["diff", "full"]}}),
+    ),
+    "sim_screenshot": (
+        "A JPEG of the screen, or of a region (a ref, or {x, y, w, h} in points). frames > 1 takes that many, "
+        "interval_ms apart, to see an animation. Costs far more than sim_snapshot: use it to check how something "
+        "looks.",
+        schema(
+            {
+                "width": {"type": "integer", "minimum": 160, "maximum": 1200},
+                "region": {"oneOf": [{"type": "string"}, {"type": "object"}]},
+                "frames": {"type": "integer", "minimum": 1, "maximum": 6},
+                "interval_ms": {"type": "integer", "minimum": 50, "maximum": 2000},
+            }
+        ),
+    ),
+    "sim_act": (
+        "Touch the device: a batch of steps in one call, played in order, each drawn live for anyone watching. "
+        'Steps: {"tap": T}, {"long_press": T, "ms": 800}, {"swipe": {"from": T, "direction": "up"}} or {"swipe": '
+        '{"from": T, "to": [x, y]}}, {"drag": {"path": [[x, y], ...]}}, {"type": "Groceries", "into": T, "clear": '
+        'true, "submit": true} (the words to type are the value of "type"; typing adds to what a field already '
+        'holds, "clear": true replaces it), {"press": "home" | "lock" | "return" | "delete" | ...}, {"pause": ms}. A '
+        'key a step does not take is refused. T is a ref like "e4" or a point [x, y]. wait after the steps: {"for": '
+        'text}, {"gone": text} or {"settle_ms": 400} for an animation. Answers ok/error per step, then what changed '
+        "on screen.",
+        schema(
+            {
+                "steps": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object"}},
+                "wait": {"type": "object"},
+                "snapshot": {"type": "string", "enum": ["diff", "full", "none"]},
+            },
+            required=("steps",),
+        ),
+    ),
+    "sim_app": (
+        "Apps on the device. launch or terminate a bundle_id -- launching an app that is already running only brings "
+        "it to the front, so give relaunch: true to start it fresh; install a built .app (a path in a folder you may "
+        "install from, or DerivedData); open_url; logs: the device log for the last since_s seconds, for a bundle_id "
+        "(else errors and faults), optionally filtered.",
+        schema(
+            {
+                "action": {"type": "string", "enum": ["launch", "terminate", "install", "open_url", "logs"]},
+                "bundle_id": {"type": "string"},
+                "relaunch": {"type": "boolean"},
+                "path": {"type": "string"},
+                "url": {"type": "string"},
+                "args": {"type": "array", "items": {"type": "string"}, "maxItems": LAUNCH_ARGS_MAX},
+                "since_s": {"type": "integer", "minimum": LOG_SINCE_S[0], "maximum": LOG_SINCE_S[1]},
+                "filter": {"type": "string"},
+                "lines": {"type": "integer", "minimum": LOG_LINES[0], "maximum": LOG_LINES[1]},
+            },
+            required=("action",),
+        ),
+    ),
+    "sim_build_run": (
+        "Build the app in your folder with xcodebuild for your simulator, then install and launch it. Answers ok, or "
+        "each error as file:line and message. A build longer than wait_s answers with its build_id: call again with "
+        "that build_id to keep waiting.",
+        schema(_BUILD_PROPERTIES),
+    ),
+    "sim_test": (
+        "Run the scheme's tests (unit and UI) on your simulator, or on another one with destination. Answers with the "
+        "counts and each failure where it happened, named as only_testing takes it back -- or, when the tests do not "
+        "build, with the compile errors. While they run your device takes no sim_act steps. A test that fails, is "
+        "retried and then passes is reported as flaky: worth knowing before you treat a green run as a fix.",
+        schema(
+            {
+                **_BUILD_PROPERTIES,
+                "only_testing": _TEST_IDS,
+                "skip_testing": _TEST_IDS,
+                "test_plan": {
+                    **_NAME,
+                    "description": "one of the scheme's test plans; leave out to run what the scheme runs by default",
+                },
+                "retries": {
+                    "type": "integer",
+                    "minimum": TEST_RETRIES_BOUNDS[0],
+                    "maximum": TEST_RETRIES_BOUNDS[1],
+                    "description": "more goes for a failing test",
+                },
+                "destination": _DESTINATION,
+            }
+        ),
+    ),
+}
+
+LOOK_AND_ACT = (
+    "These tools drive your iOS Simulator while anyone watching sees every gesture live. Look with sim_snapshot "
+    "(cheap text) before acting, then act with its refs in one sim_act batch; take sim_screenshot only to check how "
+    "something looks or moves. The device boots on first use. "
+)
+SHELL_INSTRUCTIONS = (
+    "Build from your shell with xcodebuild and the destination sim_device info gives, then sim_app install and launch."
+)
+BUILD_INSTRUCTIONS = (
+    "Build, install and launch the app with sim_build_run, and run its tests with sim_test: both answer with only what "
+    "failed and where."
+)

sim_mirror/tools/screenshot.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sim_screenshot`: a JPEG of the screen or a region of it, or several to see an animation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sim_mirror.connectors.base import Capability
+from sim_mirror.tools.context import ToolContext, make_tool, ready_device
+from sim_mirror.tools.results import Result, images
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> Result:
+    instance = await ready_device(ctx)
+    shots = await ctx.actions.screenshots(
+        instance,
+        ctx.caller,
+        width=args.get("width", ctx.config.screenshot_width),
+        region=args.get("region"),
+        frames=args.get("frames", 1),
+        interval_ms=args.get("interval_ms"),
+        max_elements=ctx.config.snapshot_max_elements,
+    )
+    caption = f"{len(shots)} frame{'s' if len(shots) != 1 else ''} · {shots[0].width}x{shots[0].height}px"
+    return images(caption, [shot.jpeg for shot in shots])
+
+
+TOOL = make_tool("sim_screenshot", (Capability.SCREENSHOT,), run)

sim_mirror/tools/snapshot.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sim_snapshot`: the screen as short lines with refs, or what changed since the agent last looked."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sim_mirror.connectors.base import Capability
+from sim_mirror.tools.context import ToolContext, make_tool, ready_device
+from sim_mirror.tools.results import Result, ToolRefused, text
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> Result:
+    mode = args.get("mode", "diff")
+    if mode not in ("diff", "full"):
+        raise ToolRefused("mode is diff or full")
+    instance = await ready_device(ctx)
+    return text(
+        await ctx.actions.snapshot(instance, ctx.caller, mode=mode, max_elements=ctx.config.snapshot_max_elements)
+    )
+
+
+TOOL = make_tool("sim_snapshot", (Capability.ELEMENT_TREE,), run)

sim_mirror/validation.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Checking the values an agent's call names, with messages that say what would do."""
+
+from __future__ import annotations
+
+from typing import TypeGuard
+
+#: The longest scheme, build configuration or test plan name a call or a setting may give.
+XCODE_NAME_MAX = 128
+
+
+class Invalid(ValueError):
+    """A value a call named that cannot be used, said so the caller knows what to give instead."""
+
+
+def is_number(value: object) -> bool:
+    """A real number: an int or a float, never a bool."""
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def is_xcode_name(value: object) -> TypeGuard[str]:
+    """A name Xcode lets a person give a scheme, a build configuration or a test plan -- `App (Staging)` as much as
+    `Debug` -- that reaches xcodebuild as nothing but that name: one printable line, trimmed, and not an option.
+
+    xcodebuild is run with an argument vector, never a shell, so punctuation means nothing to it; a leading `-` would,
+    as the option after `-scheme`. Anything narrower refuses names Xcode made, and an agent told "it has App
+    (Staging)" and then refused for using it can only try again.
+    """
+    return (
+        isinstance(value, str)
+        and 0 < len(value) <= XCODE_NAME_MAX
+        and value.isprintable()
+        and value == value.strip()
+        and not value.startswith("-")
+    )
+
+
+def whole(value: object, default: int, bounds: tuple[int, int], name: str, unit: str | None = "milliseconds") -> int:
+    """`value` as a whole number within `bounds`, `default` when it is None. Raises `Invalid` otherwise."""
+    if value is None:
+        return default
+    low, high = bounds
+    if not isinstance(value, int) or isinstance(value, bool) or not low <= value <= high:
+        of_unit = f" of {unit}" if unit else ""
+        raise Invalid(f"{name} must be a whole number{of_unit} from {low} to {high}")
+    return value

sim_mirror-0.2.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: sim-mirror
+Version: 0.2.0
+Summary: Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.
+Project-URL: Homepage, https://github.com/AndrewKochulab/sim-mirror
+Project-URL: Documentation, https://github.com/AndrewKochulab/sim-mirror/tree/main/docs
+Project-URL: Issues, https://github.com/AndrewKochulab/sim-mirror/issues
+Project-URL: Changelog, https://github.com/AndrewKochulab/sim-mirror/blob/main/CHANGELOG.md
+Author: Andrew Kochulab
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_LICENSES.md
+Keywords: ai-agents,claude-code,ios-simulator,mcp,screen-mirroring,simulator,ui-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: grpclib<0.5,>=0.4.9
+Requires-Dist: protobuf<8,>=7.36
+Requires-Dist: tomli>=2; python_version < '3.11'
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: uvicorn[standard]>=0.35
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AndrewKochulab/sim-mirror -->
+
+# SimMirror
+
+**Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.**
+
+[![CI](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml/badge.svg)](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/AndrewKochulab/sim-mirror?include_prereleases&sort=semver)](https://github.com/AndrewKochulab/sim-mirror/releases)
+
+![A Claude Code session tapping through Settings on an iPhone 17 Pro simulator in the viewer, its cursor named
+and drawn before each tap](docs/media/hero.gif)
+
+A live iOS Simulator in any browser tab or web page, an animated cursor that shows exactly what your AI agent is about
+to tap, and token-efficient UI snapshots so agents read the screen as compact text instead of screenshots. Works with
+Claude Code, Codex, Cursor and any other MCP client.
+
+> **Status: first public preview (v0.1).** The tools, the viewer and the protocol work today; the embedding API and
+> protocol become stable with v1.0.
+
+## Why SimMirror
+
+- **See the simulator anywhere.** A live H.264 or JPEG stream in a Chrome tab, an iframe or a `<sim-mirror>` web
+  component, with touch, scrolling, typing, hardware buttons and light and dark mode.
+- **Watch what the agent does.** Every agent gesture is announced before it lands, and the viewer's cursor glides to
+  the spot first -- so you can follow along, and step in: an agent waits for your hand to be still.
+- **Spend fewer tokens.** Agents read accessibility snapshots with stable element refs and diffs between screens, act
+  in batches with waits, and reach for a screenshot only when a question is visual.
+
+## Install
+
+**Claude Code**, with the plugin (tools, a skill that teaches snapshot-first use, and `/sim-mirror:open`):
+
+```
+/plugin marketplace add AndrewKochulab/sim-mirror
+/plugin install sim-mirror@sim-mirror
+```
+
+**Any MCP client**, as a stdio server:
+
+```sh
+claude mcp add sim-mirror -- uvx --from git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror mcp
+```
+
+Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
+[other clients](docs/clients/other-mcp.md).
+
+**The command**, for `sim-mirror open`, `doctor` and the rest:
+
+```sh
+uv tool install git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0
+```
+
+**The viewer library**, for your own pages: the npm package `@andrewkochulab/sim-mirror`, attached to each
+[release](https://github.com/AndrewKochulab/sim-mirror/releases). Homebrew and PyPI come with v1.0.
+
+**Requirements:** an Apple Silicon Mac, Xcode 26 or later, [uv](https://docs.astral.sh/uv/), and for touching the
+screen, idb_companion (`brew install facebook/fb/idb-companion`). Details in [Installation](docs/installation.md).
+
+## Quickstart
+
+```sh
+sim-mirror doctor     # check this Mac, ending with a real tap on a simulator
+sim-mirror open       # this project's simulator, live in a browser tab
+```
+
+Then ask your agent:
+
+> Open Settings → General → About and tell me which iOS version this simulator runs. Use sim_snapshot rather than
+> screenshots.
+
+[Getting started](docs/getting-started.md) explains what happens along the way.
+
+## Features
+
+**Live viewer.** H.264 through WebCodecs where the page can decode it, JPEG otherwise, negotiated per connection.
+Touch, drag, scroll, typing and paste, Home and Lock, light and dark, and a device picker. It reconnects by itself
+after a blip and says plainly when the simulator is off.
+
+**Agent cursor.** Every agent gesture -- tap, long press, swipe, drag, typing -- reaches the viewer before it lands, and
+the viewer's own pointer glides there first (`agent.cursor_lead_ms`). Never the Mac's pointer.
+
+**Screen understanding.** A snapshot is a few lines -- `e2 button "General" (201,319)` -- with refs that stay with their
+elements across scrolls, a digest, and diffs. `sim_act` plays up to 20 steps in one call and waits for text, its
+absence, or the screen to settle. See [Screen understanding](docs/screen-understanding.md).
+
+**Connectors.** idb_companion gives full control; without it the simctl connector still mirrors the screen, view-only,
+and says why. More connectors plug in through an entry point. See [Connectors](docs/connectors.md).
+
+**Embedding.** An [iframe](docs/embedding/iframe.md) with a one-shot ticket, the
+[`<sim-mirror>` element](docs/embedding/web-component.md) themed with CSS custom properties, or SimMirror
+[inside a Python application](docs/embedding/python-fastapi.md) with its own sign-in.
+
+**Settings panel.** `sim-mirror open --settings` puts every setting a click away in the viewer, a tab per section,
+saved for one project or all of them and applied before it says so. Settings that decide what runs or who may reach
+the daemon wait for a code from `sim-mirror settings confirm`. See [The settings panel](docs/settings.md).
+
+**Doctor.** Checks Xcode, its Simulator frameworks, runtimes, idb_companion, Device Hub and the desktop session, then
+proves a tap reaches a simulator. See [the doctor](docs/doctor.md).
+
+**Security.** Loopback only, a Host allowlist, exact Origin checks, CORS and framing only for origins you list, hashed
+scoped tokens, and one-shot codes in URL fragments. See [Security](docs/security.md).
+
+**Build and test.** `sim_build_run` and `sim_test` build with xcodebuild for the agent's simulator, install and
+launch, and answer with only what failed and where -- each failing test named so it can be run again alone, and on
+another simulator when asked. Off by default, since they run commands: `sim-mirror config set build.tools true`.
+
+## Measure the token cost
+
+`benchmarks/tool_budget.py` calls each read-only tool through the same MCP relay a client uses and prints each answer's
+bytes, estimated tokens and latency on your own screens; see [the token budget example](examples/token-budget/). On
+an iPhone 17 Pro simulator (iOS 26.5, idb connector) showing Settings → General, 5 calls each (2026-09-16):
+
+| Call | Tool | Bytes | Tokens (est.) | p50 ms | p95 ms |
+|---|---|---:|---:|---:|---:|
+| device info | `sim_device` | 265 | 46 | 2.9 | 3.6 |
+| snapshot, full | `sim_snapshot` | 561 | 112 | 64.8 | 76.4 |
+| snapshot, diff of an unchanged screen | `sim_snapshot` | 83 | 5 | 63.2 | 64.8 |
+| screenshot, 400 px wide | `sim_screenshot` | 62222 | 469 | 8.2 | 8.9 |
+| screenshot, 1200 px wide | `sim_screenshot` | 276472 | 4181 | 20.4 | 21.9 |
+
+Bytes are the whole answer, an image's base64 included; tokens are estimates (text at about 4 characters a token,
+an image at about 750 pixels a token).
+
+## Compatibility
+
+| | Expected to work |
+|---|---|
+| macOS | 26 (15 with Xcode 16.4, view-only) |
+| Xcode | 26 and 27 |
+| Connectors | idb_companion 1.5 (full control), simctl (view-only) |
+| Clients | Claude Code, Codex, Cursor, any stdio MCP client |
+| Browsers | Chrome, Safari, Firefox, Edge |
+
+Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
+
+While SimMirror is `0.x`, the tools, the protocol and the embedding API can still change in a minor release, and the
+changelog says when they do; from 1.0 they are held to [what SimMirror promises not to break](docs/stability.md). Pin
+an exact version either way.
+
+## Documentation
+
+[Everything](docs/README.md): getting started, clients, embedding, screen understanding, connectors, security,
+architecture, and the reference for [tools](docs/reference/tools.md), [configuration](docs/reference/configuration.md),
+the [command line](docs/reference/cli.md) and the [protocol](docs/reference/protocol.md).
+
+## Roadmap
+
+| Milestone | What it brings |
+|---|---|
+| **v0.1** (preview) | Live viewer, agent cursor, person and agent control, MCP tools, `sim-mirror doctor`, idb and simctl connectors, build and test as a preview |
+| **v1.0** | Stable protocol and embedding API, PyPI and npm packages, the MCP registry |
+| **v1.1** | Build, run and test tools become stable |
+| **v1.2** | Richer screen understanding, a native Swift helper, Xcode 27 `mcpbridge` connector, one shared daemon for many hosts |
+| **v2.0** | Real iPhones: view, install and launch without signing; full control through WebDriverAgent |
+| **Android** | Android emulator support with the same viewer, cursor and tools |
+| **Homebrew** | `brew install andrewkochulab/tap/sim-mirror`, right after v1.0 |
+| **Website & launch** | Landing page, video tutorials and guides |
+
+See [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/AndrewKochulab/sim-mirror/milestones). How
+SimMirror relates to other tools is in [Comparison](docs/comparison.md).
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md); AI
+coding agents read [AGENTS.md](AGENTS.md). Report security issues privately as described in [SECURITY.md](SECURITY.md).
+Questions go to [Discussions](https://github.com/AndrewKochulab/sim-mirror/discussions).
+
+## License
+
+[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
+
+SimMirror is an independent project, not affiliated with Apple or Anthropic. iOS, iPhone, Xcode and Simulator are
+trademarks of Apple Inc.; Claude and Claude Code are trademarks of Anthropic PBC.