A cute Live2D mascot for GitHub notifications on your desktop

---

Free for personal and non-commercial use. Commercial use requires a Live2D license. See License for details.

GitChan is a fork of Gitify, enhanced with Live2D character support to make your GitHub notification experience more delightful.

---

Download

Platform	Download
macOS	GitChan-0.0.3-universal.dmg
Windows	GitChan-Setup-0.0.3.exe
Linux	GitChan-0.0.3.AppImage

Or visit the Releases page for all versions.

---

Table of Contents

• Download
• Features
• Installation Notes
• Development Setup
• How to Run
• How to Use
• Modifications from Gitify
• Technologies & Libraries
• License
• Credits & Attributions
• Contributing

---

Features

• Live2D Mascot Characters: Choose from 7 different Live2D characters
  • Hiyori - Cheerful schoolgirl
  • Haru - Calm female character
  • Mao - Mysterious wizard
  • Natori - Friendly male character
  • Mark - Humorous male character
  • Rice - Cool wizard
  • Wanko - Loyal puppy
• Real-time GitHub Notifications: Receive desktop notifications for reviews, mentions, approvals, and more
• Customizable Mascot Settings:
  • Character selection
  • Mascot size adjustment (50-150%)
  • Window size adjustment (50-200%)
  • Badge position adjustment (20-200px)
• Custom Notification Sounds: Different sounds for different notification types
• Cross-platform Support: Works on macOS, Windows, and Linux

---

Installation Notes

macOS

If you see a warning that the app "can't be opened" or "isn't commonly downloaded":

1. Go to System Settings → Privacy & Security
2. Click Open Anyway

Or run in Terminal:

xattr -cr /Applications/GitChan.app

Windows

Browser download warning (Edge/Chrome):

If Edge shows "isn't commonly downloaded" warning:

1. Click ⋯ (three dots) next to the download
2. Click Keep → Keep anyway

SmartScreen warning (after running installer):

If you see "Windows protected your PC":

1. Click More info
2. Click Run anyway

---

Development Setup

Prerequisites

• Node.js >= 24
• pnpm >= 10.27.0

Clone and Install

git clone https://github.com/gitchan-app/gitchan.git
cd gitchan
pnpm install

---

How to Run

Development Mode

# Build and watch for changes
pnpm watch

# In another terminal, start the application
pnpm start

Production Build

# Build all components
pnpm build

# Package for your platform
pnpm package:macos   # For macOS
pnpm package:win     # For Windows
pnpm package:linux   # For Linux

Testing

pnpm test

Linting

pnpm lint        # Fix linting issues
pnpm lint:check  # Check for linting issues

Version Management

GitChan uses npm version for version management. This automatically updates package.json and creates a git tag.

pnpm release:patch   # Bug fixes (0.1.0 → 0.1.1)
pnpm release:minor   # New features (0.1.0 → 0.2.0)
pnpm release:major   # Breaking changes (0.1.0 → 1.0.0)

Each command will:

1. Update the version in package.json
2. Create a git commit with message Release vX.X.X
3. Create a git tag vX.X.X

---

How to Use

1. Launch GitChan: After installation, launch the application
2. Login with GitHub: Authenticate with your GitHub account via OAuth
3. Configure Settings:
   • Go to Settings to customize your experience
   • Select your favorite mascot character
   • Adjust mascot size and window size
   • Configure notification preferences
4. Receive Notifications: The mascot will notify you of GitHub events with animations and sounds

Mascot Controls

• Click on mascot: Triggers a tap animation
• Mascot Size slider: Adjust the character size (50-150%)
• Window Size slider: Adjust the mascot window size (50-200%)
• Badge Position slider: Adjust notification badge vertical position (20-200px)

---

Modifications from Gitify

GitChan extends Gitify with the following features and modifications:

New Features

1. Live2D Mascot System

   • Added Live2D character display using pixi-live2d-display
   • Transparent overlay window for mascot display
   • Support for 7 different character models
   • Character animations triggered by notifications

2. Mascot Customization

   • Character selection in settings
   • Mascot size adjustment (scale 50-150%)
   • Window size adjustment (scale 50-200%)
   • Notification badge position adjustment (20-200px)

3. Custom Notification Sounds

   • Different sounds for different notification types:
     • review-requested.wav - Review requests
     • mention.wav - Mentions and team mentions
     • approved.wav - Approval requests
     • default.wav - Other notifications
   • Volume control with adjustment buttons

