agentleFS
MobAI-AppMobAI-App/simslim/CLAUDE.md

simslim

CLAUDE.md3.5k starsChanged 37 days agoMITView on GitHub

simslim runs many more iOS, tvOS, watchOS, and visionOS simulators on one Mac by disabling the background daemons a simulator doesn't need, cutting each simulator's memory ~4x. It is a Go CLI plus a SwiftUI macOS app that wraps it. Everything is driven through xcrun simctl; the tool only ever touches the simulators you point it at, never the host Mac. macOS-only. make check runs go test, go vet, swift-format lint --strict --recursive gui, zsh -n scripts/build-app.sh, and plutil -lint…

Trending

More talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 9 mentionsOct 2026: 7 mentionsNov 2026: 1 mention
Dec 2025Jun 2026Nov 2026
Mentions a month of the MobAI-App/simslim repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about MobAI-App/simslim

The biggest 5 of 17 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 17

Talked about on GitHub and Bluesky (17 times).

On GitHub · 16

11 more on GitHub

On Bluesky · 1

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before that per-label pass, unloadInBatch stops most labels at once: it finds each label's job plist under the runtime's RuntimeRoot …

    line 86
  2. Very specific:

    JSON is a contract: Every read-only and management command supports --json.

    line 155
  3. Distinctive:

    not additive: Every category must have a positive measured estimate.

    line 206
  4. Very specific:

    Never add a Co-Authored-By: Claude trailer or any "Generated with Claude" footer to commit messages.

    line 210

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

simslim runs many more iOS, tvOS, watchOS, and visionOS simulators on one Mac by disabling the background daemons a simulator doesn't need, cutting each simulator's memory ~4x. It is a Go CLI plus a SwiftUI macOS app that wraps it. Everything is driven through xcrun simctl; the tool only ever touches the simulators you point it at, never the host Mac. macOS-only.

Commands

go build ./cmd/simslim          # build the CLI
go test ./...                   # run all tests (Makefile: make test)
go test -run TestName ./...     # run a single test
make check                      # full CI gate — must pass before a PR
make format                     # gofmt + swift-format (run before committing)
make app                        # build build/SimSlim.app (Go + swiftc, macOS only)
open build/SimSlim.app

make check runs go test, go vet, swift-format lint --strict --recursive gui, zsh -n scripts/build-app.sh, and plutil -lint gui/Info.plist. CI (.github/workflows/ci.yml) runs exactly this on macos-26 / Xcode 26.6, then builds and verifies the app bundle.

Tests are pure unit tests (parsing, delta logic, allowlist invariants) — they do not boot real simulators, so they run anywhere. Only the app build and manual runs need Xcode + an iOS runtime.

Architecture

Two packages. The repo root is package simslim, an importable library holding every piece of slimming logic and no external dependencies. cmd/simslim/ is package main, the CLI: main.go dispatches os.Args[1] to a cmd* function per subcommand and enforces macOS-only up front.

Anything that talks to a terminal — printing, --json encoding via writeJSON, the interactive wizard in wizard.go, fatal(), usage() — lives in cmd/simslim/. The library never writes to stdout; it returns values and reports progress through the Reporter callback the caller supplies.

Exported identifiers in the root package are the public API, so renaming one is a breaking change for importers as well as for the CLI.

