šŸ“® Take back control of your GitHub Notifications
Ruby HTML CSS JavaScript Shell
Latest commit b015b12 Jan 17, 2017 @WillAbides WillAbides committed on GitHub Merge pull request #253 from WillAbides/js-mark-read-fix
Fix js error in markReadSelected()
Failed to load latest commit information.
app Fix the fix Jan 17, 2017
bin Improve Docker development environment Dec 24, 2016
config Rename NotificationsController.mark_as_read to NotificationsControlleā€¦ Jan 16, 2017
db Don't forget to_i in ENV['MAX_NOTIFICATIONS_TO_SYNC'].to_i Jan 15, 2017
lib Add rake task to sync notifications for every user Dec 26, 2016
log Hello World Dec 16, 2016
public Logo and icon lossless re-compression Dec 23, 2016
test Rename NotificationsController.mark_as_read to NotificationsControlleā€¦ Jan 16, 2017
tmp Hello World Dec 16, 2016
vendor/assets remove toggle-shortcuts Dec 19, 2016
.codeclimate.yml Add codeclimate config Dec 19, 2016
.eslintignore Add codeclimate config Dec 19, 2016
.eslintrc Add codeclimate config Dec 19, 2016
.gitignore Setup test coverage with codeclimate Dec 19, 2016
.rubocop.yml fix configuration for rubucop to be compliant with new version Jan 17, 2017
.ruby-version Ruby 2.4.0 Dec 27, 2016
.travis.yml Ruby 2.4.0 Dec 27, 2016
CODE_OF_CONDUCT.md Better readme and code of conduct Dec 16, 2016
CONTRIBUTING.md Moved to Octobox org Dec 23, 2016
Dockerfile Be more specific with Docker ruby version Dec 29, 2016
Gemfile fix configuration for rubucop to be compliant with new version Jan 17, 2017
Gemfile.lock fix configuration for rubucop to be compliant with new version Jan 17, 2017
LICENSE.txt Hello World Dec 16, 2016
Procfile Added Procfile Jan 17, 2017
README.md updated shortcuts section in README.md Jan 17, 2017
Rakefile Hello World Dec 16, 2016
app.json Remove memcached dependency Jan 9, 2017
config.ru Hello World Dec 16, 2016
docker-compose.yml Remove memcached dependency Jan 9, 2017


Octobox šŸ“®

Take back control of your GitHub Notifications with Octobox.

Screenshot of Github Inbox

Build Status Code Climate Test Coverage Code Climate license Docker Automated build

Why is this a thing?

If you manage more than one active project on GitHub, you probably find GitHub Notifications pretty lacking.

Notifications are marked as read and disappear from the list as soon as you load the page or view the email of the notification. This makes it very hard to keep on top of which notifications you still need to follow up on.

Most open source maintainers and GitHub staff end up using a complex combination of filters and labels in Gmail to manage their notifications from their inbox. If, like me, you try to avoid email, then you might want something else.

Octobox adds an extra "archived" state to each notification so you can mark it as "done". If new activity happens on the thread/issue/pr, the next time you sync the app the relevant item will be unarchived and moved back into your inbox.

What state is the project in right now?

You can use a hosted version right now.

You could also host it yourself, in Heroku or otherwise.

Check out the open issues for a glimpse of the future: https://github.com/octobox/octobox/issues.


Web notifications must be enabled in your GitHub settings for Octobox to work: https://github.com/settings/notifications

Notifications settings screen

Deployment to Heroku

You can host your own instance of Octobox using Heroku. Heroku will ask you to provide a 'personal access token' which you can create on GitHub. When creating it, make sure you enable the notifications scope on it.


Running Octobox for GitHub Enterprise

In order to setup Octobox for your GitHub Enterprise instance all you need you do is add your enterprise domain to the .env file / deployed environment.



And that's it āœØ

Using Personal Access Tokens

Octobox can optionally allow you to set a personal access token to use when querying for notifications. This must be enabled at the server level. In order to enable it, add the environment variable PERSONAL_ACCESS_TOKENS_ENABLED to the .env file / deployed environment.



Once that is set, users can set a personal access token on the Settings page (found on the user drop-down menu).


The source code is hosted at GitHub. You can report issues/feature requests on GitHub Issues. For other updates, follow me on Twitter: @teabass.

Getting Started

New to Ruby? No worries! You can follow these instructions to install a local server, or you can use the included Vagrant setup.

Prefer PHP? We got you covered! There is a (work-in-progress) PHP version called LaraGit.

Installing a Local Server

First things first, you'll need to install Ruby 2.4.0. I recommend using the excellent rbenv, and ruby-build:

brew install rbenv ruby-build
rbenv install 2.4.0
rbenv global 2.4.0

Next, you'll need to make sure that you have PostgreSQL installed. This can be done easily on OSX using Homebrew or by using http://postgresapp.com. Please see these further instructions for installing Postgres via Homebrew.

brew install postgres

On Debian-based Linux distributions you can use apt-get to install Postgres:

sudo apt-get install postgresql postgresql-contrib libpq-dev

Now, let's install the gems from the Gemfile ("Gems" are synonymous with libraries in other languages):

gem install bundler && rbenv rehash
bundle install

Once all the gems are installed, we'll need to create the databases and tables. Rails makes this easy through the use of "Rake" tasks:

bundle exec rake db:create db:migrate

Now go and register a new GitHub OAuth Application, your development configuration should look something like this:

screen shot 2016-12-18 at 21 54 35

If you're deploying this to production, just replace http://localhost:3000 with your applications URL.

Once you've created your application you can then then add the following to your .env:


Finally you can boot the rails app:

rails s


You can use Docker to run Octobox in development.

First, install Docker. If you've got run macOS or Windows, Docker for Mac/Windows makes this really easy.

Then, run:

GITHUB_CLIENT_ID=yourclientid GITHUB_CLIENT_SECRET=yourclientsecret docker-compose up --build

Octobox will be running on http://localhost:3000.

Note: You can add GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to a .env file instead of supplying them directly on the command-line.

Sync notifications automatically

Now that you've set all to go you can configure the app to sync the notifications automatically, there is a rake task that will do this for every user

rake tasks:sync_notifications

You will need to configure this to run automatically


Create a Heroku Scheduler

heroku addons:create scheduler:standard

Visit the Heroku Scheduler resource and add a new job to run rake tasks:sync_notifications daily


Run crontab -e

Add the following

@daily cd octobox_path && /usr/local/bin/rake RAILS_ENV=production tasks:sync_notifications

To find the full path for your rake executable, run which rake

Keyboard shortcuts

You can use keyboard shortcuts to navigate and perform certain actions:

  • a - Select/deselect all
  • r or . - refresh list
  • j - move down the list
  • k - move up the list
  • s - star current notification
  • x - mark/unmark current notification
  • y or e - archive current/marked notification(s)
  • m - mute current/marked notification(s)
  • d - mark current/marked notification(s) as read here and on GitHub
  • o or Enter - open current notification in a new window

Press ? for the help menu.

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so we don't break it in a future version unintentionally.
  • Send a pull request. Bonus points for topic branches.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.


Copyright (c) 2017 Andrew Nesbitt. See LICENSE for details.