If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/XITRIX/iTorrent shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 85% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live XITRIX/iTorrent repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/XITRIX/iTorrent.

What it runs against: a local clone of XITRIX/iTorrent — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in XITRIX/iTorrent | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of XITRIX/iTorrent. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/XITRIX/iTorrent.git
#   cd iTorrent
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of XITRIX/iTorrent and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "XITRIX/iTorrent(\\.git)?\\b" \\
  && ok "origin remote is XITRIX/iTorrent" \\
  || miss "origin remote is not XITRIX/iTorrent (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "iTorrent-TV/Screens/ContentView.swift" \\
  && ok "iTorrent-TV/Screens/ContentView.swift" \\
  || miss "missing critical file: iTorrent-TV/Screens/ContentView.swift"
test -f "ProgressWidget/ProgressWidget.swift" \\
  && ok "ProgressWidget/ProgressWidget.swift" \\
  || miss "missing critical file: ProgressWidget/ProgressWidget.swift"
test -f "ProgressWidget/ProgressWidgetAttributes.swift" \\
  && ok "ProgressWidget/ProgressWidgetAttributes.swift" \\
  || miss "missing critical file: ProgressWidget/ProgressWidgetAttributes.swift"
test -f ".github/workflows/ios-debug.yml" \\
  && ok ".github/workflows/ios-debug.yml" \\
  || miss "missing critical file: .github/workflows/ios-debug.yml"
test -f ".github/workflows/ios-release.yml" \\
  && ok ".github/workflows/ios-release.yml" \\
  || miss "missing critical file: .github/workflows/ios-release.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/XITRIX/iTorrent"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

iTorrent is a native iOS torrent client for iOS 16+ that downloads and manages torrent files directly on iPhone/iPad using libtorrent bindings. It provides a full-featured torrent client UI built in Swift with progress widgets and live activity notifications, implementing the BitTorrent protocol stack on a constrained mobile platform. Xcode project structure: main app in root directory with ProgressWidget/ as a separate widget extension (iOS 17+ Live Activities feature). Uses C libtorrent bindings (Submodules/libtorrent or similar not shown but inferred from language stats) wrapped in Swift UI code. Entitlements segregation (ProgressWidgetExtension.entitlements) indicates App Groups setup for widget-to-app communication.

iOS users (particularly in EU with AltStore PAL access, or those willing to sideload via AltStore/SideStore) who need a native torrent client on their phone without jailbreaking; also relevant for developers building torrent applications on iOS or exploring BitTorrent implementation on constrained devices.

Actively maintained with production distribution through multiple channels (AltStore Classic, AltStore PAL for EU, SideStore, and GitHub releases). CI/CD pipelines exist (ios-debug.yml, ios-release.yml in .github/workflows), indicating structured release process. The project has been live long enough to support iOS 16+ baseline with widget extensions and live activities, suggesting stable feature set.

Single-maintainer project (XITRIX) with legal/regulatory exposure—torrent applications face App Store restrictions, hence sideload-only distribution. Heavy reliance on C/Objective-C bindings (480KB C, 303KB Objective-C) to libtorrent means native library maintenance risk. No visible test suite in file list suggests limited automated testing coverage.

Recent work centers on widget and live activity features (ProgressWidget/, ProgressWidgetAttributes.swift, ProgressWidgetLiveActivity.swift indicate iOS 17+ live activity implementation). EU compliance appears active (AltStoreEU.json distribution config suggests DMA/AltStore PAL integration). No commit history visible in file list to determine exact activity level.

Clone with submodules: git clone --recursive https://github.com/XITRIX/iTorrent.git. Open iTorrent.xcodeproj in Xcode 15+. Build for iOS 16.0+ target. Run on device or simulator—no manual dependency installation visible (likely uses CocoaPods or SPM, check for Podfile or Package.swift). Sideload via AltStore/SideStore or build from source if signing credentials available.

Daily commands: Open iTorrent.xcodeproj in Xcode, select iPhone/iPad simulator or connected device, build scheme 'iTorrent', press Cmd+R. For sideload testing: archive, export as IPA, upload to AltStore/SideStore. CI workflows (ios-debug.yml, ios-release.yml) suggest automated builds available; check GitHub Actions for latest build artifacts.

