An in-app debugger for iOS. Network traffic (HTTP, gRPC, WebView) with Proxyman-style rules and breakpoints, a UI inspector, push simulation, a file / UserDefaults / Keychain browser, performance monitoring and crash reports — all inside your app, in native SwiftUI.
Home: every tool one tap away |
HTTP, gRPC and WebView in one log |
Inspect and measure any view |
- iOS 15+, Swift 5.9+ (Xcode 15+), SPM.
- No resources.
Donkitself has no third-party code; the package declares grpc-swift, swift-protobuf and swift-nio only for the optionalDonkGRPCproduct. - Opens from a floating bubble, by shaking the device, or with
Donk.show(). - Nothing runs until you call
Donk.start(see Shipping).
Contents: Features · Agent bridge · Installation · Quick start · Configuration · Shipping · Example app · Requirements · License
| Area | What you get |
|---|---|
| Launcher | Floating bubble (tap to open, long-press for quick actions), shake to open, Donk.show() / Donk.show(.network) from code. |
| HTTP | Every URLSession request with full headers, bodies and real URLSessionTaskMetrics. Search, filters, cURL / HAR / text export, repeat request. |
| gRPC | grpc-swift 1.x interceptor. One live record per RPC with a message timeline for streams, metadata, trailers and status. |
| WebView | fetch / XHR / beacon, document navigations, sub-resources and WebSocket / EventSource connections. |
| Rules & breakpoints | Map Local, Rewrite and Breakpoints for HTTP and gRPC. |
| UI inspector | Select, measure, frames, grid and an eyedropper. |
| Performance | CPU, memory, FPS, hitches, hangs with stack traces, thermal state, FPS HUD. |
| Push | Simulate a backend push with the exact payload; history and templates. |
| Storage | Sandbox and App Group files, UserDefaults, Keychain, cookies. |
| Crashes | Crashlytics-compatible signal / NSException handlers, symbolicated reports, MetricKit. |
| Agents | Opt-in MCP bridge: Claude Code or any MCP client reads network entries, crash reports, the UI tree and screenshots of a running simulator app. Read-only, redacted before anything leaves the app. |
Tap the bubble to open donk, long-press it for quick actions (inspector modes, FPS HUD, clear the network log, hide the bubble). The bubble counts captured requests and flashes green, orange or red as requests finish. Home shows app and device info, the "rules active" banner, a tile per tool with live counters, and quick toggles.
Bubble quick actions |
Home dashboard |
Settings: launcher, capture limits, hosts, redaction |
Every URLSession request: Alamofire, URLSession.shared, completion handlers, async/await, uploads, SSE streaming. Full request/response with headers, bodies and real URLSessionTaskMetrics (protocol, TLS, timings). Search across any field, host filter, hidden hosts, cURL / HAR / text export, repeat request. Certificate pinning keeps working: auth challenges are forwarded to your session delegate.
Bodies open as a JSON tree, pretty text or raw, with find-in-body. The list is color-coded by status, and entries changed by a rule are tagged Mocked, Rewritten or Edited. Select in the list lets you tick specific requests and export only those as HAR or text.
Status colors, methods, sizes, durations |
JSON tree with find-in-body |
Timing waterfall from real metrics |
More HTTP screenshots
Overview: protocol, TLS, connection |
cURL / text / HAR export, redacted by default |
Dark mode |
DonkClientInterceptor for grpc-swift 1.x. One live record per RPC with a message timeline for streams, metadata, trailers and status. Protobuf is rendered as JSON (text format as fallback). Exports a grpcurl command. Unary, client-, server- and bidirectional streaming calls are all supported.
Message timeline of a bidi stream |
Call overview: status, service, method |
Live streams and gRPC status codes |
fetch/XHR/beacon with bodies, document navigations (status, headers), sub-resources via PerformanceObserver, WebSocket/EventSource connections. Each entry shows how much could be captured. An optional isInspectable toggle enables Safari Web Inspector.
WebView document, resource, fetch and XHR entries |
Rules in the style of Proxyman: Map Local, Rewrite (request/response: URL, method, headers, body, find/replace, status) and Breakpoints (pause a request or response, edit it, then continue, abort or answer locally). They work for HTTP and gRPC. Patterns match by contains, wildcard or regex, and the editor previews which recent requests a rule would hit. A banner on Home and in the network log shows when rules are active.
Rules, evaluated top to bottom |
Map Local: status, delay, headers, body |
Breakpoint: edit, continue, execute locally or abort |
Tap a view to see its class, size, frame, font, colors, padding to the superview and the hierarchy. Measure the distance between two views. Show the frames of all views. An adjustable grid (cell width/height, columns). An eyedropper with a loupe that copies the HEX value. The app stays usable underneath: Frames and Grid pass touches through.
Select: size and padding to the superview |
Info panel: layout, constraints, appearance |
Measure between two views |
Frames, colored by depth or kind |
Adjustable layout grid |
Eyedropper with loupe and HEX |
CPU (total and per thread), memory footprint vs. the system limit, FPS and hitches, main-thread hangs with stack traces, thermal state. GPU time is experimental. Charts, alerts on abnormal activity, and an FPS HUD that stays above every screen.
CPU and memory, live |
Alerts and hangs |
FPS HUD and alert toasts over the app |
Simulates a backend push with the exact payload (same userInfo, same keys, attachments downloaded like a Notification Service Extension would). Three delivery paths: system banner, direct delegate injection (foreground arrival or tap), and silent didReceiveRemoteNotification. Also .apns export, a history of real pushes, and templates.
Composer with a live banner preview |
History of received pushes |
Built-in and app templates |
A sandbox and App Group file browser with previews (text, JSON, plist, images, SQLite, QuickLook, hex) and editing. A UserDefaults editor with typed values, a Keychain viewer/editor, and cookies.
Files, UserDefaults suites, Keychain, cookies |
File browser |
Typed UserDefaults editor |
Signal and NSException handlers that stay compatible with Firebase Crashlytics, symbolicated reports saved on the device, MetricKit diagnostics, unclean-exit detection. Reports can be shared as an Apple-style .crash text (works with atos) or as JSON.
Signals, exceptions, unclean exits |
Report summary and reason |
Symbolicated backtrace, app frames highlighted |
donk follows the system light/dark appearance.
Coding agents can read what donk captures in a running app: network traffic, crash reports, the view tree with frames in screen points and screenshots. The app dials donk-hub, a small server on your Mac, over a WebSocket (Network.framework, so the traffic is never captured and needs no ATS exception). Agents connect to the hub over MCP, and several agent sessions can share one app.
#if DEBUG
configuration.remote.isEnabled = true // dials ws://127.0.0.1:7337/app
#endifcd mcp && npm install && npm run build && npm start
claude mcp add --transport http donk http://127.0.0.1:7337/mcpPhase 1 is read-only and covers simulator apps. Everything goes through the redaction policy first: configuration.remote.redaction, or the policy from donk Settings when that is nil. While the bridge is enabled, donk Settings shows its hub address and connection status. The wire protocol is in docs/DONKREMOTE.md, the hub and its tools in mcp/README.md.
.package(url: "https://github.com/dimashbk/donk.git", from: "0.3.0")Products:
Donk: everything.DonkCore: models, stores, rules and exporters, with no UI.DonkGRPC: the grpc-swift 1.x interceptor (grpc-swift1.21.0..<2.0.0, swift-protobuf1.25+).
SwiftPM resolves the grpc-swift dependencies for every consumer of the package, but only targets that link DonkGRPC build them.
If your app already links grpc-swift, add donk in the same place (the same Package.swift or the same Xcode project packages), so that SwiftPM resolves one grpc-swift. Link Donk and DonkGRPC into the image that already contains GRPC. That keeps one copy of GRPC and one of DonkCore. See docs/DONKGRPC.md.
-
import Donkre-exports DonkCore and the feature modules. The DonkUI design system is not re-exported: importDonkUIexplicitly if you use its components. -
Performance monitoring has a constant cost while it runs:
- a
CADisplayLinkon the main run loop (60 Hz, or up to 120 Hz if you opt in); - a watchdog that pings the main queue 10 times a second;
- a sampler at 0.5–2 Hz.
Leave
.performanceout ofDonkConfiguration.toolsif you don't need it. - a
-
Link donk into exactly one image. If DonkCore ends up statically linked into two images (for example the app and a dynamic framework or an extension that both link donk), each copy keeps its own stores and swizzles, and the ObjC runtime logs
Class DonkCoreImageSentinel is implemented in both …at launch. To fix it, link donk only from the app target, or turn the module that links donk into a dynamic framework that everything else shares.
import Donk
final class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
#if DEBUG
Donk.installCrashReporter()
#endif
return true
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
#if DEBUG
var configuration = DonkConfiguration()
configuration.network.bypassHosts = ["*.crashlytics.com"]
configuration.storage.appGroupIdentifiers = ["group.com.example.shared"]
Donk.start(configuration)
#endif
return true
}
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
#if DEBUG
DonkPush.didRegister(deviceToken: deviceToken)
#endif
}
}- Call
Donk.installCrashReporter()beforeFirebaseApp.configure(). Crashlytics then keeps receiving every crash, and so does the system crash reporter. - Call
Donk.startas early as possible. Sessions created before it are captured only throughURLSession.shared. Donk.show(),Donk.show(.network),Donk.hide()andDonk.toggle()control the debugger in code.
import DonkGRPC
final class AccountInterceptors: Bank_V1_AccountServiceClientInterceptorFactoryProtocol {
func makeGetAccountInterceptors() -> [ClientInterceptor<Bank_V1_GetAccountRequest, Bank_V1_Account>] {
DonkGRPC.interceptors(host: "api.example.com:443", after: [AuthInterceptor()])
}
}The interceptor can't see :authority, so pass the host to the factory yourself. Create new interceptor instances for every call. If a message uses google.protobuf.Any, register its types with DonkGRPC.register(anyTypes:). Until Donk.start runs (and after Donk.stop), the interceptor passes calls through untouched: nothing is recorded and no rules apply.
Web views are captured automatically when captureWebViews is on: -[WKWebView setNavigationDelegate:] is always hooked, and the WKWebView initializers are hooked too. To attach yourself, call DonkWebViewCapture.attach(to: configuration) or DonkWebViewCapture.attach(to: webView).
cURL, grpcurl, text and HAR exports from the debugger are redacted by default. Values of Authorization, Cookie, Set-Cookie, API-key headers are replaced with ••••, and so are values of JSON keys and query/form fields such as password, token, otp, cvv, cardNumber and pan. To set your own list:
configuration.redaction = RedactionPolicy(
headers: RedactionPolicy.defaultHeaders + ["x-session-id"],
keys: RedactionPolicy.defaultKeys + ["iban", "documentNumber"]
)RedactionPolicy.redact(_:) and the redaction: overloads of CurlExporter, GRPCurlExporter, EntryTextExporter and HARExporter are public, so you can use them for your own exports. Binary bodies are exported as they are.
DonkPush.contentProcessor lets the Banner mode run your Notification Service Extension logic, if that logic lives in shared code:
DonkPush.contentProcessor = { content in await PushEnricher.process(content) }Once a processor is set, donk no longer downloads the attachment itself. To keep the image, call DonkPush.attachMedia(to:keyPaths:) from your processor. It looks up the first attachment URL in userInfo (by default at PushConfiguration.attachmentURLKeyPaths), downloads it through an internal session that is never captured, and appends it to attachments. If no URL is found or the download fails, the content comes back unchanged.
DonkPush.contentProcessor = { content in
content.title = content.userInfo["sender"] as? String ?? content.title
content.body = "Sent you a photo"
return await DonkPush.attachMedia(to: content)
}Everything is set on DonkConfiguration before Donk.start:
| Property | Default | What it does |
|---|---|---|
network.isEnabled |
true |
Turns HTTP capture on or off. |
network.bypassHosts |
[] |
Hosts that are never intercepted (wildcards like *.crashlytics.com). |
captureWebViews |
true |
Captures WKWebView traffic automatically. |
performance.alertsEnabled |
true |
Enables alerts on abnormal activity (CPU, memory, hitches, hangs). |
push.templates |
[] |
Your own push templates (PushTemplate(id:name:payload:), payload is APNs JSON). |
push.attachmentURLKeyPaths |
["fcm_options.image", "imageUrl", "image", "attachment-url", "media-url"] |
Where to look for an attachment URL in userInfo. |
push.recordsIncomingPushes |
true |
Records real pushes into the history. |
storage.appGroupIdentifiers |
[] |
App Group containers shown in the file browser. |
storage.userDefaultsSuites |
[] |
Extra UserDefaults suites shown in the editor. |
showsBubble |
true |
Shows the floating bubble. |
opensOnShake |
true |
Toggles donk when the device is shaken. |
redaction |
nil |
Replaces the export redaction policy (see Export redaction). |
tools |
all DonkTool cases |
Tools that are started and shown: .network, .rules, .performance, .inspector, .push, .storage, .crashes, .settings. A disabled tool is neither started nor shown. |
Launcher, capture limits (max body size, log limit), bypass and hidden hosts, redaction and the breakpoint auto-resume timeout can also be changed at runtime in donk's Settings screen.
Nothing runs until Donk.start or Donk.installCrashReporter() is called: there are no +load hooks, no static initializers and no swizzling at load time. Linking donk without calling it changes nothing at runtime. What matters is that no production code path calls start.
- Gate every call (
Donk.start,Donk.installCrashReporter(),DonkPush.didRegister, …) behind your debug or staging flags:#if DEBUG, or a customDONKcompilation condition set only in internal configurations. - The agent bridge is off by default. Turn on
configuration.remote.isEnabledonly in debug builds: it opens a WebSocket to the hub address and answers read-only requests from it. - SPM links a package into every configuration of the target that depends on it. Tuist and XcodeGen hosts usually work this way, so the donk code is in your App Store binary even when it is never called. If that is unacceptable, depend on donk only from an internal-only target or app flavor.
- These are the private or undocumented APIs donk touches, and when each one runs:
- Inspector: this exists only in builds where
DEBUGorDONK_PRIVATE_APIis defined, and only when "Include SwiftUI elements" is turned on (it is off by default). Select mode then switches on the SwiftUI accessibility runtime through_AXSApplicationAccessibilitySetEnabled(looked up withdlsymin libAccessibility) and restores it afterwards. See Private API flag. - Push: the Inject and Tap delivery modes build
UNNotification/UNNotificationResponseobjects through key-value coding. Recording incoming pushes swizzles theUNUserNotificationCenterdelegate setter and its delegate methods (DonkPush.start,recordsIncomingPushes). - Hang and crash symbolication:
swift_demangleand__cxa_demangleare looked up withdlsymwhile a report is rendered. - Swizzling (public runtime API):
NSURLSession/URLProtocolregistration for capture,WKWebViewinit andsetNavigationDelegate:, andUIWindow.motionEndedfor shake. All of these are installed byDonk.start(or the module'sstart), never at load.
- Inspector: this exists only in builds where
Select mode can list SwiftUI accessibility elements. To do that, DonkInspector turns on the app's accessibility runtime with the private _AXSApplicationAccessibilitySetEnabled, which it looks up with dlsym in libAccessibility.
- When it's compiled in: the code and its strings are compiled only when
DEBUGorDONK_PRIVATE_APIis defined for DonkInspector. A Release build has no trace of it unless you opt in. - Without it: the setting shows as unavailable, and Select works on UIViews only.
- Even when compiled in: "Include SwiftUI elements" is off by default. When you turn it on, the runtime is enabled only while Select is active and restored afterwards.
- If the app is killed during Select: a marker in
Library/Application Support/Donklets the runtime be restored. This happens on the nextDonk.start, on the first Inspector use, or when you callDonkInspector.restoreAccessibilityIfNeeded(). - Assistive tech: donk never turns the runtime off while VoiceOver or Switch Control is running.
To enable it in internal builds that aren't DEBUG:
- Tuist:
PackageSettings(targetSettings: ["DonkInspector": ["SWIFT_ACTIVE_COMPILATION_CONDITIONS": "$(inherited) DONK_PRIVATE_API"]]) - xcodebuild: pass
OTHER_SWIFT_FLAGS='$(inherited) -DDONK_PRIVATE_API'on the command line or in an xcconfig. Build settings on your app target don't reach SPM package targets. - SwiftPM:
swift build -Xswiftc -DDONK_PRIVATE_API
donk uses APIs that need a declared reason in the host app's PrivacyInfo.xcprivacy if they ship in a build you submit:
- File timestamp APIs: the DonkStorage file browser reads creation and modification dates (
NSPrivacyAccessedAPICategoryFileTimestamp, for example reasonC617.1or3B52.1). - System boot time APIs: DonkPerformance and DonkNetwork read
ProcessInfo.systemUptimefor timings (NSPrivacyAccessedAPICategorySystemBootTime, reason35F9.1). - User defaults APIs: the DonkStorage UserDefaults editor reads and writes
UserDefaults(NSPrivacyAccessedAPICategoryUserDefaults, reasonCA92.1; add1C8F.1if you inspect App Group suites).
donk ships no privacy manifest of its own. Declare these reasons in your app's manifest, or leave donk out of the submitted binary.
cd Example && xcodegen generate && open DonkDemo.xcodeprojThe demo has playgrounds for every module: real HTTP traffic, an in-app gRPC echo server, a WebView page, an inspector layout, CPU/memory/hang generators, crash triggers, push templates and storage seed data. The screenshots above were taken in it.
- Architecture and module contracts
- Design system (DonkUI)
- Crash reporter internals
- gRPC integration
- Agent bridge protocol (DonkRemote)
- iOS 15+
- Swift 5.9+ (Xcode 15+)
- Swift Package Manager
DonkGRPConly: grpc-swift1.21.0..<2.0.0and swift-protobuf1.25+
MIT