iOS

iCATBox Opens Up a Unified macOS Console for iOS Debugging

By VicLi · Oct 26, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Routine iOS debugging hops between Terminal, Xcode, and Finder get consolidated into one open-source console, and the codebase demonstrates a clean split between generic tooling and project-specific configuration that other internal tools can copy.

Summary

iCATBox bundles routine iOS debugging actions into one SwiftUI/AppKit console. Developers pick a project and device, then run install, launch, screenshot, sandbox file edits, route jumps, log streaming, crash symbolication, and signing checks without leaving Xcode's orbit. It drives simulators through simctl and real devices through devicectl, with no third-party Swift dependencies, and the whole thing is MIT-licensed.

The tool separates generic tooling from per-project data. Public capabilities include route jumping, bridge code generation, Flutter utilities, and a declarative analytics adapter, while each project's routes, bridge methods, domains, and interface parameters stay in local JSON imports. Route definitions can even be subscribed from remote JSON/Markdown/HTML docs, merged by URL with a 30-minute auto-check and a guard against stale writes when the user switches projects mid-request.

The first public release is 1.2.0, built from a clean clone via a scripted pipeline that runs config regression checks and produces a universal (Apple Silicon + Intel) app with SHA-256 checksums. It's ad-hoc signed and not notarized, so users must verify checksums and may need to override Gatekeeper.

Takeaways

— iCATBox is open-sourced under MIT, first public release 1.2.0.

— Built with SwiftUI and AppKit; uses simctl for simulators and devicectl for real devices; no third-party Swift dependencies.

— Covers install/launch/terminate/screenshot/record, sandbox open/pull/write/backup/restore, route links, environment mapping, favorites, subscriptions, regression screenshots, log streaming, crash reports/symbolication, scripts, dependencies, signing certs, profiles, pre-release checks, hybrid bridge, Flutter, and React Native workflows.

— Routes are user-maintained and can be subscribed from JSON, Markdown, or HTML documents; structured routes.json is recommended.

— Route merging dedupes by URL, preserves existing titles, does not delete local routes missing from the source, and auto-sync can check every 30 minutes.

— Async network results re-validate project ID, subscription address, and import rules before merging to avoid writing to a switched project.

— The public repo contains only generic UI and tool dispatch; project-specific data (links, bridge methods, page names, domains, API params) is imported via local JSON.

— Analytics debugging uses a declarative adapter mapping endpoint path, parameters, response rows, and fields; only form POST and field remapping are supported, with no JavaScript execution.

— Tokens, cookies, and passwords are excluded from exported project configuration.

— Build verification includes config regression tests and GitHub Actions covering old config decoding, JSON roundtrip, route parsing, domain boundaries, duplicate links, field mapping, parameter placeholders, and cookie scope.

— Release process builds a universal Apple Silicon + Intel app, generates ZIP, DMG, and SHA-256 checksums, and preserves historical versions by tag.

— Minimum requirements: macOS 13+ and Xcode; real-device features depend on devicectl availability and device trust.

— The public installer is ad-hoc signed, not Apple Developer ID notarized, so users must verify checksums and may need to override Gatekeeper.

Conclusions

Separating generic tool capabilities from project-specific data is a clean template for open-sourcing an internal dev tool without leaking business config or hardcoded vendor assumptions.

Re-validating project context after an async network response is a correctness detail many similar tools ignore; without it, stale route merge results would corrupt the wrong project.

The deliberate limitation of the analytics adapter to form POST and field remapping, with no JavaScript execution, keeps the tool predictable and safe, but also walls off any backend with custom encryption or transport.

Shipping ad-hoc signed and un-notarized installers is a real adoption barrier; users must trust checksums and bypass Gatekeeper, which many will not do casually.

Concepts & terms

simctl

Xcode's command-line interface for controlling iOS simulators, used to boot, shut down, install apps, launch, take screenshots, and more.

devicectl

Xcode's command-line tool for interacting with physical iOS devices, providing install, launch, log, and other operations; introduced in Xcode 15.

Ad-hoc signing

Code signing performed without an Apple Developer Program certificate. macOS treats such apps as untrusted, so users must verify checksums and manually override Gatekeeper to run them.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