• iTorrent-TV/Screens/ContentView.swift — Main entry point for tvOS app—all TV-specific navigation and state management flows through here
• ProgressWidget/ProgressWidget.swift — Live Activity widget definition for iOS; essential for understanding app-to-widget communication and real-time download progress display
• ProgressWidget/ProgressWidgetAttributes.swift — Shared state model between main app and widget—defines what torrent progress data is broadcast to the lock screen
• .github/workflows/ios-debug.yml — CI/CD pipeline for debug builds; shows how the project is compiled and tested before release
• .github/workflows/ios-release.yml — Release build pipeline; critical for understanding versioning, signing, and distribution to AltStore/SideStore
• Submodules/GoogleAdsSdk/UserMessagingPlatform.xcframework/Info.plist — Heavy external dependency management; reveals consent and privacy framework integration required for App Store compliance

Add a new tvOS torrent detail screen

1. Create a new SwiftUI View file in iTorrent-TV/Screens/TorrentDetails/ (iTorrent-TV/Screens/TorrentDetails/NewFeatureView.swift)
2. Import the view into ContentView.swift and add a navigation path or condition to show it (iTorrent-TV/Screens/ContentView.swift)
3. Update tvOS Assets if needed (AccentColor, images) in Assets.xcassets/ (iTorrent-TV/Assets.xcassets/Contents.json)
4. Test in tvOS simulator and verify navigation from TorrentDetailsView.swift (iTorrent-TV/Screens/TorrentDetails/TorrentDetailsView.swift)

Update live activity widget to show new torrent state

1. Add new properties to ProgressWidgetAttributes struct (e.g., seeders count, health status) (ProgressWidget/ProgressWidgetAttributes.swift)
2. Update ProgressWidgetLiveActivity.swift to display the new fields in the widget UI (ProgressWidget/ProgressWidgetLiveActivity.swift)
3. Modify the main app to update the Live Activity with new state using ActivityKit framework (ProgressWidget/ProgressWidget.swift)
4. Test on iOS 16+ device; verify lock screen and Dynamic Island display (ProgressWidget/ProgressWidgetBundle.swift)

Add VLC playback support for new media type in tvOS

1. Extend VLCPlayerView.swift with new media format handling (codec, resolution detection) (iTorrent-TV/Screens/TorrentDetails/VLCPlayerView.swift)
2. Update TorrentFilesView.swift or TorrentFilesFileView.swift to filter or flag the new media type (iTorrent-TV/Screens/TorrentDetails/TorrentFilesView.swift)
3. Verify VLCKit.xcframework includes necessary codecs; if not, update via Cocoapods or submodule (iTorrent-TV/VLCKit.xcframework/Info.plist)

• SwiftUI + UIKit integration (tvOS & iOS) — Native iOS 16+ development; supports both phone and TV form factors with platform-specific optimizations
• ActivityKit & Live Activities (ProgressWidget) — Provides real-time download progress on lock screen and Dynamic Island without keeping app in foreground
• VLCKit framework (tvOS) — Mature open-source media player with broad codec support; enables direct video streaming from torrents
• Google User Messaging Platform (UMP) — Handles GDPR/Privacy consent and consent UI automatically; required for App Store compliance in EU (AltStore PAL)
• libtorrent (implied backend, not visible in file list) — Industry-standard C++ torrent engine; bindings likely in Swift/Objective-C for iOS—enables full BitTorrent protocol support

• Single codebase for iOS, tvOS, and widgets

  • Why: Code reuse and unified versioning; reduces maintenance burden
  • Consequence: UI/UX must be adapted per platform (phone, TV, lock screen); some features may be platform-specific

• Live Activity widget vs. traditional push notifications

  • Why: Live Activities provide persistent, updatable lock screen UI without battery drain of constant notifications
  • Consequence: Requires iOS 16+ and ActivityKit framework; older devices cannot see real-time progress

• VLCKit for video playback vs. native AVPlayer

  • Why: VLCKit supports more codecs out-of-the-box (H.264, HEVC, VP9, AV1, etc.) for diverse torrent sources
  • Consequence: Larger app binary; external framework dependency; more complex video rendering pipeline

