Octogriffin
Turn your Commits into Gold and XP.
Gamify your open-source work and professional development by connecting GitHub to Habitica.
</a>
<a href="https://github.com/drazenbebic/octogriffin/actions/workflows/release-deploy.yaml">
</a>
<a href="https://github.com/drazenbebic/octogriffin/blob/HEAD/LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3">
</a>
About
Octogriffin acts as a bridge between your GitHub workflow and your Habitica RPG character. Instead of manually checking off "Did code today" tasks, it listens to GitHub webhooks and scores Habitica habits for you whenever you push, open a pull request, review code and more.
It is built with Next.js, Prisma and PostgreSQL, and runs as a GitHub App.
Features
- Triggers you define: Pick a GitHub event and the Habitica habit it should score. Commits, pull requests, reviews, issues, releases, stars and many more events are supported.
- Your rules:
- Difficulty: Trivial, Easy, Medium or Hard.
- Direction: Earn XP and Gold, or lose Health for habits you want to break.
- Scope: Apply a trigger to all your repositories or only to selected ones.
- Fair rewards: A trigger scores at most 10 times per event (for example a push with 50 commits). Self-hosters can change this with
MAX_REWARDS_PER_EVENT. Triggers can also have a cooldown, from seconds up to 365 days, so they rest for a while after they score. A daily cap sets the most a trigger can score in a Habitica day. Skip spam, on by default, leaves out empty commits and pull requests closed straight away. Bots like Dependabot never earn rewards. - Security first:
- AES-256-GCM encryption: Your Habitica API token is encrypted at rest and never sent to the browser.
- Webhook verification: Every GitHub delivery is checked against its SHA-256 signature.
- Open source: Licensed under AGPLv3.
Tech Stack
- Framework: Next.js 16 (App Router), React 19
- Database: PostgreSQL (Neon in production, Docker locally)
- ORM: Prisma 7
- Authentication: NextAuth.js with GitHub OAuth
- Styling: Tailwind CSS 4, Ariakit, Hugeicons
- Testing: Jest, Testing Library
- Tooling: pnpm workspaces, ESLint, Prettier, Husky, commitlint
- Releases: Release Please, deployed to Vercel
Getting Started
For Users
If you simply want to connect your repositories to Habitica, you do not need to clone this repo. Follow our Installation Guide to get started in minutes.
For Developers
You need Node.js 22 or newer (CI uses 24), pnpm (the version is pinned in package.json, corepack enable picks it up) and Docker.
git clone https://github.com/drazenbebic/octogriffin.git
cd octogriffin
pnpm install
# Start PostgreSQL (and pgAdmin on http://localhost:5050)
cp .env.example .env
docker compose up -d
# Configure the web app, then fill in the values
cp apps/web/.env.local.example apps/web/.env
# Create the database tables and start the dev server
pnpm --filter @octogriffin/web prisma:migrate:dev
pnpm dev
The app runs on http://localhost:3000. To receive webhooks you also need your own GitHub App and a public tunnel to your machine. The Developer Setup Guide walks you through both, and the Architecture overview explains how the pieces fit together.
| Command | What it does |
|---|---|
pnpm dev |
Start the dev servers |
pnpm lint |
Run ESLint |
pnpm test |
Run the Jest test suites |
pnpm build |
Build every app (runs database migrations as well) |
pnpm knip |
Find unused files, exports and dependencies |
Repository Layout
apps/
web/ Next.js app: website, docs, dashboard and the GitHub webhook endpoint
api/ Standalone API (Hono), early stage
Contributing
We welcome contributions! Please read CONTRIBUTING.md before opening a pull request. It covers:
- Finding something to work on
- Branch names and commit conventions (Conventional Commits)
- Checks that must pass
- The pull request process
Please check the Roadmap and open an issue before starting large features.
Security
Found a vulnerability? Please do not open a public issue. See SECURITY.md for how to report it privately.
Sponsors
Octogriffin is an open-source passion project maintained by Drazen Bebic and contributors. While the core features will always remain free, server costs and development time are real.
Your support helps keep the servers running and fuels new features. Every monthly sponsor is listed here and on the website; the tier decides how big:
- $2/mo, Coffee fund: your name.
- $5/mo, Server fuel: your avatar and name.
- $15/mo, Feature backer: a large avatar and link at the top, plus priority on your feature requests.
Sponsor monthly or give once on GitHub Sponsors or Ko-fi. Public one-time gifts from the last 12 months are listed as Potion brewers.
The party
Potion brewers
License
Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for more information.
Author
Drazen Bebic
- Website: www.bebic.dev
- X: @drazenbebic
- LinkedIn: Drazen Bebic
