BHTwitter: a Twitter tweak whose release notes read like a bug report for the platform

What the tweak actually injects

BHTwitter is an iOS tweak for the Twitter app, built as a dynamic library that loads into the host process rather than a standalone application. The README describes it as enhancing the experience with additional features and customization options: get rid of ads, gain access to Twitter Blue features for free, and much more.

The feature list is organised into four groups. General enhancements include downloading videos, including from private accounts, loading photos at the highest quality available, saving tweets as images, undoing a tweet, enabling voice tweets and voice messages in DM, and enabling a new DM search UI.

UI customization is the largest group: a custom tab bar, themes such as Twitter Blue, an app icon changer, a font changer, a padlock, an option to disable the edge-to-edge tweet style, an option to always open links in Safari, and toggles to hide the Spaces bar, hide topics tweets, disable the history feature, disable right-to-left layout, and disable the video layer caption.

Interaction and behaviour adds a Twitter Circle feature, copying profile information, translating bios, and confirmation alerts before tweeting, liking and following. Developer tools include the FLEX debugging tool, which is how you inspect the host app's view hierarchy at runtime.

The README also flags its central dependency plainly: it heavily relies on feature flags, and if a feature stops working the host app most likely removed support for it.

Reading the Makefile to understand the architecture

The `Makefile` is the most informative file in the repository, because it declares exactly which components are compiled and which frameworks are linked.