The slimming model (the core idea). profiles.go defines Categories, an allowlist of launchd daemon labels grouped by user-facing feature (siri, search, icloud, …). Categories may overlap — a label lives in every category whose feature needs it (e.g. the AMS payment-sheet daemons are in both store and icloud), and Profile.Desired() keeps a label enabled when any excepted category lists it. SlimmableSet() is the deduplicated union of every label in Categories. managedSet() adds each category's AlwaysEnabled compatibility services, which simslim may only repair back to enabled; these are the only labels the tool may ever disable or enable. Anything outside those sets is never touched. service_descriptions.go supplies the short per-daemon explanations shown by the GUI; its coverage and length are enforced in profiles_test.go. profile_file.go loads a committed JSON profile (simslim on --profile <path>) whose except/keep arrays mirror the flags of the same name, validates it against the allowlist, and resolves it to a Profile. The dependency-free profile command's interactive wizard lives in cmd/simslim/wizard.go. features.go defines Features, a finer-grained catalog than Categories: each feature (push, storekit, universal-links, …) names just the daemons one testable capability needs. doctor reads a booted simulator's disabled labels and reports any required feature whose daemons are down, exiting non-zero — a CI preflight. features_test.go asserts every feature label is managed, including required services that earlier versions could have disabled. slim.go's ensure() rejects a non-empty slim profile on runtimes older than iOS/tvOS 18.5, watchOS 11.5, or visionOS 2.5 before booting or mutating the device, then reads the currently disabled labels, computes a delta against the desired set, and applies the changes with launchctl disable/enable run inside the simulator via simctl spawn, a pool of spawnWorkers (8) at a time. It reboots and reads the state back before reporting persistence. on disables the profile; off remains available on every runtime and re-enables the whole managed set. Profile.DesiredForDevice keeps com.apple.homed enabled on watchOS, which re-enables that service after startup, and com.apple.mobileassetd on visionOS, whose simulated surroundings are mobile assets. Slimming, verification, and per-device status totals use this platform-specific profile; Profile.Desired remains the platform-independent catalog for profile editors. Device.Platform identifies iOS, tvOS, watchOS, or visionOS (CoreSimulator's xrOS runtimes); an empty platform defaults to iOS for library callers. EnableSlimNoReboot (on --no-reboot) skips the reboot: it runs launchctl disable + launchctl bootout per label so the daemon stops in the current boot session, which is the only slimming possible on runtimes older than iOS 18.5. Before that per-label pass, unloadInBatch stops most labels at once: it finds each label's job plist under the runtime's RuntimeRoot (Device.RuntimeID → runtimeRoot, used only when the plist's own Label matches) and passes them to one launchctl unload -w per 64 plists, which writes the same override as disable and removes the job like bootout. It then reads print-disabled and launchctl list back, and only labels still enabled or loaded take the per-label path; any failure in the batch just means more labels do.

