The detailed reference for people changing iOS Studio. Start with ARCHITECTURE.md (the map: processes, layers, patterns) and CONTRIBUTING.md (setup, running in demo mode, tests, recipes, PR rules).
shell.qml window, sidebar, page loader, global keys, IPC handler, overlays
AppState.qml `app`: current page, nav(), toast(), confirm(), settings, every service
core/ non-visual QML plumbing
Cli.qml, Stream.qml one-shot and streaming helper calls
Resource.qml one piece of backend data and its state
Host.qml overlay stack (singleton)
CommandCheck.qml cached `command -v` (singleton)
ThemeWatcher.qml follows the Omarchy theme
lib/Model.js pure helpers: glyphs, PAGES, SHORTCUTS, formatting, run preset rules
services/ one service per area: Account, Device, Log, Project, Setup, Toolchain, Watch (+ PathResults)
pages/ one page per sidebar entry
components/ UI building blocks, one folder per area (APIs in components.md)
common/ shared widgets: Card, ListRow, Sheet, StateView, Theme, LogView, …
device/ the iPhone page: hero, tabs (Device*View), app data, debug, perf chart, screenshot compare
projects/ the Projects page: cards, build panel, sheets (new, packages, format, presets, build settings)
logs/ the Logs page: device/console/build log tabs, crash browser
account/ the Apple ID page: sign-in sheet, revoke warning
settings/ Settings parts: AI agents, editor setup
helper/
run.py starts a module of the package (`python3 -I helper/run.py iosstudio …`); bin/ uses it
root/ scripts that run as root through pkexec (root-tasks.sh, the Swift hold hook, xcspec.py)
iosstudio/ the helper and the device daemon: one stdlib-only package (the real daemon adds pymobiledevice3)
__main__.py, cli.py `<group> <action>` -> features/ module (MODULES), imported lazily
core/ shared by everything; used qualified (`output.ok(…)`, `appdirs.STATE_DIR`) so tests can patch it
output.py the output protocol: ok()/fail()/event()/step()/progress()/log()/done()/prompt(), HelperError, fix()
subproc.py tool_env(kind), run_cmd(), run_group(), Runner (streaming, prompts, cancel, timeout, group kill),
stream_cmd(), kill_group(), which(), pymd3_python(), demo_delay()
fileio.py atomic_write(), locks, load_json()/save_json(), tail_text(), dir_size(), prune()
appdirs.py XDG folders read at call time, sdk_bundle(), tilde(), REPO, settings(), project roots, cache_get()/cache_put()
flags.py parse_flags(): --key value / --flag -> dict
jsonc.py JSON with comments, span-preserving (editor and agent configs)
xtool_yml.py xtool.yml reader and a key update that keeps the rest of the file
features/ one module or package per helper group, plus logic the daemon features share
projects/ groups `projects`, `build`: model.py (discovery, templates), store.py (projects.json, builds.json,
build-logs/), build.py (the build flow), runner.py (BuildRunner: xtool output -> events),
renew.py (auto-renew timer), commands.py (flags in, JSON out)
setup/ groups `setup`, `toolchain`: facts.py, steps.py, installers.py, downloads.py, sources.py, pins.py,
xip.py, toolchain.py, runtime.py, commands.py
watch/ group `watch` (compile on save): fswatch.py (inotify/polling), watcher.py (scheduler),
builds.py, lifecycle.py, runtime.py (lock/status files), commands.py
packages/ group `packages`: manifest.py, manifest_edit.py, add.py, update.py, project.py, swift.py,
demo_mode.py, commands.py
hotreload/ group `hotreload` (hot reload on the iPhone): project_setup.py (the Package.swift block), session.py,
state.py (runtime files), buildinfo.py (baseline), patch.py, checks.py, macho.py, signing.py, commands.py
editor_setup/ group `editor`: editors.py (once per machine), project.py (per project), actions.py, env.py, demo.py
agents/ group `agents` (connect the MCP server to AI tools): clients.py, writers.py, server.py, rpc.py, demo.py
account.py group `account` (xtool)
appconfig.py group `app`: launcher keybinding, window rule, opacity, about
debugger.py group `debug` (LLDB on your own apps); lldb_driver.py runs inside lldb's Python
editor_debug*.py `debug editor-config` / `editor` / `editor-status`: Debug in editor (VS Code, Zed via lldb-dap)
screenshots.py group `screenshots`: baselines and visual diffs
format.py `projects format` / `format-lint`: swift-format and SwiftLint
app_icon.py `projects icon` / `pick-file`: the app icon from any image (Pillow or ImageMagick)
build_settings.py, run_presets.py, project_check.py, diagnostics.py used by projects/
agent_instructions.py AGENTS.md / CLAUDE.md for `projects new` and `projects convert` (never overwrites)
app_data.py plist <-> JSON, store summaries and rows, reset plans (shared with the daemons)
ui_inspect.py UI inspection without a device (shared with device/features/ui/)
crash_symbols.py keeps each build's binary + dSYM, resolves crash frames to file:line
config_files.py edits other programs' config files without losing anything
xip_version.py the Xcode version inside a .xip, without unpacking it
demo/ the helper's demo mode: demo.py (router + made-up answers), demo_art.py, debugger_demo.py, hot_reload.py
device/ the device daemon, its broker and client
protocol.py the wire format (JSON lines, errors)
backend.py the Backend base class: what the broker calls on a daemon
kit.py FeatureRegistry + load_features(), Resources, CursorRing
broker.py the shared daemon: socket, clients, events, syslog fan-out, idle exit
client.py asyncio client (stdlib only, no package imports: the MCP server loads it by path); runtime_base()
link.py USB and Wi-Fi transport; network.py, models.py shared helpers
real/ the real daemon: daemon.py (session, tunnel, dispatch, --serve/--once), core.py (what features import)
demo/ the made-up iPhone: daemon.py (DemoBackend), core.py (its shared state)
features/<name>/ real.py + demo.py (+ core.py and helpers): appdata, apps (index.py = AppIndex, lookup.py,
install.py), cameratest, conditions, console, crashes, ddi, debug, files, hotreload, location, metrics
(stats.py), mirror, pairing, pcap, profiles, screen, syslog, ui
mcp/
iosstudio_mcp/ the MCP server (see mcp.md#for-tool-authors)
server.py, state.py, helper.py, models.py, prompts.py, resources.py, guide.md
core/ registry.py (@tool, slim_schemas), jobs.py (JobManager), job_status.py, deadline.py (25 s),
budget.py, params.py, errors.py
backends/ device.py, projects.py, builds.py, console.py, crashes.py
tools/ one module per area (101 tools), listed in tools/__init__.py MODULES
pyproject.toml its dependencies (installed into a private venv on first run)
evaluation.xml, EVALUATION.md demo-mode evaluation questions and results
bin/ ios-studio (launcher), iosstudio-helper, iosstudio-deviced, iosstudio-mcp
templates/ Swift app templates used by New app; agent-instructions/ holds AGENTS.md and CLAUDE.md for new projects;
hot-reload/ is the runtime package hot reload copies into a project (bump version.txt when it changes)
tests/ helper/, cli/, mcp/, qml/, e2e/, support/ (shared fakes), fixtures/<area>/
pyproject.toml dev tools only (pytest and ruff config, the dev dependency group); not a package
install.sh launcher integration (and --uninstall)
.github/ CI and release workflows, release-note categories, scripts/check-version.sh
QML imports between these folders are relative, so qmllint can follow them: a page imports
"../components/common" and its own area folder, a component in components/device/ imports "../common"
(and "../../core" if it uses Stream, Resource, Host or CommandCheck), and everything imports
"<up>/lib/Model.js" as Model. Files in the same folder see each other without an import. Quickshell only
resolves folders it found by following imports from shell.qml; pages load by URL, so shell.qml imports
"pages" to make Quickshell scan them (and through them every components/ folder). A new folder must be
imported from a file that is already reached, or its types are "not a type" at runtime.
shell.qml creates one AppState (app), and AppState creates every service on it: app.setup, app.toolchain, app.account, app.device, app.projects, app.logs, app.watch. Each page gets required property var app. Every service exposes status (unknown, loading, ready, needs-setup, error), a summary for the Home page and sidebar badges, and refresh().
The app doesn't ship its own widget library. install.sh creates two symlinks in the repo:
Commons -> $OMARCHY_PATH/shell/Commons
Ui -> $OMARCHY_PATH/shell/Ui
QML then imports them as qs.Commons and qs.Ui, the same modules the Omarchy bar uses. Colours come from Commons.Color.*, sizes from Style.font.*, spacing from Style.spacing.*, radius from Style.cornerRadius. Don't hard-code pixels or colours. Both links are gitignored, so run install.sh after cloning.
Theme changes reach the window two ways: ThemeWatcher.qml watches the theme itself, and install.sh adds an Omarchy theme-set hook that calls qs ipc -p <repo> call iosstudio applyTheme.
bin/iosstudio-helper <group> <action> [--flag value ...]
Groups and their modules are in MODULES in helper/iosstudio/cli.py: setup, toolchain (features/setup/), account, projects, build (features/projects/), app (appconfig.py), agents (features/agents/, see mcp.md), debug (debugger.py; its editor* actions in editor_debug.py and editor_debug_bridge.py, see features/editor-debugging.md), screenshots, editor (features/editor_setup/), watch (features/watch/), packages (features/packages/) and hotreload (features/hotreload/, see features/hot-reload.md). format and format-lint are short for projects format / projects format-lint. Each feature's commands and flags are in its page under features/. cli.py imports modules lazily, so one broken module doesn't take the others down. With IOSSTUDIO_DEMO set, every command goes to demo/demo.py instead.
A one-shot command prints exactly one JSON object and exits 0 (ok), 1 (handled error) or 2 (bad usage):
{"ok": true, "data": {}}
{"ok": false, "error": {"code": "not-signed-in", "message": "You're not signed in to your Apple ID.",
"fix": {"label": "Sign in", "page": "account", "action": "signin"}}}message is written for end users. fix deep-links the UI with page plus an optional step, action or url. Secrets (password, 2FA code) only travel over stdin, never argv.
Long jobs (installs, builds, sign-in) stream JSON lines: step, progress, log, notice, prompt and a final done. The UI answers a prompt by writing {"prompt": "<id>", "value": "..."} to stdin. Stream.qml handles this for every service. The Setup-specific events are listed in setup-steps.md.
Root work goes through one pkexec helper/root/root-tasks.sh <flags> per step, so the user sees one password prompt. Never sudo: there's no terminal. makepkg runs as the user.
services/DeviceService.qml starts bin/iosstudio-deviced when the app opens. That process is only a stdio bridge. The daemon itself is a shared broker on $XDG_RUNTIME_DIR/ios-studio/deviced.sock (helper/iosstudio/device/broker.py, with real/daemon.py or demo/daemon.py as its backend). A process started without XDG_RUNTIME_DIR (the MCP SDK's stdio_client drops it) uses /run/user/<uid> when that folder exists and is yours, so it still finds the app's daemon; only without it does everything fall back to /tmp/ios-studio-<uid> (client.runtime_base(), also used by watch mode). The bridge starts it if it isn't running, and it exits 120 s after its last client leaves, so the app and the MCP server (helper/iosstudio/device/client.py) share one tunnel to the phone. Demo mode uses its own socket under $XDG_RUNTIME_DIR/ios-studio-demo/. Diagnostics go to deviced.log next to the socket.
Requests and replies are JSON lines with an id. The daemon also pushes events such as devices, connection and syslog. Pages call it through app.device.request(cmd, args, callback) and listen on app.device.daemonEvent(name, data). The Logs page uses the same daemon for the live log and crash reports.
The daemon also has a --once <cmd> '<json>' mode for background jobs (the daily auto-renew timer uses it to install), and it writes the last known device state to ~/.local/state/ios-studio/device.json.
Every command and event is documented in deviced-protocol.md.
real/daemon.py is only the core. Each feature group is a folder helper/iosstudio/device/features/<name>/ with real.py (the phone) and demo.py (the made-up iPhone) side by side, plus any shared logic (core.py, or named helpers such as apps/index.py). At start each daemon imports its side of every folder (kit.load_features) and calls its register(reg). When a module fails to import or register, the daemon logs the traceback to deviced.log, skips it and keeps serving the rest. daemon.features lists what loaded, what failed and which module owns each command. A command name that is already taken makes the second module fail, so two features can't silently shadow each other. Real and demo must register the same names: tests/helper/test_device_protocol.py::Parity checks it.
A feature module:
# helper/iosstudio/device/features/perf/real.py
from iosstudio.device.real.core import emit, err # never import real.daemon (it runs as __main__)
from iosstudio.device.kit import CursorRing
def register(reg):
ring = CursorRing(max_items=5000, max_bytes=4 << 20)
@reg.command("perf.start")
async def start(d, a): # d: the Daemon, a: the request args
s = d.need_session(a) # raises no-device / bad-args
async def open_():
... # start sampling, return a handle
async def close(handle, reason): # reason: released, client, tunnel, session, shutdown, timeout
...
await d.resources.acquire("perf", d.client(), open_, close, scope="tunnel", timeout=600)
return {"running": True}
@reg.command("perf.read")
async def read(d, a):
return await ring.wait_read(a.get("cursor"), timeout=min(float(a.get("wait", 0)), 20))
@reg.on_tunnel_drop # also: on_client_gone, on_session_end, on_shutdown
def dropped(d, session): ...
@reg.info # merged into device.info and the welcome deviceInfo
def info(d, session): return {}Handlers get (d, args) and raise err(code, message, fix, detail) for a plain-language error. Any other exception goes through classify(), and a connection error drops the tunnel so the session reconnects. d.client() is the asking client (None in --once mode).
The phone must only be reached through the session's existing tunnel. A second tunnel (another UserspaceRsdTunnel or pymobiledevice3 remote ...) breaks the daemon's link. The session (s = d.need_session(a)) offers:
| need | call |
|---|---|
| the RSD | rsd = await s.get_rsd() (waits up to 25 s for a reconnect) |
| a lockdown-over-RSD service for one call | async with s.open_service(AfcService) as afc: (also PcapdService, DiagnosticsService, or a coroutine such as HouseArrestService.create) |
| the same, kept open until the tunnel drops | afc = await s.cached_service("afc", AfcService); await s.forget_service("afc") after it breaks |
| an app's container | async with s.house_arrest(bundle_id, documents=False) as afc: (VendContainer, or VendDocuments with documents=True) |
| a raw service connection | conn = await s.service_connection(name, checkin=True) (caller closes it) |
| the shared DVT connection | dvt = await s.get_dvt() (mounts the DDI first) |
| a DVT instrument kept open | sm = await s.dvt_instrument("sysmon", Sysmontap); s.reset_dvt() if the channel broke |
| a DVT channel for one call | async with s.dvt_channel(ProcessControl) as pc: |
| a DVT connection of its own | async with s.dedicated_dvt() as dvt: (long-held things such as the condition inducer) |
| retry once on a broken DVT link | await s.dvt_retry(fn) |
| a loopback port into the phone | fw = await s.port_forward(service="com.apple.internal.dt.remote.debugproxy") or port=8100; fw.port, await fw.stop() |
| UDP for device-initiated media | s.udp_available(), s.userspace_udp(); pymobiledevice3's screen_stream.open_media_receiver() uses it by itself |
| USB-only services | s.require_usb("Packet capture"), async with s.usb_lockdown() as lockdown: |
| feature state | s.data (this device), s.tunnel_data (cleared when the tunnel drops) |
Import pymobiledevice3 classes the core doesn't load (HouseArrestService, PcapdService, DisplayService, ConditionInducer, ...) at the top of your feature module. If pymobiledevice3 changes, only that module fails to load.
d.resources (kit.Resources) holds things that stay open for clients: a mirror stream, a recording, a condition, a perf tap, a packet capture, a port forward. acquire(key, client, open_fn, close_fn, scope=..., timeout=...) counts one hold per client and runs open_fn once. release(key, client) returns how many holders are left and closes the resource at zero. The resource also closes when its last holder disconnects, after timeout seconds (touch(key) restarts the timer), on a tunnel drop (scope="tunnel"), on a device switch ("tunnel" or "session") and at shutdown (all scopes). forget(key) drops a resource that ended by itself. Use it for anything that changes the phone, so a crashed client never leaves a network condition switched on. features/mirror/real.py (the live view and recordings) is a working example; it also shows the DisplayService video stream over s.userspace_udp().
kit.CursorRing buffers streamed entries with bounds on count and bytes. read(cursor) returns entries, nextCursor, hasMore, missed and bufferStart, with the same semantics as the MCP server's ios_logs_read.
The demo twin registers the same command names with made-up data. Its handlers get (ctx, args), where ctx is the demo backend (ctx.resources, ctx.client()). A plain def handler runs in a worker thread, an async def one on the event loop. Shared fake data and event() live in demo/core.py. Document new commands and events in deviced-protocol.md.
To test in parallel checkouts without touching anyone else's daemon, give each one its own runtime directory:
export IOSSTUDIO_RUNTIME_DIR=$XDG_RUNTIME_DIR/ios-$NAME IOSSTUDIO_DEMO=1 # keep it short: socket paths max out at 107 bytes
python3 helper/run.py iosstudio.device.client daemon.features # starts this checkout's demo daemon on demand
python3 helper/run.py iosstudio.device.client device.info
python3 helper/run.py iosstudio.device.client daemon.shutdown '{"all": true}'IOSSTUDIO_RUNTIME_DIR replaces $XDG_RUNTIME_DIR as the base of ios-studio[-demo]/ (socket, lock, log, demo files) for bin/iosstudio-deviced, device/client.py and the MCP server. A real daemon started under it answers every request with busy while the default real daemon is running, because a second tunnel would break the first one's connection.
Setup and demo mode are in CONTRIBUTING.md. The rest:
./install.sh # once: symlinks, launcher entry, icon, theme hook
qs -p . # run from the repo (Ctrl+C to stop)
qs log -p . # read the log of a running instance (ios-studio --log does the same)
qs ipc -p . call iosstudio nav projects # drive it over IPC
bin/iosstudio-helper setup check # call the helper directlyIPC functions: nav(page) (also page:tab), navTab(page, tab), refresh(), status(), applyTheme(), toast(text, level). ios-studio <page> uses nav to deep-link. Page names and aliases are in lib/Model.js.
Demo mode, ios-studio --demo[=ready|expiring|fresh] [page], runs the whole app on made-up data: a fake account, iPhone and projects. It never touches your Apple account, phone, Hyprland config or real settings. Use it for screenshots and for UI work without a phone. A demo window and a real one can't be open at the same time. The MCP server has its own demo mode (IOSSTUDIO_DEMO=1, see mcp.md).
setup install accepts --dry-run. IOSSTUDIO_DEMO_FAIL=linker or =package makes demo builds fail with parsed linker or package errors, without a toolchain. IOSSTUDIO_DEMO_DELAY multiplies the demo's pretend-work pauses (build steps, installs, the demo iPhone's UI and debugger); 0 makes them instant, which the tests use.
| Area | Folder | Command |
|---|---|---|
| Helper and daemon modules, in process (stdlib only) | tests/helper/ |
.venv/bin/pytest tests/helper |
The helper as a subprocess, fake xtool/swift/swift-format (slow) |
tests/cli/ |
.venv/bin/pytest tests/cli |
MCP tools (mcp; need mcp, pydantic, pillow) |
tests/mcp/ |
.venv/bin/pytest tests/mcp |
QML core: Resource, lib/Model.js (qmltestrunner from qt6-declarative; skipped without it) |
tests/qml/ |
.venv/bin/pytest tests/qml |
Real Swift toolchain, network (slow, network) |
tests/e2e/ |
.venv/bin/pytest tests/e2e -m "" |
| Everything CI runs | tests/ |
.venv/bin/pytest --durations=10 |
pytest skips network tests by default (addopts in pyproject.toml); -m "" runs everything, -m "not slow" skips
the subprocess and toolchain tests. tests/conftest.py points every XDG_* folder, IOSSTUDIO_RUNTIME_DIR and TMPDIR
into pytest's own numbered temp folder (/tmp/pytest-of-$USER/pytest-N, of which pytest keeps the last 3; a killed
run's folder rotates out too) and sets IOSSTUDIO_DEMO_DELAY=0. Shared fakes are in tests/support/ (import support), fixtures in
tests/fixtures/<area>/, and pyproject.toml puts helper/, mcp/ and tests/ on the path. Patch a shared folder
or output where the code reads it (mock.patch.object(appdirs, "STATE_DIR", …)). No test needs xtool, pymobiledevice3,
an iPhone or your home folder; tests that use Swift, swift-format or llvm-symbolizer skip without them.
Hot reload's tests (listed in features/hot-reload.md) use these hooks: IOSSTUDIO_HOT_RELOAD_TEMPLATES replaces templates/hot-reload/ (stand-in runtime packages), IOSSTUDIO_XTOOL_DATA replaces xtool's data folder ~/.config/xtool/data (a throwaway signing identity made with openssl, never yours), IOSSTUDIO_RCODESIGN is the rcodesign to run (a fake), and IOSSTUDIO_SWIFT the swift that checks Package.swift (shared with the packages feature). IOSSTUDIO_E2E_CRASHLAB points tests/helper/test_hot_reload_e2e.py at an already built copy of CrashLab, which it edits in place, to skip the first build of about 4 minutes.
.github/workflows/ci.yml runs on every pull request, on pushes to main and by hand (Actions › CI › Run workflow). A newer push to the same branch cancels the older run. It has three jobs:
- Python, on 3.11 (the oldest the helper runs on, because of
tomllib), 3.14 (what Omarchy ships) and 3.15. It compiles every file inhelper/,mcp/andtests/, runstests/helperandtests/cliwith that Python and only pytest installed (the helper must stay stdlib-only), makes the dev venv withuv sync --group devand runs every test but thenetworkones in it with--durations=10, then checks thatbin/iosstudio-mcp --prepare(the same uv path users get) still builds the MCP venv. No test needs xtool, pymobiledevice3, an iPhone or your home folder: they use fake tools, fixtures and temp folders. - Lint: ruff 0.17.4 with the rules in
pyproject.toml: pyflakes, pycodestyle's real errors (unused imports and variables, undefined names, syntax) and import order (I, fixable withruff check --fix), no style rules.E731(a lambda assigned to a name) andE741(names likel) are off. Then shellcheck at warning level oninstall.sh, the shell scripts inbin/,helper/root/,.github/scripts/and the dSYM fixture'sbuild.sh.tests/qmlis skipped there (noqmltestrunneron the runner); run it locally. - QML: qmllint on every
.qmlfile in anarchlinux:latestcontainer withqt6-declarativeandquickshellfrom Arch's repos.qs.Commonsandqs.Uiare symlinks into Omarchy's shell that onlyinstall.shmakes, so their imports don't resolve there. qmllint's default levels only fail on syntax errors; the thousands of unresolved-import, unqualified and missing-property warnings that follow from that are counted in the log but don't fail the job.
To run the same checks locally:
python3 -m compileall -q helper mcp tests # writes __pycache__ folders (gitignored)
python3 -m pytest tests/helper tests/cli # stdlib + pytest only
uv sync --group dev && .venv/bin/pytest --durations=10
.venv/bin/ruff check # or: uvx ruff@0.17.4 check
shellcheck --severity=warning install.sh bin/ios-studio bin/iosstudio-helper bin/iosstudio-deviced bin/iosstudio-mcp helper/root/*.sh tests/fixtures/crash-symbolication/build.sh .github/scripts/*.sh
/usr/lib/qt6/bin/qmllint $(git ls-files '*.qml') >/dev/null; echo $? # 0 unless there's a syntax error
actionlint # the workflow files themselvesPushing a tag vX.Y.Z runs .github/workflows/release.yml. It checks that the tag matches the version files (.github/scripts/check-version.sh), runs the CI jobs above, then creates a GitHub Release with notes generated from the merged pull requests, grouped by label as set in .github/release.yml (enhancement, bug, mcp, ui/accessibility, documentation, ci, then everything else). It attaches ios-studio-X.Y.Z.tar.gz (a git archive of the tag) and ios-studio-X.Y.Z.tar.gz.sha256. A tag with a suffix, like v0.2.0-rc1, is published as a pre-release and checked against its base version (0.2.0). Only the last job can write to the repo (contents: write).
To make a release:
-
Bump the version in both files to the same
X.Y.Z:readonly property string versioninAppState.qml(Settings › About shows it) andversioninmcp/pyproject.toml. Changingpyproject.tomlmakes each user's MCP venv rebuild once on its next start. -
Merge that through a pull request, then tag the merge commit on
mainand push the tag:git switch main && git pull .github/scripts/check-version.sh v0.2.0 # prints 0.2.0, or says which file is still behind git tag -a v0.2.0 -m "iOS Studio 0.2.0" git push origin v0.2.0
-
Watch Actions › Release. If the version check fails, the job names the file that differs: delete the tag (
git push origin :v0.2.0 && git tag -d v0.2.0), fix it and tag again.
Users install a release by cloning its tag or from the tarball, see the README's Install section.
The paths below are the defaults: $XDG_CONFIG_HOME, $XDG_STATE_HOME, $XDG_CACHE_HOME and $XDG_DATA_HOME replace ~/.config, ~/.local/state, ~/.cache and ~/.local/share when set, for the app, helper, daemon and MCP server alike.
| What | Path |
|---|---|
| Settings | ~/.config/ios-studio/settings.json |
| State (build history, renewals, device, setup progress; projects.json has each project's build settings and run presets; editor-auto.json what editor setup wrote into each project) | ~/.local/state/ios-studio/ |
| Latest lint result per project (format and lint) | ~/.local/state/ios-studio/lint/ |
| Full diffs of format dry runs that didn't fit (the newest 10 are kept) | ~/.cache/ios-studio/format/ |
Swift packages: manifest descriptions, product lists and SwiftPM scratch folders (the newest 100 of each), full Package.swift diffs that didn't fit (the newest 10) |
~/.cache/ios-studio/packages/ |
| One lock per project so two package changes never run at once | ~/.local/state/ios-studio/packages/ |
| Build logs (the newest 300 builds' logs are kept) | ~/.local/state/ios-studio/build-logs/ |
Cache (screenshots, crash files, account lists, each iPhone's app list apps-<udid>.json) |
~/.cache/ios-studio/ |
| Large MCP results saved to a file | ~/.cache/ios-studio/mcp/ |
| Kept builds for crash symbolication (binary + dSYM per UUID; last 10 per project, 1 GB in total) | ~/.cache/ios-studio/symbols/ |
Screenshots, screen recordings, packet captures, metrics CSVs and memgraphs, camera test results (the oldest are deleted past a count and size cap, see fileio.prune) |
~/.cache/ios-studio/screens/, recordings/, captures/, metrics/, cameratest/ |
App executables unpacked from .ipa files for the debugger (the newest 2 per project) |
~/.cache/ios-studio/debug-builds/ |
Debug in editor: each app's attach file (<bundle id>.lldb), its running bridge (<bundle id>.json) and the lldb commands they load (the newest 20 apps) |
~/.local/state/ios-studio/editor-debug/ |
Hot reload: each project's baseline (build commands, sources and objects as built, the app's executable) and its signed patches (the newest 10); 300 MB in all, the oldest projects go first, never one with a running session; staging folders (.<key>-…) go after 6 hours |
~/.cache/ios-studio/hot-reload/<key>/ (key: the first 12 hex digits of the SHA-1 of the project path) |
Hot reload in a project: the runtime package (or its no-op stub) and a .gitignore of *; the managed block at the end of Package.swift |
<project>/.iosstudio/hot-reload/ |
Hot reload sessions: hotreload-<key>.lock, hotreload-<key>.json (snapshot and the last 20 reloads), hotreload-<key>-control.json (pause/resume); a stopped session's files go after 24 hours, lock files without a holder or a state file after a minute |
$XDG_RUNTIME_DIR/ios-studio/ (same base as watch mode) |
Watch mode (lock, status, events, owners, log; demo mode uses ios-studio-demo/) |
$XDG_RUNTIME_DIR/ios-studio/watch* ($IOSSTUDIO_RUNTIME_DIR overrides the base; without XDG_RUNTIME_DIR, /run/user/<uid> when it's yours, else /tmp/ios-studio-<uid>: device/client.py: runtime_base(), shared with the device daemon) |
| Compiled Python modules of the helper, daemon and MCP server | ~/.cache/ios-studio/pycache/ |
| Debug symbols, per iOS version | ~/.cache/ios-studio/DeviceSupport/ |
App data: copies of an app's SwiftData / Core Data stores (pulled again when they change; the 5 most recently used apps) its preferences file before each change (the newest 10 per app), and its recent changes for the reverted check (writes.json) |
~/.cache/ios-studio/appdata/<bundle id>/ |
| Imported photos and videos (default) | ~/Pictures/iPhone |
| pymobiledevice3 venv | ~/.local/share/ios-studio/venv |
| MCP server venv | ~/.local/share/ios-studio/mcp-venv |
| Config backups made by Settings › AI agents | ~/.local/state/ios-studio/backups/ |
| App checkout | anywhere; the README clones into ~/.local/share/omarchy-ios-studio. install.sh and bin/ios-studio find it from their own path |
| Launcher command | ~/.local/bin/ios-studio (symlink into the checkout) |
| Desktop entry, icon | ~/.local/share/applications/ios-studio.desktop, ~/.local/share/icons/hicolor/scalable/apps/ios-studio.svg |
| New apps (default) | ~/Developer; scanned roots default to whichever of ~/Developer, ~/Projects, ~/Code, ~/src, … exist (appdirs.default_project_roots()) |
| Apple sign-in (owned by xtool) | ~/.config/xtool |
The UI and error rules are in ARCHITECTURE.md. Also:
- Every async surface has a loading, empty and error state. Errors show the plain
messageand a fix button. - Destructive actions go through
app.confirm({...})with Cancel as the default. - Desktop notifications (
omarchy-notification-send) only fire while the window isn't focused. - Nothing animates unseen: an
Iconwithspinningturns only while it's visible and the window isn't hidden, a StatusPill'slevel: "busy"is bound to work that is running (never left on a hidden pill), and an endless animation of your own checksvisibletoo. A hidden spinner keeps the whole window redrawing. - Settings edits to Hyprland files only touch marker-delimited blocks, back the file up first and roll back if
hyprctl configerrorsreports a problem.
- components.md: the page contract and every shared component's API
- deviced-protocol.md: device daemon commands and events
- setup-steps.md: the Setup steps, what each installs, and the install events
- features/: one page per feature: how it works, its limits, the agent tools and the code