BHTwitter_FILES = Tweak.x $(wildcard *.m BHDownload/*.m BHTBundle/*.m Colours/*.m JGProgressHUD/*.m SAMKeychain/*.m AppIcon/*.m CustomTabBar/*.m ThemeColor/*.m)
BHTwitter_FRAMEWORKS = UIKit Foundation AVFoundation AVKit CoreMotion GameController VideoToolbox Accelerate CoreMedia CoreImage CoreGraphics ImageIO Photos CoreServices SystemConfiguration SafariServices Security QuartzCore WebKit SceneKit

That single line tells you the source layout. The entry point is `Tweak.x`, and the wildcard pulls in every `.m` file from the root plus six subdirectories, each of which is one cohesive feature area: `BHDownload/` for media downloading with a matching `BHDownloadInlineButton.h` and `.m`, `Colours/` for the colour system, `CustomTabBar/` for the tab bar rewrite, `ThemeColor/` for theming, `JGProgressHUD/` for progress indicators, and `SAMKeychain/` for keychain access. `AppIcon/` holds the alternate icon assets, `lib/` holds static archives, and there are header and implementation pairs at the root for `BHTManager`, `SettingsViewController` and `SimpleAlert`.

The flags are worth reading too: `-fobjc-arc` for automatic reference counting, and a run of `-Wno-` suppressions including `-Wno-deprecated-declarations`, which is the honest admission that a tweak targeting a shipping app will touch deprecated API.

Libraries are `sqlite3 bz2 c++ iconv z`, and the build targets `arm64` at SDK 14.0 with `iphone:clang`. Private frameworks list is `Preferences`, which is how it reads and writes the tweak's own settings, and extra frameworks pull in Cephei, CepheiPrefs and CepheiUI, the preference library that gives the settings screen its iOS look.

Four deployment targets from one checkout

Local setup needs Theos and, for sideloaded or TrollStore builds, cyan:

git clone --recursive https://github.com/BandarHL/BHTwitter
cd BHTwitter
chmod +x ./build.sh
./build.sh [OPTIONS]

The recursive clone matters. A `.gitmodules` file is in the tree, so the submodules carry code the build needs, and a plain clone will fail later in a confusing way.

Four options control the target. `--rootfull` builds for rootfull deployment, `--rootless` for rootless, `--trollstore` for TrollStore, and no option or `--sideloaded` builds for sideloaded deployment. Each produces a different artifact:

./build.sh --sideloaded
# You'll get BHTwitter-sideloaded.ipa in the packages folder.

The rootless and rootfull builds produce versioned Debian packages instead, named after the bundle identifier, version and architecture. The README's examples show 4.2 in those filenames, which is a useful detail: a deb name carries the version, so an upgrade is visible in the filename.

Both IPA paths need a decrypted IPA already in the `packages` folder, and it has to be named `com.atebits.Tweetie2.ipa`. That is the original bundle identifier of the Twitter app, and matching it exactly is what lets the build process the binary. The `Makefile` also reveals a conditional build: when `SIDELOADED` is defined, a `keychainfix` subproject is added, which exists because a sideloaded install has no keychain access entitlement.

For anyone who would rather not set up Theos locally, the README documents a GitHub Actions route: fork the repository, enable workflows, pick the Build and Release BHTwitter workflow, choose a deployment type, and for sideloaded or TrollStore supply a URL to a decrypted IPA, while rootfull and rootless accept any value.

Release notes as a running commentary on X

The releases page is more informative than the feature list, because it records what the platform did to the project.

Version 4.4, published in May 2025, has the most substantive notes. They fix all the crashes in the newer versions, add the new tabs to the hide page, add a DM reply-later page and tags, add 4K media upload, add a voice feature in posts and replies, update the localisations, and remove unnecessary options. It credits two contributors by handle.

Version 4.3 from February 2024 added uploading a custom voice, added the ability to select a URL host such as fxtwitter or vxtwitter for a tweet after copying it, and removed unnecessary options. Version 4.2-1 from December 2023 has no release body at all, which is common for a patch tag.

"Remove unnecessary options" appearing in both 4.3 and 4.4 is worth noticing. A tweak accumulates switches for features the host app has since removed, and pruning them is maintenance nobody thanks you for.

Then there is the warning at the top of the README, which is the most important sentence in the file: do not create issues regarding sign in or tweeting. The stated reason is that Twitter/X added attestation to prevent the use of third-party or modified clients, and that there is nothing a tweak can do about it. Read plainly, that means the most-used features of any Twitter client are the ones this project cannot restore, and the 2,605 stars and 928 forks should be read with that in mind.

The last push to `master` was 2026-07-06, months after the 4.4 release, and there are 29 open issues. The license field is reported as empty, so there is no declared grant to work from.

What this teaches about injecting into a shipping app

The parts of this repository worth studying are structural rather than functional. The component split is the clearest example: `BHDownload`, `Colours`, `CustomTabBar`, `ThemeColor`, `JGProgressHUD`, `SAMKeychain` and `AppIcon` are each a directory, each pulled into the build by one wildcard rather than an enumerated list. Adding a feature means adding a file, not editing a build script, which is the difference between a tweak that survives and one that stops compiling.

The second is that preferences are delegated. Cephei and CepheiPrefs are linked as extra frameworks rather than a settings screen being hand-written, and `SettingsViewController` is a thin layer over that. `TWHeaders.h` at the root is the header that carries the host app's interface declarations, so code depending on Twitter's own classes has one place to look.

The third is honest about the platform's direction. When a host app adds attestation, no amount of Objective-C cleverness gets past it, and the project says so instead of pretending otherwise. That is worth more to a reader than another feature bullet.

The fourth is the version pinning in the `Makefile`: `iphone:clang:latest:14.0` and `ARCHS = arm64`. A tweak is a binary artefact compiled against a specific SDK, so those two lines tell you what it can and cannot load onto, and they will need changing when Apple moves.

None of this makes the tweak safe to run, or free of consequences for the account you sign in with. It makes the engineering legible, which is the part you can take from it.

Repository contents and what they imply

The tree is larger than it looks and the extras are informative. `control`, `BHTwitter.plist` and `Makefile` are standard Theos packaging files, and the presence of an `ffmpeg/` directory alongside a `BHDownload/` component tells you the download and upload work leans on a bundled FFmpeg rather than on AVFoundation alone

`ffmpeg/` and `lib/` both being directories, with `BHTwitter_OBJ_FILES` set from `find lib -name '*.a'`, means prebuilt static archives are committed rather than built from source. That is normal for a media project, and it is also the part of the build most likely to rot, since a bundled library compiled years ago against an older toolchain is exactly the kind of thing that breaks on a new Xcode.

There is also a `layout/` directory, which is Theos's mechanism for placing files into specific system paths on install, and `packages/`, where build outputs land. The presence of `1.png` through `4.png` at the root is simply the screenshots the README embeds in its table, kept in the repository rather than an images directory.

`layout/` alongside four different packaging targets is worth pausing on. The same source produces a rootful deb, a rootless deb, a sideloaded IPA and a TrollStore IPA, and each of those installs somewhere different on the device. The conditional `keychainfix` subproject in the `Makefile` is the visible trace of that, since a sideloaded build needs help with keychain access that the other three targets get for free.

Editorial conclusion

BHTwitter is worth reading as an engineering artifact rather than as a product, because it demonstrates what a well-organised Theos tweak looks like when the host app is hostile to modification. The `Makefile` is unusually readable, the source is split into cohesive Objective-C components rather than one growing file, and the build script plus GitHub Actions workflow give you four distinct deployment targets from one checkout. The important caveat is the one the project states most loudly: X added attestation to block third-party clients, so sign-in and tweeting are outside what any tweak can fix. Its 4.4 release credits two contributors and describes fixes for crashes in newer versions, which tells you the maintenance burden is real. Cloning recursively and running `./build.sh --rootless` is the whole setup, and every IPA build needs your own decrypted copy of the app first.

Frequently asked questions

Official sources

1. BandarHL/BHTwitter on GitHub
2. Issues
3. README
4. Releases