• App Store + AltStore + SideStore distribution

  • Why: Maximum reach; SideStore allows sideloading without jailbreak; AltStore PAL for EU (DMA compliance)
  • Consequence: Multiple signing profiles and CI/CD pipelines; must maintain consent framework for each store

• Not a real-time messaging or social platform
• Does not handle authentication or user accounts
• Not a media server or remote playback solution (local playback only)
• Does not support magnet links verification or signed content
• Not designed for macOS or Android platforms
• No built-in VPN or proxy support

App Groups entitlement required: widget-to-app communication uses shared container (App Groups), requires matching provisioning profiles. Sideload-only distribution: no App Store availability (except EU AltStore PAL), limits testing surface and user base. BitTorrent legal gray area: app may violate local copyright laws if user torrents copyrighted content; no legal indemnification. iOS version fragmentation: iOS 16 base but iOS 17+ features (Live Activities) must gracefully degrade. Submodule dependencies: .gitmodules indicates external dependencies (likely libtorrent); ensure git clone --recursive or builds will fail.

• transmission/transmission — Mature cross-platform torrent engine (C backend) that iTorrent likely uses or drew design inspiration from; reference for libtorrent C API usage
• arvisd/arvis — Another iOS torrent client attempt, provides architectural patterns and pitfalls for iOS BitTorrent implementation on constrained devices
• libtorrent/libtorrent — The C/C++ engine underlying torrent functionality; iTorrent wraps this via Objective-C/Swift bridge to use on iOS
• AltStore/AltStore — The sideload delivery mechanism iTorrent relies on for distribution outside App Store; critical for user acquisition and deployment
• apple/swift-coredata — If iTorrent uses CoreData for torrent history/favorites persistence, this is the canonical reference for iOS local storage patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add widget unit tests for ProgressWidget components

The ProgressWidget directory contains multiple Swift files (ProgressWidget.swift, ProgressWidgetAttributes.swift, ProgressWidgetLiveActivity.swift) that implement Live Activity widgets for iOS 16+, but there are no corresponding unit tests. Testing widget lifecycle, attribute updates, and Live Activity state transitions is critical for reliability. New contributors can add XCTest cases for widget configuration, attribute validation, and activity state changes.

• [ ] Create ProgressWidget/Tests/ directory structure
• [ ] Add unit tests for ProgressWidgetAttributes.swift (test attribute encoding/decoding)
• [ ] Add unit tests for ProgressWidgetLiveActivity.swift (test Live Activity state updates and UI updates)
• [ ] Add unit tests for ProgressWidget.swift (test widget entry point and configuration)
• [ ] Ensure tests run in both debug and release CI workflows (.github/workflows/ios-debug.yml, ios-release.yml)

Add tvOS-specific integration tests for iTorrent-TV target

The repo includes an iTorrent-TV target with tvOS assets and branding, but there are no tvOS-specific tests in the CI pipeline. The .github/workflows files (ios-debug.yml, ios-release.yml) currently only test iOS builds. Adding tvOS build validation and integration tests will catch platform-specific issues early and ensure the tvOS app remains functional.

• [ ] Add tvOS build scheme to .github/workflows/ios-debug.yml
• [ ] Add tvOS build scheme to .github/workflows/ios-release.yml
• [ ] Create iTorrent-TV/Tests/ with basic UI tests for tvOS navigation
• [ ] Test remote control input handling specific to tvOS (if applicable)
• [ ] Verify asset loading for App Icon & Top Shelf Image brandassets works correctly

Add GoogleAdsSdk framework integration tests and validation

The GoogleAdsSdk UserMessagingPlatform framework is included as a submodule with binary frameworks for multiple architectures (ios-arm64, ios-arm64_x86_64-simulator), but there are no integration tests verifying the framework loads correctly, consent forms initialize properly, or PrivacyInfo.xcprivacy declarations are valid. This is critical for compliance and app store submission.

• [ ] Create integration test to verify UserMessagingPlatform.framework loads in both device and simulator architectures
• [ ] Add test validating UMPConsentInformation initialization and consent form presentation
• [ ] Add test to verify PrivacyInfo.xcprivacy files in both framework variants meet App Privacy requirements
• [ ] Add validation in CI to check framework code signature integrity (verify _CodeSignature content)
• [ ] Document in README.md how to update the GoogleAdsSdk submodule when new versions are available