The offline fast path. On a runtime with persistent overrides ensureOffline takes over: disabled_store.go writes the overrides directly and boots the device once, already slim, skipping every launchctl spawn and the reboot that would apply them (measured 2m14s → 33s for 170 labels). A booted device gets there too — an override only takes effect at the next boot, so ensure reads its live state, returns early when the profile already matches, and otherwise spends the shutdown the device already owed before handing off. There is no shell inside any iOS runtime (RuntimeRoot/bin holds only df and launchctl), so batching transitions through a spawned /bin/sh is not an option; the offline path uses the pool. launchd_sim is a host process, so that store is not in the device's data directory — it sits beside the device's launchd.log in /private/var/tmp/com.apple.CoreSimulator.SimDevice.<UDID>/disabled.plist, keyed only by UDID. It is an undocumented CoreSimulator detail, so treat it as best-effort: writes merge (the runtime keeps its own explicit-enable entries there, and unmanaged labels are never simslim's business), the booted device is always read back with print-disabled rather than trusted, and anything that does not work out returns errOfflineIneffective so ensure falls back to the launchctl path. A store problem must never surface as a command failure. watch.go uses the same store to slim a shut-down device before it boots (preslimDevice): it only adds the profile's disables, to every shut-down device on startup. A kqueue NOTE_WRITE watch on each device-set directory (watch_dirs_darwin.go, re-attached each scan interval while a set directory is missing) seeds a new device from its device.plist in its own goroutine (seedNew), since a simctl list on a loaded host takes longer than a script waits between simctl create and boot. A boot that starts first is logged and caught by the no-reboot slim at boot, which stays as the read-back and fallback.

Live enable/disable. live.go holds EnableServices/DisableServices (simslim enable/disable), which act on a booted simulator only and keep no state, like on --no-reboot: the profile stays the only description of a slim simulator. startServices runs one launchctl load -w per chunk via loadJobs, then per-label enable and bootstrapJobs for what is left; stopServices is the unload/disable/bootout path on --no-reboot uses. Everything is read back; a label that loads only at the next boot is reported in notStarted, not as an error. disable keeps a label a named category shares with another category whose labels are all enabled right now (enabledNeighbours), and reports it in stillEnabled; a label named on its own is always stopped. A simulator that is not booted is an error unless --save is given. profile_save.go's SaveServices (--save <file>) adds or removes categories in a profile file's except and labels in its keep, keeping order and other fields, skipping duplicates, starting a missing file from the default (empty) profile, and writing atomically; the file is validated first and written only after the live change succeeded. Launchd reads (readLaunchd) retry launchd_sim's error 124 ("Domain is tearing down", answered for a few seconds around a boot or reboot) and an attempt that ran out of SpawnTimeout, on launchdRetryDelays, and nothing else; later applyDelta passes pause on the same delays. Reads and per-label transitions go through launchctlCmd, whose WaitDelay abandons the output pipe a killed xcrun's simctl child would otherwise hold open forever.

simctl wrapper. simctl.go is the only place that shells out to xcrun simctl (list/boot/shutdown/clone/erase/delete/spawn). measure.go sums phys_footprint across the simulator's launchd process tree (via pgrep/ps/top) — that's the memory figure that decides how many simulators fit. MeasureProcesses keeps the per-process detail (footprint + cpu, from the same snapshot) for the top drill-down. fleet.go's FleetSnapshot composes booted devices + slim status + MeasureMany into the fleet view; the live TUI is cmd/simslim/top.go (Bubble Tea), which also has a --json/non-TTY one-shot fallback. disk.go, disk_cleanup.go, and disk_inventory.go handle disk measurement and the separate, permanent disk-cleanup feature.

JSON is a contract. Every read-only and management command supports --json. The structs in output.go (DeviceSummary, StatusOutput, SimulatorMutationOutput, ServicesOutput, etc.) plus the category/plan structs are the stable interface the SwiftUI app decodes. Changing a JSON field breaks the GUI in gui/*.swift — keep them in sync. gui/Backend.swift invokes the bundled CLI with --json and decodes these types; there is no other IPC.

The SwiftUI app (gui/) has no Xcode project. scripts/build-app.sh compiles the Swift sources directly with swiftc, cross-builds the Go CLI, bundles it into SimSlim.app/Contents/Resources/simslim, generates the icon, and ad-hoc codesigns. The app is a thin front end that shells out to that bundled binary.

Safety invariants — preserve these

  • Never add a deadlock-prone daemon to Categories. A handful of daemons wedge a simulator when disabled. profiles_test.go holds a forbiddenLabels list and asserts none appear in any category; if you add labels, keep that test green.
  • Only managed labels are ever mutated. delta() is scoped to managedSet() on both sides. Compatibility labels are omitted from every desired slim state, so they can only be repaired to enabled.
  • Destructive/management commands resolve the exact UDID first (findDevice / shutdownIfBooted) so a simctl alias like all can never fan out a boot, erase, delete, or filesystem path across every simulator.
  • Disk cleanup only removes allowlisted per-device directories, refuses to run without --confirm, and never touches the shared, signed iOS runtime (built-in apps, core OS language resources). disk-plan is strictly read-only. Durable storage (Documents, app bundles, user media) is measured but never deletable.

Conventions

  • CLI parsing uses github.com/urfave/cli/v3; the top command's live TUI uses github.com/charmbracelet/bubbletea + lipgloss. These are the CLI's only dependencies — the root library still has none, so importers never inherit a terminal stack. The command tree lives in cmd/simslim/app.go (newApp); each subcommand's Action is a cmd* function in cmd/simslim/main.go that reads flags via cmd.Bool/String(...) and positionals via cmd.Args(). Flags may appear before or after positional args (e.g. simslim on <udid> --except search) — v3 parses flags anywhere by default. --set is a global flag (inherited by every subcommand) registered in its flag Action. main.go still owns version/help/no-args and the macOS-only guard before handing off to the tree, and routes every command error through fatal() for the stable simslim: <msg> (exit 1); unknown commands exit 2 with usage.
  • Two timeouts live in simctl.go: ShutdownTimeout (30s, a const) and BootTimeout (10min, because a first slim reconfigure boots twice). BootTimeout is a package var, not a const, so the CLI's global --boot-timeout flag (env SIMSLIM_BOOT_TIMEOUT, wired in app.go like --set) can raise it for slow CI runners where the per-daemon launchctl transitions would otherwise blow the deadline mid-reconfigure.
  • Progress for multi-minute operations goes to stderr via the Reporter callback; machine-readable JSON goes to stdout. Under --json, suppress the stderr chatter so consumers reading a combined stream still get clean JSON.
  • Memory estimates (ApproxMemoryMB) are iOS-26.5 clean-boot medians and are not additive. Every category must have a positive measured estimate.

Git

Never add a Co-Authored-By: Claude trailer or any "Generated with Claude" footer to commit messages.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.