gitgud

GitGud

Keep your coding skills sharp while using AI. A Claude Code plugin that periodically assigns manual coding challenges with gamification features.

Why GitGud?

AI assistants like Claude Code make us incredibly productive, but there's a risk: if we never write code ourselves, our skills atrophy. GitGud ensures you practice regularly while still benefiting from AI assistance.

Features

• Periodic Challenges: Every N requests, you'll get a coding task related to your current work
• Smart Categorization: Tasks match your context (API, auth, testing, database, etc.)
• Gamification:
  • Streaks: Track consecutive days of completed tasks
  • Achievements: Unlock badges as you progress
  • Skip System: Skip tasks when you're in a hurry (limited per day)
• Persistent Progress: Your data is stored in ~/.gitgud/ and persists across plugin updates
• Fully Configurable: Adjust frequency, difficulty, and daily skips

Installation

Claude Code

From Marketplace (recommended)

/plugin marketplace add MissingPackage/gitgud
/plugin install gitgud

From local folder (for development)

claude --debug --plugin-dir /path/to/gitgud

Cursor IDE

GitGud now supports Cursor IDE! The same repository works for both Claude Code and Cursor, with shared data between them.

Requirements

• Node.js 14+ installed
• Cursor IDE 1.7+ (with hook support)
• Git (for cloning the repository)

macOS/Linux

# Clone and run installer
git clone https://github.com/MissingPackage/gitgud.git ~/.gitgud-cursor
cd ~/.gitgud-cursor
./install-cursor.sh

Notes for multi-shell setups (bash + zsh, etc.)

The installer adds command aliases (e.g. gg-stats) to your primary/login shell config file:

• zsh → ~/.zshrc
• bash → ~/.bashrc
• fish → ~/.config/fish/config.fish
• other → ~/.profile

If you want to override the target file explicitly:

GITGUD_SHELL_RC="$HOME/.zshrc" ./install-cursor.sh

Windows

# Run in PowerShell
git clone https://github.com/MissingPackage/gitgud.git $env:USERPROFILE\.gitgud-cursor
cd $env:USERPROFILE\.gitgud-cursor
.\install-cursor.ps1

How Cursor Support Works

Unlike Claude Code which can inject context directly, Cursor's beforeSubmitPrompt hook only supports { continue: boolean }. Therefore, GitGud for Cursor uses a different approach:

1. Hook: Processes prompts and writes task state to files
2. Cursor Rule: Reads task state and instructs the AI to enforce training mode
3. Shared Data: Both Claude Code and Cursor use ~/.gitgud/ for data storage

This means your streak, achievements, and settings are synchronized between both IDEs!

⚠️ IMPORTANT: Cursor Rules Configuration

Cursor does NOT support global rules that apply automatically across all projects. You must manually configure GitGud rules for each project where you want to use it.

📖 Official documentation: Cursor Rules

Step 1: Copy the Rule File

For each project where you want GitGud active:

# From your project root:
mkdir -p .cursor/rules
cp ~/.gitgud-cursor/cursor/rules/gitgud.mdc .cursor/rules/

Or append to an existing .cursorrules file:

cat ~/.gitgud-cursor/cursor/rules/gitgud.cursorrules >> .cursorrules

Step 2: Enable the Rule in Cursor Settings

⚠️ Copying the file is not enough! You must also enable the rule in Cursor:

The GitGud rule should always be active, but sometimes you may need to enable it once, the first time you want to activate GitGud in a project.

1. Open the project in Cursor
2. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
3. Run "Reload Window" to detect new rules
4. Go to Cursor Settings → Rules (or open the Context panel → Rules)
5. Verify that the GitGud rule appears and is enabled (toggle ON)

Without enabling the rule, Cursor's AI will not enforce training mode even if tasks are assigned!

Verifying the Setup

To check if GitGud is working in Cursor:

1. Open a project with the rule configured and enabled
2. Run node ~/.gitgud-cursor/cursor/validate-cursor.js to verify setup
3. Check if pending tasks appear when you interact with Cursor AI

Uninstalling from Cursor

# macOS/Linux
~/.gitgud-cursor/uninstall-cursor.sh

# Windows (PowerShell)
~\.gitgud-cursor\uninstall-cursor.ps1

The uninstaller will ask if you want to keep your data for future reinstallation.

Commands

Command	Description
/gg-complete	Mark current task as completed
/gg-stats	View statistics, achievements, and streak
/gg-reset [counter|stats|all]	Reset data
/gg-config	View current configuration
/gg-config <setting> <value>	Change a setting

How It Works