stephen/StikDebug
1
0
Fork 0
mirror of https://github.com/StikDebug/StikDebug.git synced 2026-10-16 04:20:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
An on-device debugger/JIT enabler for iOS versions 17.4+, powered by idevice. https://stikdebug.xyz/
766 commits 2 branches 10 tags 516 MiB
Find a file
Claude a7792d0289
Switch route data fetch from around() to bbox: fixes inconsistent bus stops 
Bus stops loaded inconsistently even after the previous chunking fix.
Investigation against the live Overpass API found two compounding root
causes:

1. Overpass's around(radius, point-list) operator costs scale with
   points-in-list x candidate-elements-in-area. A single chunk at the
   previous chunkMaxPoints=160 reliably timed out; even much smaller
   chunks (25-60 points) took anywhere from 3s to 23s depending on how
   road-dense the area was -- the same chunk size that was fine in a
   quiet area could time out in a busy one, which is exactly the
   "sometimes works, sometimes doesn't" behavior reported.

2. When Overpass's own [timeout:N] elapses, it replies HTTP 200 with an
   empty elements array and a "remark" field describing the error --
   not an error status. The client only checked the HTTP status code, so
   a timed-out chunk was silently indistinguishable from "no stops near
   this stretch of road" and never retried or logged.

Fixes:
- Replace the around() query with a bounding-box query per chunk. A bbox
  test is an O(1) rectangle check per candidate regardless of route
  shape or point density, unlike around(). Verified live: a chunk that
  took 16-23s (or timed out) via around() resolved via bbox in 2-8s for
  the same area, including a deliberately pathological zigzag route
  whose bbox came out much larger than the route itself.
- Chunk the route by real-world distance (~5km) instead of point count,
  since query cost no longer depends on point density -- this also
  simplifies chunk building (no separate query-string downsampling step).
- Decode the "remark" field and treat any non-nil value as a failure so
  a server-side timeout is retried and logged instead of silently
  accepted as empty data.
- Retry each chunk once with a short backoff before giving up, since the
  public Overpass instance is a shared, load-dependent resource where a
  single slow response shouldn't cost that stretch of road its data.

Verified the exact query shape and decoder assumptions against the live
Overpass API across multiple route shapes (realistic 5km stretch,
dense-area chunk, pathological zigzag) -- all resolved in under 8s with
correct bus stop / speed limit extraction.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013DNqCsHShA4yNqgZ6ZZQy3
2026-07-15 05:03:06 +00:00
.github Remove Swift Package CI workflow that can never pass 2026-07-14 22:19:01 +00:00
assets Change StikJIT to StikDebug 2026-05-20 09:07:55 -04:00
StikDebug Switch route data fetch from around() to bbox: fixes inconsistent bus stops 2026-07-15 05:03:06 +00:00
StikDebug.xcodeproj 3.1.6 2026-06-16 21:53:53 -06:00
StikDebugTests 3.1.5 2026-05-31 20:07:01 -04:00
StikDebugUITests Change StikJIT to StikDebug 2026-05-20 09:07:55 -04:00
.gitignore Hopefully fix some weird issues 2026-05-20 10:07:09 -04:00
CODE_REVIEW_REPORT_BY_FABLE_5.md Rename CODE_REVIEW_REPORT.md to CODE_REVIEW_REPORT_BY_FABLE_5.md 2026-07-14 16:02:18 -07:00
info.md Clarify data collection statement for StikDebug 2026-02-25 13:52:13 -05:00
LICENSE Create LICENSE 2025-03-27 06:46:57 -04:00
README.md Keep JIT/debug sessions alive when backgrounded and support cellular 2026-07-14 08:59:20 +00:00

README.md

Logo

StikDebug

An on-device debugger/JIT enabler for iOS versions 17.4+ powered by idevice.