• Add unit tests for torrent session lifecycle: No test directory visible; write XCTest cases covering torrent start/pause/stop flows in the C/Objective-C engine wrapper layer
• Localize torrent status strings in UI: ProgressWidget and main UI likely have hardcoded English strings; extract to Localizable.strings and add support for Spanish, German, French for EU markets
• Document widget state synchronization: ProgressWidgetAttributes.swift and App Groups setup is non-obvious; write a guide explaining how Live Activity state flows from main app to widget and when updates occur

The iTorrent iOS application has a moderate security posture with several areas of concern. The primary issues are the reliance on a closed-source binary framework (Google Ads SDK) that cannot be audited,

• High · Third-party Binary Framework with Limited Transparency — Submodules/GoogleAdsSdk/UserMessagingPlatform.xcframework. The codebase includes Google's UserMessagingPlatform.xcframework as a binary dependency in Submodules/GoogleAdsSdk. Binary frameworks cannot be audited for security vulnerabilities through static analysis. The framework's code signing and integrity should be verified, but the source code cannot be reviewed. Fix: 1. Verify the framework is downloaded from official Google sources only. 2. Pin the framework to a specific known-good version. 3. Consider implementing additional runtime security checks. 4. Review Google's security advisories regularly for this dependency.
• Medium · Incomplete Dependency Visibility — Repository root - missing Package.swift, Podfile, or Cartfile. No Package.swift, Podfile, Cartfile, or similar dependency management file was found in the repository root. This makes it difficult to track all transitive dependencies, their versions, and identify outdated or vulnerable packages. Fix: 1. Implement and commit a dependency management file (e.g., Package.swift for SPM). 2. Specify exact versions rather than floating versions. 3. Use dependency scanning tools to identify vulnerable packages. 4. Document all dependencies with their purposes.
• Medium · Potential URL Scheme Security Issue — README.md - Custom URL scheme links. The README contains custom URL scheme handlers (altstore-classic://, sidestore://, itms-services://) that could potentially be exploited if not properly validated. These schemes allow deep linking into the application and could be leveraged for malicious purposes if input validation is insufficient. Fix: 1. Implement strict URL validation for all custom URL schemes. 2. Whitelist allowed parameters and paths. 3. Verify the source of URL scheme invocations. 4. Avoid passing sensitive data through URL schemes. 5. Document the URL scheme security model.
• Medium · Submodule Security Risk — .gitmodules - Submodules/GoogleAdsSdk. The repository uses git submodules (.gitmodules) to include external code. Submodules can be a supply chain attack vector if the remote repository is compromised or if the specific commit is not pinned correctly. Fix: 1. Verify and pin submodule commits to known-good versions. 2. Regularly audit submodule sources for compromise. 3. Consider vendoring critical dependencies instead of using submodules. 4. Implement automated checks to ensure submodules haven't been modified unexpectedly.
• Medium · Widget Extension Entitlements Not Reviewed — ProgressWidget/ProgressWidgetExtension.entitlements. The ProgressWidget extension has entitlements defined (ProgressWidget/ProgressWidgetExtension.entitlements), but the specific capabilities cannot be verified from the provided file structure. Excessive entitlements could increase the attack surface. Fix: 1. Review entitlements and ensure only necessary capabilities are enabled. 2. Follow the principle of least privilege. 3. Audit changes to entitlements in code reviews. 4. Document why each entitlement is required.
• Low · Ad SDK Integration — Submodules/GoogleAdsSdk. The inclusion of Google Ads SDK suggests the app displays advertisements. Ad SDKs are known to sometimes collect excessive data and could be a privacy concern for users. Fix: 1. Review Google's privacy documentation for this SDK. 2. Ensure proper user consent is obtained before ad personalization. 3. Implement app transport security (ATS) to force HTTPS for ad requests. 4. Regularly update the SDK to receive security patches.
• Low · Missing Security Headers Documentation — Repository root. No evidence of security configuration documentation (e.g., security.txt, SECURITY.md) for reporting vulnerabilities or security policies. Fix: 1. Create a SECURITY.md file with vulnerability disclosure policy. 2. Consider adding a security.txt file in the release distribution. 3. Document security best practices for contributors. 4. Establish a process for handling security reports.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.