Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (claude-code-achievements) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Claude Code Achievements

Steam-style achievement system for Claude Code

Gamify your coding journey and unlock achievements as you master Claude Code features!

Installation · Usage · Achievements · How It Works

中文 · Español · 한국어 · 日本語

Features

26 Achievements across 4 categories
Real-time notifications via system alerts or terminal
Multi-language support (EN / 中文 / ES / 한국어 / 日本語)
Cross-platform (macOS / Linux / Windows)
Global installation - works across all your projects

Installation

npx claude-code-achievements

The interactive installer will:

Auto-detect your OS and notification capability
Ask for language preference (English/한국어)
Configure notification style (system/terminal/both)
Install globally to ~/.claude/plugins/local/

Note: This plugin installs globally and works across all your projects automatically.

Manual Installation

git clone https://github.com/subinium/claude-code-achievements.git
cd claude-code-achievements
node bin/install.js

Usage

Command	Description
`/achievements`	View unlocked achievements (default)
`/achievements locked`	View locked achievements with hints
`/achievements all`	View all achievements by category
`/achievements-settings`	Change language or notification settings

/achievements basics    # Getting Started
/achievements workflow  # Workflow
/achievements tools     # Power Tools
/achievements mastery   # Mastery

Achievements

Getting Started (4 achievements)

Achievement	How to Unlock
✏️ First Touch	Edit any file
📝 Creator	Create a new file
🔍 Code Detective	Use Glob or Grep to search codebase
📋 Project Curator	Create `CLAUDE.md` for project context

Workflow (8 achievements)

Achievement	How to Unlock
📋 Task Planner	Use TodoWrite for task tracking
🎯 Strategic Thinker	Use Plan mode (`Shift+Tab` twice)
🗣️ Communicator	Claude uses `AskUserQuestion` to clarify requirements or present options
🌍 Global Curator	Set up `~/.claude/CLAUDE.md`
📦 Version Controller	Commit with Claude
🚀 Ship It!	Push to remote repository
🧪 Quality Guardian	Run tests with Claude
🚦 CI/CD Pioneer	Create GitHub Actions workflow

Power Tools (9 achievements)

Achievement	How to Unlock
🎨 Visual Inspector	Analyze image or screenshot
📡 Doc Hunter	Fetch and analyze a web page
🤖 Delegation Master	Use `Task` tool for sub-agents
🔌 MCP Pioneer	Use any MCP tool
🌐 Web Explorer	Use `WebSearch` tool
⚡ Skill Master	Use slash command skills
⚙️ Customizer	Modify Claude Code settings
📜 Skill Creator	Create custom skill in `.claude/skills/`
⌨️ Command Crafter	Create custom slash command

Mastery (5 achievements)

Achievement	How to Unlock
🪝 Automation Architect	Set up Claude Code hooks
🔗 MCP Connector	Configure `.mcp.json` for integrations
🤖 Agent Architect	Create custom agent in `.claude/agents/`
🛡️ Security Guard	Configure security permissions
🔄 Loop Master	Start autonomous coding loop

Architecture

This plugin uses Claude Code's hook system to track your actions in real-time.

┌─────────────────────────────────────────────────────────────┐
│                     CLAUDE CODE SESSION                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   You: "Edit the config file"                               │
│                     │                                        │
│                     ▼                                        │
│   ┌─────────────────────────────────────┐                   │
│   │         Claude uses Edit tool        │                   │
│   └─────────────────────────────────────┘                   │
│                     │                                        │
│                     ▼                                        │
│   ┌─────────────────────────────────────┐                   │
│   │    PostToolUse Hook Triggered        │◄── hooks.json    │
│   │    → track-achievement.sh            │                   │
│   └─────────────────────────────────────┘                   │
│                     │                                        │
│         ┌──────────┴──────────┐                             │
│         ▼                     ▼                             │
│   ┌───────────┐        ┌───────────┐                        │
│   │  Match!   │        │ No Match  │                        │
│   │           │        │           │                        │
│   │ Unlock    │        │ Continue  │                        │
│   │ Notify    │        └───────────┘                        │
│   │ Save      │                                              │
│   └───────────┘                                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Plugin Structure

~/.claude/plugins/local/claude-code-achievements/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── hooks/
│   ├── hooks.json           # Hook definitions (PostToolUse, Stop)
│   ├── track-achievement.sh # Main tracking logic
│   └── track-stop.sh        # Session end handler
├── commands/
│   ├── achievements.md      # /achievements command
│   └── achievements-settings.md
├── scripts/
│   ├── show-achievements.sh # Display UI
│   └── show-notification.sh # Notification handler
└── data/
    ├── achievements.json    # Achievement definitions
    └── i18n/
        ├── en.json          # English
        ├── zh.json          # 中文
        ├── es.json          # Español
        ├── ko.json          # 한국어
        └── ja.json          # 日本語

How Hooks Work

The plugin registers two hooks in Claude Code:

Hook	Trigger	Purpose
`PostToolUse`	After any tool execution	Check if action unlocks achievement
`Stop`	Session ends	Save session stats

How Commands Work

Slash commands (/achievements) are implemented as markdown files in ~/.claude/commands/. Claude Code reads these and executes the embedded instructions.

Notifications

System notifications are auto-detected during installation:

OS	Method	Sound
macOS	`osascript`	Glass
Linux	`notify-send`	System default
Windows	PowerShell	System default
Fallback	Terminal	None

Install notify-send on Linux

# Ubuntu/Debian
sudo apt install libnotify-bin

# Fedora
sudo dnf install libnotify

# Arch
sudo pacman -S libnotify

Configuration

Settings are stored in ~/.claude/achievements/state.json:

{
  "settings": {
    "language": "en",
    "notifications": true,
    "notification_style": "system"
  },
  "achievements": {},
  "counters": {}
}

Setting	Values	Description
`language`	`"en"`, `"zh"`, `"es"`, `"ko"`, `"ja"`	UI language
`notifications`	`true`, `false`	Enable/disable alerts
`notification_style`	`"system"`, `"terminal"`, `"both"`	Alert method

Troubleshooting

Achievements not unlocking?

# Check plugin is installed
ls ~/.claude/plugins/local/claude-code-achievements/

# Check state file exists
cat ~/.claude/achievements/state.json

# Verify hooks are loaded (restart Claude Code after install)

Reset all progress

rm ~/.claude/achievements/state.json

Reinstall plugin

npx claude-code-achievements@latest

Contributing

Contributions welcome! Ideas:

New achievements
New language translations
UI improvements
Bug fixes

License

MIT © subinium

Happy coding!