Need help with
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

133 Stars 49 Forks 5.3K Commits 635 Opened issues


Something Awful Forums browser for iOS

Services available


Need anything else?

Contributors list


Awful is an iOS 9.0+ app that's Better Than Safari for browsing the Something Awful Forums. Its story is told in its thread (and the thread before that (and the thread before that (and the thread before that))).

Not sure what to work on? There's a list of issues, or just post in the thread and someone will share their pet peeves for your amusement!

Screenshot of Awful as it appears on an iPhone

An unofficial app

This app is not endorsed by Something Awful.


You need Xcode 11 or 12 to build and run Awful. You can download Xcode for free from Apple. Then:

  1. Clone the repository:
    git clone --recursive Awful-app
  2. Open the Xcode workspace and build away:
    xed Awful-app

You may see build warnings of the form "Unable to find included file '../Local.xcconfig'". You should still be able to build and run, just with a couple of features turned off. If you'd like to enable those features, or just make the warnings go away, please scroll on down to the "Local build settings" section below.

The only required dependencies for building Awful that are not included directly in this repository are those managed by Swift Package Manager. Files generated by other utilities are included in the repository. The only submodule is the thread-tags repository, which is not strictly needed for building; if you don't need it, you can leave off the

part from step one.

If you'd like to build to your device, set the

build setting as mentioned in the Local build settings section below.

Optional dependencies

There are optional dependencies for building Awful. You only need them if you're working on the relevant part of the app.

  • Swift Package Manager is the preferred way to add dependencies. If at all possible, please use it.
    • Running into "duplicate symbol" warnings? Add the dependency to the
      target instead.
  • Manual installation is totally fine. Drag the built binary or xcodeproj on in.
  • CocoaPods manages some of our dependencies.
    • There's a
      nearby if you want to use a known working version of CocoaPods.
  • No matter how you add a dependency, please update
    with the name and license of the dependency. We do not use CocoaPods-generated acknowledgements.
  • LESS helps us write CSS. If you're modifying the themes for displaying posts (these are files like
    ), please install LESS:
    1. Install homebrew.
    2. Open Terminal and install node:
      brew install node
    3. In Terminal, install less:
      npm install less -g
    4. Now build the Xcode project and the CSS files will be regenerated.

Local build settings

There are some local build settings that can be useful to include but should not be committed to a public repo. Store those in an Xcode configuration file at

; see Local.sample.xcconfig for an example. You'll get a build warning until you put a file at that location; it can be an empty file if you just want Xcode to be quiet.

Awful uses an App Group to communicate and share data with the Smilie Keyboard. Unfortunately, App Group identifiers must be unique, so we can't simply set it up in this repository and have it work for everybody work. By default, Awful builds without an App Group configured, which means that the Smilie Keyboard won't be able to download new smilies, remember recent smilies, or store favourite smilies. If you like, you can:

  1. Create an App Group in your iOS Developer account.
  2. Copy
  3. Copy and paste your App Group identifier into
  4. Set the
    build setting in
    for the targets
    for a suggested setup).
  5. After a build and run, full keyboard functionality should be yours.


There are unit tests, that don't cover much, running continuously via GitHub Actions.

Build Status

Updating dependencies

Dependencies not managed via CocoaPods or Swift Package Manager are placed in the Vendor folder and manually kept up-to-date. They include:

  • ARChromeActivity and TUSafariActivity assets. We've implemented our own
    subclasses but continue to use the libraries' images.

Version scheme

Bump the major version when changing the minimum required iOS version (deployment target). Otherwise, bump the minor version.

Also, when changing the iOS deployment target, please tag the last commit that supports any no-longer-supported deployment target(s) and update the table in the section "iOS deployment targets" below.

Handy utilities

If you peek in the Xcode folder you'll find:

  • beta
    , a script that bumps the build number and then runs
    to create an archive suitable for uploading to App Store Connect. See
    beta --help
    for more, including how to set up automatic uploads to App Store Connect.
    • If you've released to the App Store, it's time to bump at least the minor version number by passing the
      parameter, e.g.
      beta --minor
  • bump
    , a script that can increment the build, minor, or major version number throughtout the project. See
    bump --help
    for more.

And in the Xcode workspace itself you'll find:

  • SmilieExtractor
    , an iOS app that takes
    and extracts resources for Smilie Keyboard. To update smilies, first save a fresh
    from the Forums, then run
  • CopyMarkdownApp
    , a macOS Safari App Extension that adds a "Copy Awful Markdown" context menu item to the Forums. The copied markdown is ready to be pasted into a GitHub issue.

