Let Claude debug your mobile app through Flocon Desktop (timeline, crashes, network calls, mocks and bad network, files, analytics, databases, preferences, feature flags, deeplinks, dashboards, tables, images, accessibility, WebView, screenshots and recordings), and set Flocon up or migrate it in Android, KMP, iOS and Flutter projects

GitHub stars
384

Install

/plugin install flocon@flocon

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openflocon/Flocon.

Contents

Discovered from source

Skills 2

Debugging a mobile app with Flocon

Flocon Desktop receives what happens in the mobile app connected to it and exposes it through the flocon MCP server (tools mcp__flocon__*).

Prerequisites

  • Flocon Desktop must be running (the MCP server listens on http://localhost:9042/mcp, loopback only). Port 9042 is only for MCP; the apps connect to Desktop on 9023 (WebSocket) and 9024 (HTTP).
  • The app must be connected to Flocon. If a tool fails to connect or returns no device, ask the user to start Flocon Desktop and the app.

Discover the tools, do not assume them

The table below lists the tools of the current Flocon Desktop, but the session may expose fewer: an older Desktop has fewer tools, and some clients only expose part of a server's tools (for example list_images present in the server tools/list but missing from the session). Work from the tools actually available in the session. If a tool you need is missing, say so and name it; do not call another tool as a substitute and present its result as the same thing. A tool available in the session can still return nothing for a platform whose SDK does not send that data (see below).

Targeting

By default every tool targets the device and app selected in Flocon Desktop. Call list_devices to see the others (each has a connectionType: default for localhost, wifi when connected through the connect module), then pass deviceId and packageName. When nothing is selected in Desktop, or a call fails on the selection, retry with an explicit deviceId and packageName (the iOS bundle id) taken from list_devices.

When a call fails

Tell the user which case it is, with the evidence, before concluding anything about the app:

SymptomCaseNext step
Connection refused on localhost:9042 / the MCP server is not connectedFlocon Desktop not running (or MCP disabled)Ask the user to start Flocon Desktop
"No device has been connected to Flocon yet"No device ever connectedCheck the app runs a build where Flocon is started, and the Desktop version is compatible with the SDK (the Swift SDK needs a Desktop with the encrypted wss connection)
"No device / app is currently selected"Nothing selected in Desktoplist_devices, then pass deviceId and packageName
"App '…' not found", "Device '…' not found or has no app", "several apps"Unknown or ambiguous targetUse the exact ids from list_devices
Unknown tool, missing argument, unexpected schemaDesktop version and skill out of syncSay which tool and which Desktop version the user runs
A Kotlin class name in the message (for example …RepositoryImpl$getDeviceSelectedApp$2) or a stack-trace-like textInternal Desktop errorReport it as a Flocon Desktop error with the tool, arguments and message; retry once with an explicit target. Do not present it as a bug of the mobile integration without other evidence

Do not restart Desktop, clear data or change ports to work around an error unless the user asks.

Platform coverage

The tools are shared by every SDK, but each SDK sends what it supports. With the Swift SDK (FloconSwift): network (only the instrumented URLSessions, plus gRPC with FloconSwiftGrpc), images (from network responses, no new entry on a cache hit), analytics, feature flags, tables, preferences (incl. keychain if registered), files, databases (inspection; query logs only when the app logs them), dashboards, deeplinks, timeline logs, crashes and WebView events (console and page events of attached WKWebViews, bridge calls the app logs). Not sent by the Swift SDK at the time of writing: accessibility events, and its websockets do not accept injected messages. Screenshots and screen recordings are taken by Desktop on the booted iOS Simulator only. With the Flutter SDK (FloconFlutter): network (only clients wrapped with withFlocon(), WebSockets only when logged by hand, mocks and bad network on Dio / package:http), images, analytics, feature flags, tables, preferences, files, databases (inspection; query logs only when the app logs them), dashboards, deeplinks, timeline logs and crashes (Dart and Flutter errors only). Not sent by the Flutter SDK: WebView events and accessibility events, and its websockets do not accept injected messages. An empty result for a feature the app did not wire is not an app bug: say which wiring is missing (see the flocon-setup skill).

What to use for what

GoalTools
Understand what the app did around a moment ("before the crash", "at 14:32", "recently"), or know if an event was sentget_timeline first: one narrative of every source with the anomalies first (crash, HTTP errors, ERROR logs, loops, responses over 1 MB). Give nothing to let it choose (the latest crash, otherwise the last 2 minutes) and read window.reason; mode / at / from / to / eventId to choose; search to know if an event was sent; excludeSources: ["database"] if the database lines are noise. Then use the ids of its lines (network:<callId> for get_network_call, crash:<crashId> for get_crash_report)
Show the user a zone of the timeline (a crash, an error, a loop, a large call) in Floconshow_in_timeline (eventId of get_timeline, or a time, or nothing: the latest crash then the main anomaly; view graph or list). It selects the device and app, opens the timeline and centers the graph. Flocon is not brought to the front: tell the user to go to the Flocon app. Read hiddenBy and the message: if a filter of the user hides the event, say it, the filters are never changed
Find a failing or slow calllist_network_calls, search_network_calls (summaries), then get_network_call with a callId for headers, bodies and the cURL command
Make the app receive a fake response or exceptioncreate_network_mock (fromCallId starts from a captured call), update_network_mock, list_network_mocks, get_network_mock, delete_network_mock
Simulate a slow or flaky network (latency, random errors or exceptions on a part of the requests)list_bad_network_configs (the configs of the app and the active one), create_bad_network_config (latencyTriggerProbability with minLatencyMs / maxLatencyMs; errorProbability with errors, each an httpCode or an exceptionClassPath such as java.net.SocketTimeoutException, picked by weight; enabled: true activates it right away, otherwise it is created inactive), update_bad_network_config (only the given fields, errors replaces all of them), set_active_bad_network_config (one active config per app; without configId it turns the simulation off), delete_bad_network_config
Check a file written by the applist_file_roots first (the root folders announced by the app: the platform defaults, such as files and caches on Android or documents, caches and tmp on iOS, plus the folders registered by the app), then list_files (a root id, then the absolute path of a sub directory), read_file
Read a custom dashboard of the applist_dashboards, get_dashboard for its elements and values
Investigate a crashlist_crash_reports for the exception type and message, get_crash_report for the full stack trace
Debug a WebView (JS console errors, failed page loads, calls from the page to native code)list_webview_events (filters: kind console / page / bridge, text, start timestamp); the requests made by the page are not captured yet
Check analytics eventscount_analytics_events for an overview per event name, list_analytics_events for the properties, list_analytics_tables
Check the deeplinks of the applist_deeplinks (declared links and parameters), list_deeplink_history, open_deeplink (opens a link on the device, fill its parameters first)
See the current screen, or keep a visual tracetake_screenshot (saves a PNG and returns the image)
See what the Flocon desktop app itself displays (the screen the user is looking at in Flocon)take_flocon_desktop_screenshot (returns the image of the visible window, nothing is saved; not the device screen)
Read or change the ports of the Flocon servers (websocket 9023, HTTP 9024 by default)get_server_ports (effective, saved, defaults, forced by a launch option), set_server_ports (websocketPort, httpPort, at least one)
Show the user something in the Flocon desktop app (a screen, another device / app, the graph or list view of the timeline)flocon_navigate_into_desktop_app (screen, deviceId, packageName, timelineView; Flocon is not brought to the front, so tell the user to go to the Flocon app to see it)
Reproduce a bug on videostart_screen_recording, do the scenario, then stop_screen_recording (returns the mp4 path; Android stops by itself after 3 minutes)
Show the user the saved screenshots, videos or exportsopen_flocon_folder (opens the Flocon documents folder, optional Screenshot / ScreenRecord sub folder)
Check SharedPreferenceslist_shared_preferences (gives the sharedPreferenceId and the storage type), get_shared_preference_values (typed values, optional text filter); set_shared_preference_value edits an existing key (never creates or removes one) and returns the previous value
Make the app receive a server message on a websocketlist_websocket_clients (ids of the websockets accepting injected messages), then send_websocket_message (Android OkHttp FloconWebSocket only for now)
Check feature flagslist_feature_flags (provider, name, state, variant, filters), get_feature_flag for the full payload
Check what a screen reader gets (focus order, announcements, content descriptions)get_accessibility_state first (is TalkBack / VoiceOver on, is capture supported), then list_accessibility_events (type and text filters), clear_accessibility_events; walk the focus order with move_accessibility_focus (next / previous, needs TalkBack on) and read where it is with get_accessibility_focused_node
Check which images the app loadedlist_images (urls and load times). If one is missing, check in order: did a real download happen (cache hits are not captured), is it in list_network_calls, is its Content-Type an image/*, then whether only the Desktop thumbnail fails (Desktop downloads the image from its URL)
Check persisted datalist_databases (gives the databaseId), list_database_tables (schema), query_database, list_database_query_logs (queries run by the app, each with a transactionId when it ran in a transaction, plus nestedTransactionId / parentTransactionId for a savepoint inside it; pass transactionId to get only that transaction)
Check custom tableslist_tables (gives the tableId), list_table_items (rows, optional text filter)

Rules

  • Mocks change the app behavior: prefer disabling a mock (update_network_mock) over deleting it, and tell the user which mocks you left enabled.
  • query_database is read only (SELECT, PRAGMA without value, EXPLAIN): always add a LIMIT.
  • The captured data stays read only: network calls, files, databases, preferences (except set_shared_preference_value), analytics events, feature flags, crashes, the timeline, tables, dashboards, images and WebView events cannot be modified, deleted or replayed through the tools (get_dashboard cannot trigger a button or a field). read_file only saves a copy of the file on the computer.
  • These tools change the state of the app, the device or Flocon Desktop: use them when the user asks or when the task needs it, and always tell the user what you changed.
    • App behavior: create_network_mock, update_network_mock, delete_network_mock, create_bad_network_config, update_bad_network_config, set_active_bad_network_config, delete_bad_network_config, set_shared_preference_value, send_websocket_message.
    • Device: open_deeplink, move_accessibility_focus, take_screenshot, start_screen_recording, stop_screen_recording (the screenshots and videos are saved in the Flocon documents folder).
    • Flocon Desktop and the computer: set_server_ports, show_in_timeline, flocon_navigate_into_desktop_app, clear_accessibility_events (deletes the accessibility events received from the app), open_flocon_folder.
  • set_shared_preference_value can lose data: read the value first with get_shared_preference_values, show the user key: old value -> new value and get their confirmation before calling it. Afterwards, tell them the previous value (returned as previousValue) so it can be restored; confirmed: false means the app did not answer in time and the edit may or may not be applied.
  • Bad network configs change the app behavior as soon as one is active, and an update of the active config is applied right away: tell the user which config you left active, if any. To stop the simulation, prefer set_active_bad_network_config without configId (the configs are kept) over deleting a config.
  • get_timeline only reads. The times are those of the phone, not the computer. Read window.reason, truncated and notes before concluding: an empty answer can mean the window was wrong, not that nothing happened.
  • show_in_timeline changes what the user sees and selected in Flocon (device, app, the timeline view saved in their preferences) but never their filters. The graph draws network, database and analytics events only: for a crash or another source, say that its row is in the list (view: list). The request is only registered: it does not tell that the user saw it.
  • flocon_navigate_into_desktop_app changes what the user selected in Flocon (device, app) and saves the timeline view in their preferences: use it when asked to show something, say what you changed, and ask them to go to the Flocon app.
  • set_server_ports restarts the websocket and HTTP servers and disconnects every device until the SDKs reconnect (they must use the new ports): only use it when asked, call get_server_ports first, always tell the user the ports you changed (old and new) and that the devices are disconnected. A port forced by a launch option cannot be changed (error). The MCP port (9042) is not affected.
  • take_screenshot, start_screen_recording and open_flocon_folder act on the device / computer (iOS: the booted Simulator only): use them when asked or when seeing the screen helps. take_screenshot, start_screen_recording and open_deeplink use adb on Android, so they fail for a device whose connectionType (in list_devices) is wifi.
  • take_flocon_desktop_screenshot only reads: it captures the Flocon main window as displayed, with its open dialogs, menus and popups (separate windows such as About are not included).
  • Start from summaries and fetch details only for the calls you need, bodies can be large.

Setting up or migrating Flocon in a project

Flocon is a debugging SDK: the app talks to Flocon Desktop. This skill puts the SDK in a project, or moves an existing integration to a newer version. It does not debug a running app (that is flocon-mcp).

Always follow the docs of the SDK used when they are available: for Kotlin, the repository docs docs/install-kotlin.md (install), docs/connect.md (connection), docs/migration.md (1.x to 2.0, and the per-module no-ops after 2.0.0) and the feature pages; for Swift, the README of openflocon/FloconSwift and its DocC comments; for Flutter, the README of openflocon/FloconFlutter and the Dart doc comments of the packages. If this skill and those docs disagree, the docs win; tell the user.

1. Detect the platform first

Answer from the project files; ask the user only what the files cannot tell.

Look forPlatform
com.android.application / com.android.library, no kotlin("multiplatform")Android
kotlin("multiplatform") with commonMain / iosMainKotlin Multiplatform (an iOS app consuming the KMP framework is still KMP for Flocon)
*.xcodeproj / *.xcworkspace / Package.swift, no Kotlin framework providing FloconSwift (iOS / macOS)
pubspec.yaml with sdk: flutterFlutter (its android/ and ios/ folders are generated host apps: use the Flutter rules, not the Android or Swift ones)

A repository can hold several apps: handle each app with its platform rules.

2. Then detect the version, with that platform's rules

Android / KMP (Kotlin SDK, io.github.openflocon artifacts):

Look forTells you
io.github.openflocon in libs.versions.toml / *.gradle.ktsFlocon already used: read its version
Flocon.initialize( or import io.github.openflocon.flocon.plugins.Kotlin SDK 1.x
startFlocon(Kotlin SDK 2.x: 2.0.0 has one -no-op per module and separate modules (flocon-network-core...); 2.0.1 and later merge them into flocon with a single flocon-no-op

Swift (openflocon/FloconSwift): read the version from Package.resolved / project.pbxproj (revision or version of FloconSwift, and FloconSwiftGrpc). Do not use the start function as a version marker: the Swift SDK has both startFlocon { } and Flocon.initialize(). Details in references/swift.md.

Flutter (flocon* packages on pub.dev): read the version of flocon in pubspec.lock. Do not infer it from the start function. 0.0.x is the current API, not a legacy one: the future 2.0.0 will have its own migration page in references/migrations/. Details in references/flutter.md.

Then pick one path, and read only the file you need:

A future migration is a new file in references/migrations/.

3. Rules for every platform

  • Work on a branch; do not touch unrelated uncommitted changes (use a separate worktree if the tree is dirty).
  • Flocon must never be active in release builds. Say precisely what was delivered: SDK inactive in a configuration (nothing starts or intercepts) is not the same as SDK absent from the binary. Inspect the real build configurations / variants of the project (they are rarely only Debug and Release).
  • Install only the plugins the project really uses; find them by searching the code, do not guess.
  • A plugin that is not installed does nothing at runtime, it does not fail the build. After the change, list every plugin call and check each one is installed.
  • After finding a configuration point (network client factory, image downloader, analytics provider…), search its callers and check it runs in the app target being tested. A hook in a function only the demo calls covers nothing.
  • Do not wrap SDK calls in background tasks "for performance": the logging calls only queue values and send in the background. Measure the app's own mapping cost instead.
  • Ending with a green compile is not proof it works: say what was not run (app on a device, connection to Flocon Desktop, Release build, camera…).
  • Keep the user's device / simulator data, and do not start or restart Flocon Desktop if the user manages it.
  • Never put project, company or app names in docs or skill files you write for Flocon itself.

4. Platform rules

Android / KMP

  • The real modules go in implementation (every variant); a single flocon-no-op in releaseImplementation (and in every other build type that ships) turns Flocon off. Only flocon-accessibility and flocon-qr-scanner keep a -no-op (debug real, release no-op; dependency substitution for KMP). Flocon is absent from the binary only in a minified (R8) build; without R8 it is inactive but its code stays.
  • Compile every variant you touched (debug, release, and others such as an internal build). List the Gradle tasks first, their names depend on flavors.

Swift

  • There is no no-op product. "Inactive in Release" is done with the project's debug compilation condition around imports, calls, types, hooks and menu entries; SPM still links the framework in every configuration. Removing it from the Release binary is a separate, architectural choice: ask once if the user's wording does not settle it.
  • .network only covers URLSession.shared; every other session needs withFlocon() on its configuration before the session is created. Background sessions are not instrumented.
  • Analytics, feature flags, gRPC, App Group storage and dashboards need explicit wiring: see the topic pages listed in references/swift.md.
  • Build the touched schemes and configurations with xcodebuild (list them with xcodebuild -list).

Flutter

  • There is no no-op package. "Inactive in release" is if (kDebugMode) around the start; the packages and their native code stay in the release binary. Removing the Flocon Dart code from it needs a debug-only entry point: ask once if the user's wording does not settle it. See references/flutter.md.
  • Network is only captured for clients wrapped with withFlocon(); top-level http.get(...) and clients created elsewhere are not. Inventory them.
  • Use the API of the installed version (pubspec.lock): the facade (Flocon.analytics, Flocon.featureFlags...) and the top-level functions (floconAnalytics(...)) are two generations, see references/flutter-data.md.
  • The host differs per target (10.0.2.2 Android emulator, localhost iOS Simulator / macOS, the computer's IP on a device), and each target needs its permission (INTERNET, NSLocalNetworkUsageDescription, macOS network entitlement).
  • Run flutter analyze and build the targets the project ships, debug and release.

MCP servers 1

Sponsors

Details

Marketplace
openflocon/Flocon
Source
plugins/flocon
Category
Development