This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Flipper-iOS-App is the iOS companion app for the Flipper Zero device family ("Mobile app to rule all the Flipper's family"). It talks to a physical Flipper device over Bluetooth, manages its file archive (NFC/RFID/Infrared/iButton/Sub-GHz keys), and integrates with the Flipper cloud catalog/backend.
The Xcode project lives at Flipper/Flipper.xcodeproj, scheme Flipper(iOS). There is no fastlane/CI build pipeline in this repo — builds and tests are run through Xcode or xcodebuild directly.
# Build the app
xcodebuild -project Flipper/Flipper.xcodeproj -scheme "Flipper(iOS)" -destination "platform=iOS Simulator,name=iPhone 17 Pro" build
# Lint (SwiftLint, config at Flipper/.swiftlint.yml)
cd Flipper && ./perform_lint.sh
# or directly:
cd Flipper && ./swiftlintEach feature/domain package under Flipper/Packages/* is an independent Swift Package with its own Tests/ directory, so tests can be run per-package without opening the full app:
# Run all tests for one package
cd Flipper/Packages/Core && swift test
# Run a single test (XCTest selector syntax)
cd Flipper/Packages/Core && swift test --filter ArchiveTests/testSomethingThis repo has .mcp.json configured for XcodeBuildMCP and .xcodebuildmcp/config.yaml with a default session profile (ios) pointed at the Flipper(iOS) scheme — prefer the XcodeBuildMCP tools over raw xcodebuild invocations when available.
- Line length limit is 80 characters (enforced by both
.editorconfigand SwiftLintline_length). - SwiftLint disables
todo,nesting,opening_brace,identifier_name,cyclomatic_complexity,void_function_in_ternary— don't fight these where they'd normally fire. Packages/Peripheraland parts ofPackages/Core(protobuf-generated sources, theVersionutils) are excluded from lint — don't expect clean lint output there and don't try to "fix" generated code style.
The codebase is split between the iOS app target (Flipper/iOS, Flipper/AppIntents, Flipper/Shared, Flipper/ActivityWidget, Flipper/LiveWidget, Flipper/KeyPreview) and a set of local Swift Packages under Flipper/Packages/ that contain essentially all business logic. The app target is thin — it composes SwiftUI screens (Flipper/iOS/UI/{Apps,Archive,Device,Hub,Infrared,Main,Options,RemoteControl,TabView,Welcome,...}) on top of these packages, plus App Intents/Shortcuts support (Flipper/AppIntents) and widgets (ActivityWidget, LiveWidget).
Package dependency graph (leaf → root):
- Macro — standalone Swift macro plugin (
SwiftSyntax-based), depended on byBackendandCorefor compile-time code generation. - Peripheral — lowest-level layer: Bluetooth transport and the RPC/protobuf protocol spoken with the physical Flipper device (
Sources/Bluetooth,Sources/RPC/{Model,Protobuf,Session}). No dependency on other local packages. - Analytics — event tracking abstraction with backends for Countly, Clickhouse, and "WantMoar", plus its own protobuf event schema.
- Activity — Live Activity / progress UI support, consumed by
Core. - MFKey32v2 — a C library (
CCrapto1) wrapped in Swift for Mifare Classic key-recovery ("reader attack") functionality. - Backend — networking clients for the Flipper cloud services:
Catalog(app/firmware catalog) andInfrared(IR signal database), built onMacro. - Core — the app's domain layer; depends on all of the above (
Macro,Analytics,Activity,Peripheral,MFKey32v2,Backend). Owns device pairing (PairedDevice), the local file archive and its favorites/manifest handling (Archive), sharing/deep-link encoding (Sharing), OTA firmware updates (Update), region/provisioning data (Provisioning), the reader-attack flow (ReaderAttack), and the high-levelFlipperservice that apps/UI code talk to. - Notifications — push notifications via Firebase Cloud Messaging; kept separate from
Coresince it pulls in the Firebase SDK.
When changing device-communication behavior, start in Peripheral (transport/protocol) vs. Core/Sources/Flipper (device service facade) depending on whether the change is protocol-level or app-facing. When changing anything catalog/IR-database related, that's Backend, not Core.
Core, Backend, Peripheral, and Analytics all declare swift-protobuf dependencies and carry generated Protobuf sources — treat files under any Sources/**/Protobuf or Sources/**/events directory as generated, not hand-written.