Features

  • JIT: Enable Just In Time compilation for sideloaded apps that have the get-task-allow entitlement.
  • App Launching: Launch every app installed on your device.
  • Console: Live app and system logs.
  • Scripts: Manage automation scripts (mainly used for iOS 26 JIT).
  • App Expiry: See when apps will expire and install/remove profiles.
  • Device Info: View detailed device metadata.
  • Processes: Inspect running apps/processes and terminate them.
  • Location Simulator: Simulate the GPS location of your device.

Download

Note

Notice: StikDebug is no longer available on the App Store. Please use the official download methods below.

Compatibility

iOS Version Status Notes
1.0 – 17.3.X Not supported Uses Different Connection Protocols
17.4 – 18.x Fully supported Stable
26.0+ Supported Limited App Availability (Developers need to update their apps to work.)

How to Enable JIT

StikDebug enables JIT for sideloaded apps on iOS 17.4+ without needing a computer after the initial pairing setup.

Requirements

  • StikDebug installed (via AltSource, direct .ipa, or self-built)
  • A valid pairing file (.plist / .mobiledevicepairing) for your device
  • SideStore / AltStore / similar sideload tool (for app refreshing)
  • A loopback VPN such as LocalDevVPN

Steps

  1. Obtain a pairing file

  2. Set up VPN

    • Launch LocalDevVPN and enable the VPN.

  3. Enable JIT for an app

    • Launch StikDebug and tapp the Enable JIT button.
    • Select your sideloaded app from the list in StikDebug.

Troubleshooting

  • "Connection dropped" or loopback errors → Check iOS version compatibility / beta warnings.
  • Heartbeat errors → Ensure that LocalDevVPN is on. Any network works (Wi-Fi or cellular); the tunnel rides the VPN, so cellular-only is supported. It may also be a pairing file issue.
  • Session drops after switching to another app → Keep the background keep-alive enabled (Settings → Background Keep-Alive). While a JIT/debug session is active, StikDebug plays inaudible audio and holds a background assertion so the session survives being switched out of the app instead of timing out.
  • Pairing file issues → Replace file with device unlocked & trusted.
  • Still stuck? Join the Discord with logs/screenshots.

Building from Source

Requirements

  • macOS (latest recommended)
  • Xcode 16+ (Xcode 26+ preferred for iOS 26+ support)
  • iOS device on iOS 17.4+ (for testing)
  • Git
  • Basic Xcode/Swift knowledge

Steps

  1. Clone the repo

    git clone https://github.com/StephenDev0/StikDebug.git
cd StikDebug

  2. Open in Xcode

    • Launch Xcode
    • Open StikDebug.xcodeproj

  3. Configure signing

    • Select the StikDebug target
    • Go to Signing & Capabilities
    • Sign in with your Apple ID (free or paid developer account)
    • Set a unique Bundle Identifier (e.g., com.yourname.StikDebug)

  4. Build & install

    • Select your connected device
    • Press Cmd + R (or Product → Run)
    • Trust the certificate on device: Settings → General → VPN & Device Management

After install, follow the JIT setup steps above (pairing import, etc.).

Contributing

Thank you for your interest in contributing to this project. Contributions of all kinds are welcome.

Reporting Bugs

If you discover a bug, please open an issue and include:

  • A clear and descriptive title
  • Steps to reproduce the issue
  • Expected behavior vs. actual behavior
  • Relevant logs, screenshots, or environment details (iOS version, device model, etc.)

Suggesting Features

To propose a new feature, open a feature request issue and provide:

  • A clear description of the feature
  • The problem it solves or the use case it addresses
  • Any relevant examples or implementation ideas

Code Contributions (Best Practices)

  • Follow normal Swift and SwiftUI style.
  • Write clear and easy to understand code.
  • Keep your changes consistent with how the project is already set up.
  • Make sure everything builds and works without errors.

We appreciate your time and effort in helping improve this project.

Code Help

Ask DeepWiki

License

StikDebug is licensed under AGPL-3.0. See LICENSE for details.