4. Upgraded SDK Support

   • Live2D Cubism 5 SDK for MOC3 v5 model support

Modified Files

• src/main/mascot.ts - Mascot window management
• src/main/mascot.html - Live2D rendering and canvas management
• src/main/mascot-preload.ts - IPC bridge for mascot window
• src/shared/constants.ts - Mascot model definitions
• src/shared/events.ts - IPC event definitions
• src/renderer/types.ts - Settings type definitions
• src/renderer/context/defaults.ts - Default settings values
• src/renderer/components/settings/SystemSettings.tsx - Settings UI
• src/preload/index.ts - Preload script with mascot API

Added Assets

• assets/live2d/ - Live2D model files (Hiyori, Haru, Mao, Natori, Mark, Rice, Wanko)
• assets/lib/ - Live2D SDK and dependencies
  • live2dcubismcore.min.js - Cubism 5 Core SDK
  • pixi.v6.min.js - PixiJS v6
  • pixi-live2d-display-cubism4.min.js - Live2D display plugin
• assets/sounds/ - Custom notification sound files

---

Technologies & Libraries

Core Framework

Library	Version	Description
Electron	39.2.7	Cross-platform desktop app framework
React	19.2.3	UI component library
TypeScript	5.9.3	Type-safe JavaScript

Live2D Integration

Library	Version	Description
Live2D Cubism SDK	5.x	Core Live2D rendering engine
PixiJS	6.x	2D WebGL renderer
pixi-live2d-display	-	Live2D model display for PixiJS

UI Components

Library	Version	Description
Primer React	38.7.0	GitHub's design system components
Primer CSS	22.1.0	GitHub's design system styles
Tailwind CSS	4.1.18	Utility-first CSS framework

Build Tools

Library	Version	Description
Webpack	5.104.1	Module bundler
Babel	7.28.5	JavaScript compiler
electron-builder	26.4.0	Electron app packager

Testing

Library	Version	Description
Jest	30.2.0	Testing framework
Testing Library	16.3.1	React testing utilities

---

License

This project uses a dual-license structure:

Application Code - MIT License

The GitChan application code (excluding Live2D components) is licensed under the MIT License.

MIT License

Copyright (c) GitChan Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Live2D Components - Live2D Proprietary License

The Live2D Cubism SDK and sample models are subject to Live2D's proprietary licenses:

• Live2D Cubism SDK: Subject to the Live2D Proprietary Software License Agreement
• Sample Models: Subject to the Free Material License Agreement

Important Notes for Commercial Use

• Free for Personal/Non-commercial Use: You can use GitChan freely for personal, educational, or non-commercial purposes
• Commercial Use Requires License: If you plan to use GitChan commercially (with revenue exceeding the threshold specified by Live2D), you must obtain a separate license from Live2D Inc.
• Live2D SDK License: Commercial applications must comply with Live2D's licensing terms

For more information about Live2D licensing, visit: https://www.live2d.com/en/sdk/license/

Notification Sounds - Custom/Royalty-Free

All notification sound files in assets/sounds/ are custom-created and royalty-free. You may use, modify, and distribute these sounds freely.

---

Credits & Attributions

Gitify

GitChan is based on Gitify, an open-source GitHub notification app.

• Repository: https://github.com/gitify-app/gitify
• Website: https://gitify.io
• License: MIT License
• Copyright: Gitify Contributors

We express our sincere gratitude to the Gitify team for creating such an excellent foundation.

Live2D Inc.

Live2D technology and sample models are provided by Live2D Inc.

• Cubism SDK: https://www.live2d.com/en/sdk/
• Sample Models Used:
  • Hiyori (Free Material)
  • Haru (Free Material)
  • Mao (Free Material)
  • Natori (Free Material)
  • Mark (Free Material)
  • Rice (Free Material)
  • Wanko (Free Material)

pixi-live2d-display

Live2D model rendering is powered by pixi-live2d-display.

• Repository: https://github.com/guansss/pixi-live2d-display
• Author: guansss
• License: MIT License

PixiJS

2D rendering is powered by PixiJS.

• Repository: https://github.com/pixijs/pixijs
• License: MIT License

GitHub Primer

UI components are built with GitHub Primer.

• Repository: https://github.com/primer
• License: MIT License

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Support

If you encounter any issues or have questions:

• Issues: https://github.com/gitchan-app/gitchan/issues
• Discussions: https://github.com/gitchan-app/gitchan/discussions

---

Made with ❤️ by the GitChan Team