Loading fixtures into the app and/or working offline

If you've stashed some .html files from the Forums, you can load those into a debug build of the app. And if you forgot to stash some, you're in luck: we've stashed some as test fixtures. See FixtureURLProtocol for more info.


You can help! See our contribution guidelines.

Project Structure

Awful is broken down somewhat:

  • Awful
    is the iOS app.
  • AwfulCore
    is a framework that does the scraping and networking with the Forums. It's meant to be compatible with all Apple platforms, but nobody's really tried beyond iOS.
  • Smilies
    is a framework that downloads smilies and presents them as a keyboard. It's meant to be compatible with all Apple platforms, but nobody's really tried beyond iOS.


Awful's posts view is fully customizable using CSS. There's a default theme, as well as themes for specific forums such as YOSPOS and FYAD. Internally, we use LESS to generate our CSS, so if you are editing built-in themes please edit the

files. (LESS installation instructions are above.) Then commit both the modified
files and any resulting changes to
files, so others don't need LESS to build Awful.

The rest of Awful is themed in a a big plist. If you can't find a theme key you'd like to use, ask and we'll add it!

Thread Tags

Diabolik900 and The Dave have largely fashioned Awful with its own [set of thread tags][thread tags] that look great on the iPhone and the iPad. They're distributed with the app. New thread tags can also appear in Awful without us having to send an update through the App Store. This is done by hosting the icons via GitHub Pages.

To add a new thread tag you just made:

  1. Add it to the thread tags repository and push.
  2. Update the repository repository per its README.
  3. In this ( repository, update the

    App/Resources/Thread Tags
    submodule and push:
    cd path/to/awful-app/repo
    cd App/Resources/Thread\ Tags
    git pull origin master
    cd ..
    git commit -am "Updated thread tags."
    git push

Alternate App Icons

Since Awful supports both iOS 10.3 and iOS 11+, there's some hoops to jump through to support alternate app icons. Here's a mini checklist for adding a new alternate app icon:

  • Pick a name for the alternate icon. The icon picker in the Settings tab sorts icons alphabetically by this name. (e.g. the :getout: frog is called
  • Name the image files according to the scheme you see for the existing icons, but using your chosen name.
  • Add new key and values to both
    . Your added key/values will be identical between those two locations, so go ahead and copypasta.
  • Add the image files to the Xcode project, and double-check that the images get added to the target. Seems like Xcode doesn't always add everything even if you ticked the target on the sheet.

The reason for this silliness: iOS 10.3 requires alternate icons to be loose in the app bundle, while iOS 11+ supports alternate icons in an asset catalog; App Store Connect requires all submissions built using the iOS 11 SDK to have the main app icon in an asset catalog. It seems like the asset catalog compiler merges any

values it comes across with its own generated values so it works out ok for us.

URL schemes

Awful answers to a couple URL schemes:

  • awful:
    opens Awful directly to various screens. This URL scheme is documented at and at Launch Center Pro.
    • awful://forums
      opens the Forums tab.
    • awful://forums/:forumid
      opens the Forums tab to the identified forum.
    • awful://threads/:threadid
      opens the first page of the identified thread. For example,
      opens Awful's thread.
    • awful://threads/:threadid/pages/:page
      opens the given page of the identified thread. For example,
      opens the fifteenth page of Awful's thread.
    • awful://posts/:postid
      opens the identified post's page of its thread and jumps to it. For example,
      opens the OP of Awful's thread.
    • awful://bookmarks
      opens the Bookmarks tab.
    • awful://messages
      opens the Messages tab.
    • awful://messages/:messageid
      opens the identified private message. (I guess the idea is to handle a link from one message to another?)
    • awful://settings
      opens the Settings tab.
    • awful://users/:userid
      opens the identified user's profile. For example,
      opens pokeyman's profile.
    • awful://banlist
      opens the Leper's Colony.
    • awful://banlist/:userid
      opens the identified user's rap sheet. For example,
      opens pokeyman's rap sheet.
  • awfulhttp:
    handle Forums website URLs by opening the corresponding screen when possible.
    • The idea is you take your…
      URL, put
      in front, and now it opens in Awful.

iOS deployment targets

For iOS

Check out tag/branch
13 master
12 master
11 master
10 master
9 master
8 ios-8
7 ios-7
6 ios-6
5 ios-5


Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License


Awful development is led by pokeyman aka Nolan Waite.

Awful includes contributions from:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.