Astrolabe

English | 简体中文

Astrolabe is a runtime UI inspection tool for AI coding agents. It combines a Swift CLI, a local MCP server, and a packaged agent skill to inspect and verify running mobile interfaces.

Android View inspection is supported through Astrolabe Runtime for Android 2.0.

Features

• Discover supported apps running in iOS simulators, Android emulators, or on USB-connected devices.

• Inspect UIKit and Android View hierarchies, node frames, visibility, text, styles, semantic roles, and detailed runtime attributes.

• Capture native-resolution screenshots and compare them with expected images or recorded baselines.

• Query nodes and verify style, layout, and node-detail expectations.

• Keep related hierarchy operations bound to a frozen page snapshot.

• Apply allowlisted, in-memory presentation patches in Debug builds and revert them without changing source code or persistent application state.

• Expose the same inspection workflow through CLI commands, MCP tools, and the bundled astrolabe skill.

Related MCP server: iOS Device Control MCP Server

Requirements

• macOS 13 or later

• Swift 5.9 or later

• Node.js 22 or later

• Android Platform Tools (ADB) when inspecting Android apps

• A supported app with an Astrolabe Runtime SDK enabled in Debug builds

Installation

Clone the repository, then install Astrolabe for the AI clients you use:

git clone https://github.com/regulusleow/astrolabe.git
cd astrolabe
npm run install:codex
npm run install:opencode
npm run install:claude-code

Codex, OpenCode, and Claude Code can be installed independently or together. A multi-client installation builds the shared package once:

node scripts/install.mjs --client codex --client opencode --client claude-code

The installer places shared artifacts under ~/.astrolabe/package and links the bundled skill into each client's supported user-level skill directory. Each client adapter owns only its MCP configuration: Codex uses ~/.codex/config.toml, OpenCode uses ~/.config/opencode/opencode.json, and Claude Code uses ~/.claude.json. Installing or uninstalling one client does not remove another client's configuration or required skill link.

Restart the configured AI clients after installation.

Installation management commands:

npm run reinstall:codex
npm run update:codex
npm run check:codex
npm run uninstall:codex

npm run reinstall:opencode
npm run update:opencode
npm run check:opencode
npm run uninstall:opencode

npm run reinstall:claude-code
npm run update:claude-code
npm run check:claude-code
npm run uninstall:claude-code

Quick Start

Launch a Debug build that includes a supported Runtime SDK, then discover it:

astrolabe list-apps --json

Use the returned appId with inspection commands:

astrolabe inspect-screen <app-id> --json
astrolabe capture-hierarchy <app-id> --json
astrolabe find-nodes <app-id> --role text --visible-only --limit 20 --json
astrolabe inspect-node <app-id> --oid <oid> --json
astrolabe node-detail <app-id> <oid> --json
astrolabe capture-screenshot <app-id> --output /tmp/screen.png --source auto --json

Hierarchy commands return a snapshotId. Pass it to subsequent hierarchy, node, style, and layout commands to keep the workflow bound to the captured page. Screenshot and visual comparison commands always use the latest screen.

The installed MCP server exposes the same capabilities to Codex, OpenCode, and Claude Code. The bundled skill guides app discovery, snapshot reuse, node selection, runtime checks, screenshots, visual comparison, and temporary presentation experiments.

Development

Install dependencies and run the test suites:

npm ci
npm --prefix mcp-adapter ci
npm test
swift test --parallel

Build the Release CLI:

swift build -c release --product astrolabe

Run end-to-end smoke tests with a supported app running:

npm run test:smoke
npm run test:usb

Repositories

• astrolabe-protocol: platform-neutral Wire Protocol, Schemas, Fixtures, and Swift/Kotlin DTOs and Codecs.

• astrolabe-runtime-ios: Debug-only UIKit Runtime SDK.

• astrolabe-runtime-android: Debug-only Android View Runtime SDK.

Astrolabe Host consumes the shared protocol directly and does not depend on a platform Runtime implementation package.

Roadmap

• Jetpack Compose Runtime inspection.

• Integrations for additional AI coding platforms.

License

Astrolabe is available under the Apache License 2.0. Components derived from third-party projects remain subject to their original licenses; see THIRD_PARTY_NOTICES for details.