The Problem

Developers and power users who want a tweaked iOS/iPadOS Twitter client face two issues: the official app blocks third‑party modifications, and existing forks often retain unwanted branding or lack ad‑blocking features. Maintaining a custom client also requires juggling large binary assets that bloat the repository and insecure CI defaults.

What This Does

NeoFreeBird is a fork of the original Twitter/X iOS client that restores legacy branding, integrates the community‑maintained BHTwitter ad‑blocker, and disables several proprietary features. The bulk of the UI assets live under assets/classic/ (e.g., Assets.car, LaunchScreen.nib, and a full set of localized .strings). Branding overrides are stored in the Branding/ folder (icons, badge images, screenshots). The only executable source code in the repo is a three‑file Safari extension located at:

  • assets/main/PlugIns/OpenTwitterSafariExtension.appex/background
  • assets/main/PlugIns/OpenTwitterSafariExtension.appex/content
  • assets/main/PlugIns/OpenTwitterSafariExtension.appex/popup

These JavaScript files implement the extension’s background script, content script, and UI popup respectively.

How It Is Wired

Execution starts in the iOS app bundle (not explicitly listed but implied by the presence of .car and .nib resources). When the app launches, Xcode loads the compiled resources from assets/classic/. The Safari extension is registered via the OpenTwitterSafariExtension.appex bundle; iOS invokes its background script (background) as the entry point for extension lifecycle events (install, activate). The background script injects the content script into web pages matching Twitter URLs, which modifies the DOM to replace X branding and inject BHTwitter functionality. The popup script supplies the small UI shown when the user clicks the extension icon. No internal module imports exist—each script is isolated, so the call graph consists of three leaf nodes with no circular dependencies.

Because the JavaScript files are the only programmatic components, the blast radius of any change is limited to the extension’s behavior. Core UI changes (icons, splash screens) are driven by the asset bundles, not by code, and therefore require rebuilding the Xcode project rather than editing source.

How To Use It

The repository does not contain explicit build scripts, a package.json, or a Makefile. To compile and install the client you will need the standard iOS toolchain:

# Prerequisites
# - Xcode with iOS SDK
# - AltStore or SideStore for sideloading (see README badges)

# Typical workflow (manual)
open NeoFreeBird.xcodeproj   # Xcode project not listed but expected in the upstream repo
# Adjust signing, then Product → Archive → Export for Ad‑Hoc deployment
# Use AltStore/SideStore to install the .ipa on a device

If you only need the Safari extension, copy the three JavaScript files from assets/main/PlugIns/OpenTwitterSafariExtension.appex/ into an existing Safari Extension target and rebuild with Xcode.

No configuration files or environment variables are required beyond the standard iOS signing credentials. The repo lacks a lockfile, so dependency versions are managed entirely by Xcode.

Real‑World Use

A power user installs the generated .ipa via AltStore on an iPhone, then enables the Safari extension from Settings → Safari → Extensions. When browsing twitter.com, the content script replaces the X logo with the original Twitter branding, blocks ad network requests, and unlocks select “Twitter Blue” UI elements, all without needing a separate API key.

Code Health & Issues

  • Medium – Large binaries – assets/main/Assets.car (10 MB) and other >5 MB blobs inflate clone size. Fix: Move to Git LFS or external storage.
  • Medium – Persistent CI credentials – .github/workflows/Build-NeoFreeBird.yml checks out the repo with the default token retained. Fix: Add persist-credentials: false to the checkout step.
  • Low – Missing workflow timeout – Same workflow lacks timeout-minutes. Fix: Define a realistic timeout per job.
  • SDLC – No tests – Repository contains no test files, leaving code paths unverified.
  • SDLC – No LICENSE – Absence of a license file makes redistribution rights unclear.
  • CI – GitHub Actions present – CI is configured but lacks lockfiles and dependency snapshots.

The Bottom Line

NeoFreeBird provides a functional, branding‑reverted Twitter client for iOS with integrated ad‑blocking, but the repo is missing essential build documentation, a license, and automated tests. Large binary assets and insecure CI defaults further increase maintenance overhead. It is suitable for developers comfortable with Xcode and manual signing who need a quick, modifiable client, but it requires additional housekeeping before being production‑ready.