claude-code-achievements 1.0.0

package/bin/install.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const PLUGIN_NAME = 'claude-code-achievements';
+const TARGET_DIR = path.join(os.homedir(), '.claude', 'plugins', 'local', PLUGIN_NAME);
+
+const ITEMS_TO_COPY = ['.claude-plugin', 'commands', 'hooks', 'scripts', 'data', 'bin'];
+
+// ANSI colors
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+    if (src.endsWith('.sh') || src.endsWith('.js')) {
+      fs.chmodSync(dest, 0o755);
+    }
+  }
+}
+
+function detectOS() {
+  const platform = os.platform();
+  if (platform === 'darwin') return 'macOS';
+  if (platform === 'win32') return 'Windows';
+  return 'Linux';
+}
+
+function detectLanguage() {
+  const locale = process.env.LANG || process.env.LC_ALL || process.env.LANGUAGE || '';
+  if (locale.toLowerCase().includes('ko')) return 'ko';
+  return 'en';
+}
+
+function checkSystemNotification(osName) {
+  try {
+    if (osName === 'macOS') {
+      // macOS always has osascript
+      return { available: true, method: 'osascript' };
+    } else if (osName === 'Linux') {
+      // Check for notify-send
+      execSync('which notify-send', { stdio: 'ignore' });
+      return { available: true, method: 'notify-send' };
+    } else if (osName === 'Windows') {
+      // Check for PowerShell
+      execSync('where powershell.exe', { stdio: 'ignore' });
+      return { available: true, method: 'PowerShell' };
+    }
+  } catch (e) {
+    return { available: false, method: null };
+  }
+  return { available: false, method: null };
+}
+
+async function prompt(question, options) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    const optStr = options.map((o, i) => `${i + 1}) ${o.label}`).join('  ');
+    rl.question(`${question} [${optStr}]: `, (answer) => {
+      rl.close();
+      const num = parseInt(answer) || 1;
+      const idx = Math.max(0, Math.min(options.length - 1, num - 1));
+      resolve(options[idx].value);
+    });
+  });
+}
+
+async function install() {
+  console.log('');
+  console.log(`${CYAN}${BOLD}╔═══════════════════════════════════════════════════════════╗${RESET}`);
+  console.log(`${CYAN}${BOLD}║       🎮 Claude Code Achievements Installer 🎮            ║${RESET}`);
+  console.log(`${CYAN}${BOLD}╚═══════════════════════════════════════════════════════════╝${RESET}`);
+  console.log('');
+
+  const detectedOS = detectOS();
+  const detectedLang = detectLanguage();
+  const notifyCheck = checkSystemNotification(detectedOS);
+
+  console.log(`${DIM}Detected OS: ${detectedOS}${RESET}`);
+  if (notifyCheck.available) {
+    console.log(`${DIM}System notifications: ${GREEN}✓${RESET}${DIM} ${notifyCheck.method}${RESET}`);
+  } else {
+    console.log(`${DIM}System notifications: ${YELLOW}✗${RESET}${DIM} not available (will use terminal)${RESET}`);
+  }
+  console.log('');
+
+  // Check if interactive
+  const isInteractive = process.stdin.isTTY;
+
+  let language = detectedLang;
+  let notificationStyle = notifyCheck.available ? 'system' : 'terminal';
+
+  if (isInteractive) {
+    // Language selection
+    console.log(`${BOLD}Select language / 언어 선택:${RESET}`);
+    language = await prompt('', [
+      { label: 'English', value: 'en' },
+      { label: '한국어', value: 'ko' }
+    ]);
+    console.log(`  ${GREEN}✓${RESET} ${language === 'ko' ? '한국어' : 'English'}`);
+    console.log('');
+
+    // Notification style (only ask if system notifications available)
+    if (notifyCheck.available) {
+      console.log(`${BOLD}Notification style:${RESET}`);
+      notificationStyle = await prompt('', [
+        { label: `System (${notifyCheck.method})`, value: 'system' },
+        { label: 'Terminal', value: 'terminal' },
+        { label: 'Both', value: 'both' }
+      ]);
+      console.log(`  ${GREEN}✓${RESET} ${notificationStyle}`);
+    } else {
+      console.log(`${BOLD}Notification:${RESET} Terminal (system not available)`);
+      notificationStyle = 'terminal';
+    }
+    console.log('');
+  }
+
+  // Copy files
+  const packageRoot = path.resolve(__dirname, '..');
+
+  if (fs.existsSync(TARGET_DIR)) {
+    console.log(`${DIM}Removing existing installation...${RESET}`);
+    fs.rmSync(TARGET_DIR, { recursive: true, force: true });
+  }
+
+  console.log(`${DIM}Installing to ${TARGET_DIR}${RESET}`);
+  fs.mkdirSync(TARGET_DIR, { recursive: true });
+
+  for (const item of ITEMS_TO_COPY) {
+    const srcPath = path.join(packageRoot, item);
+    const destPath = path.join(TARGET_DIR, item);
+    if (fs.existsSync(srcPath)) {
+      copyRecursive(srcPath, destPath);
+    }
+  }
+
+  // Initialize state
+  const stateDir = path.join(os.homedir(), '.claude', 'achievements');
+  const stateFile = path.join(stateDir, 'state.json');
+
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+
+  // Always update settings, preserve achievements if exists
+  let existingState = null;
+  if (fs.existsSync(stateFile)) {
+    try {
+      existingState = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    } catch (e) {}
+  }
+
+  const newState = {
+    settings: {
+      language,
+      notifications: true,
+      notification_style: notificationStyle
+    },
+    achievements: existingState?.achievements || {},
+    counters: existingState?.counters || {},
+    session: {}
+  };
+
+  fs.writeFileSync(stateFile, JSON.stringify(newState, null, 2));
+
+  // Copy commands to ~/.claude/commands/
+  const commandsDir = path.join(os.homedir(), '.claude', 'commands');
+  if (!fs.existsSync(commandsDir)) {
+    fs.mkdirSync(commandsDir, { recursive: true });
+  }
+  const srcCommands = path.join(packageRoot, 'commands');
+  if (fs.existsSync(srcCommands)) {
+    for (const file of fs.readdirSync(srcCommands)) {
+      fs.copyFileSync(
+        path.join(srcCommands, file),
+        path.join(commandsDir, file)
+      );
+    }
+  }
+
+  console.log('');
+  console.log(`${GREEN}${BOLD}✅ Installation complete!${RESET}`);
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log(`${BOLD}Ready to use:${RESET}`);
+  console.log('');
+  console.log(`  ${CYAN}/achievements${RESET}       View your achievements`);
+  console.log(`  ${CYAN}/achievements hint${RESET}  Get tips for unlocking`);
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('🎮 Happy coding!');
+  console.log('');
+}
+
+install().catch(err => {
+  console.error('❌ Installation failed:', err.message);
+  process.exit(1);
+});

package/commands/achievements-settings.md

@@ -0,0 +1,63 @@
+---
+description: "Configure your achievements settings"
+---
+
+# /achievements-settings Command
+
+## Instructions
+
+Use AskUserQuestion to let the user configure settings interactively.
+
+### Step 1: Read Current Settings
+
+```bash
+cat ~/.claude/achievements/state.json | jq '.settings'
+```
+
+### Step 2: Show Menu
+
+Use AskUserQuestion with ALL settings in one question (multiSelect: false):
+
+```
+Question: "Select a setting to change"
+Header: "Settings"
+Options:
+- "Language: {current}" (description: "Change display language")
+- "Notifications: {on/off}" (description: "Toggle unlock notifications")
+- "Style: {current}" (description: "terminal / system / both")
+- "Reset Progress" (description: "Clear all achievements")
+```
+
+### Step 3: Based on Selection
+
+**If "Language"**: Ask with options "English", "한국어", then apply:
+```bash
+jq '.settings.language = "en"' ~/.claude/achievements/state.json > tmp.json && mv tmp.json ~/.claude/achievements/state.json
+```
+
+**If "Notifications"**: Ask "On" or "Off", then apply:
+```bash
+jq '.settings.notifications = true' ~/.claude/achievements/state.json > tmp.json && mv tmp.json ~/.claude/achievements/state.json
+```
+
+**If "Style"**: Ask "terminal", "system", "both", then apply:
+```bash
+jq '.settings.notification_style = "system"' ~/.claude/achievements/state.json > tmp.json && mv tmp.json ~/.claude/achievements/state.json
+```
+
+**If "Reset"**: Confirm first, then:
+```bash
+jq '.achievements = {} | .counters = {"ralph_iterations": 0, "files_read": 0, "edits_made": 0} | .session = {"files_read_set": []}' ~/.claude/achievements/state.json > tmp.json && mv tmp.json ~/.claude/achievements/state.json
+```
+
+### Step 4: Confirm
+
+Tell user what changed: "✓ Language changed to English"
+
+## Direct Arguments
+
+Skip menu if arguments provided:
+- `/achievements-settings language en`
+- `/achievements-settings notifications off`
+- `/achievements-settings notification-style system`
+- `/achievements-settings reset`

package/commands/achievements.md

@@ -0,0 +1,93 @@
+---
+description: "Display your Claude Code achievements progress"
+---
+
+# /achievements Command
+
+Display Claude Code achievements progress. Output directly in your response (not bash).
+
+## Arguments
+
+- `(none)` or `all`: Show all achievements
+- `hint` or `tips`: Show tips for unlocking
+- `<category>`: Show specific category (basics, workflow, tools, mastery)
+
+## Instructions
+
+### Step 1: Read Data
+
+Use the Read tool to read these files:
+- `~/.claude/plugins/local/claude-code-achievements/data/achievements.json`
+- `~/.claude/achievements/state.json`
+
+### Step 2: Format Output
+
+**IMPORTANT: Output directly in your response text, NOT via bash. Bash output gets collapsed and has bad UX.**
+
+Format like this (compact, readable):
+
+```
+🎮 **Claude Code Achievements** — 4/18 unlocked (22%)
+████░░░░░░░░░░░░░░░░
+
+**Getting Started**
+✅ First Touch ⬜ · ✅ Creator ⬜
+⬛ Hello, Claude! ⬜ — Start your first conversation
+⬛ Project Curator 🟩 — Create CLAUDE.md for project context
+
+**Workflow**
+⬛ Strategic Thinker 🟩 — Use Plan mode for complex tasks
+⬛ Version Controller 🟩 — Commit changes with Claude
+⬛ Ship It! 🟩 — Push changes to remote
+⬛ Quality Guardian 🟩 — Run tests with Claude
+
+**Power Tools**
+✅ Delegation Master 🟦
+⬛ MCP Pioneer 🟦 — Use an MCP tool
+⬛ Web Explorer 🟦 — Search the web
+⬛ Skill Master 🟦 — Use a slash command
+⬛ Data Scientist 🟦 — Edit a Jupyter notebook
+⬛ Customizer 🟦 — Modify Claude Code settings
+
+**Mastery**
+⬛ Automation Architect 🟪 — Set up hooks
+⬛ Loop Master 🟪 — Start autonomous coding loop
+⬛ Parallel Universe 🟪 — Run multiple Claude sessions
+⬛ Full Stack Vibecoder 🟨 — Work on frontend, backend, DB in one session
+
+_Rarity: ⬜ Common · 🟩 Uncommon · 🟦 Rare · 🟪 Epic · 🟨 Legendary_
+```
+
+Rules:
+- ✅ = unlocked (show name + rarity only)
+- ⬛ = locked (show name + rarity + description)
+- Group unlocked items on same line when possible
+- Keep it compact!
+
+### Step 3: Suggest Next
+
+After showing achievements, suggest ONE easy achievement to unlock next.
+
+## Hint Mode (/achievements hint)
+
+Show tips for 2-3 locked achievements. Read the `tip` field from achievements.json:
+
+```
+💡 **Tips to unlock more:**
+
+📋 **Project Curator** (🟩 Uncommon)
+Create a CLAUDE.md file for your project
+→ Include tech stack, coding style, and common commands
+
+🎯 **Strategic Thinker** (🟩 Uncommon)
+Use Plan mode for your next complex task
+→ Press Shift+Tab twice to enter Plan mode
+```
+
+## Rarity Reference
+
+- ⬜ Common — basic actions
+- 🟩 Uncommon — workflow essentials
+- 🟦 Rare — power user features
+- 🟪 Epic — advanced automation
+- 🟨 Legendary — master vibecoder

package/data/achievements.json

@@ -0,0 +1,168 @@
+{
+  "rarities": {
+    "common": { "name": "Common", "color": "⬜", "order": 1 },
+    "uncommon": { "name": "Uncommon", "color": "🟩", "order": 2 },
+    "rare": { "name": "Rare", "color": "🟦", "order": 3 },
+    "epic": { "name": "Epic", "color": "🟪", "order": 4 },
+    "legendary": { "name": "Legendary", "color": "🟨", "order": 5 }
+  },
+  "categories": {
+    "basics": {
+      "name": "Getting Started",
+      "description": "First steps with Claude Code",
+      "order": 1
+    },
+    "workflow": {
+      "name": "Workflow",
+      "description": "Mastering development workflow",
+      "order": 2
+    },
+    "tools": {
+      "name": "Power Tools",
+      "description": "Using advanced Claude Code features",
+      "order": 3
+    },
+    "mastery": {
+      "name": "Mastery",
+      "description": "Expert-level usage",
+      "order": 4
+    }
+  },
+  "achievements": {
+    "first_edit": {
+      "id": "first_edit",
+      "name": "First Touch",
+      "description": "Edit a file with Claude's help",
+      "tip": "Be specific: instead of 'fix the bug', say 'fix the TypeError in login.js line 42'",
+      "category": "basics",
+      "rarity": "common",
+      "icon": "✏️"
+    },
+    "first_write": {
+      "id": "first_write",
+      "name": "Creator",
+      "description": "Create a new file",
+      "tip": "Claude can create entire files from description. Try: 'Create a React component for a login form'",
+      "category": "basics",
+      "rarity": "common",
+      "icon": "📝"
+    },
+    "claude_md_creator": {
+      "id": "claude_md_creator",
+      "name": "Project Curator",
+      "description": "Create CLAUDE.md for project context",
+      "tip": "CLAUDE.md helps Claude understand your project. Include: tech stack, coding style, important files, and common commands.",
+      "category": "basics",
+      "rarity": "uncommon",
+      "icon": "📋"
+    },
+    "plan_mode_user": {
+      "id": "plan_mode_user",
+      "name": "Strategic Thinker",
+      "description": "Use Plan mode for complex tasks",
+      "tip": "Press Shift+Tab twice to enter Plan mode. Great for architecture decisions and multi-step tasks.",
+      "category": "workflow",
+      "rarity": "uncommon",
+      "icon": "🎯"
+    },
+    "git_commit": {
+      "id": "git_commit",
+      "name": "Version Controller",
+      "description": "Commit changes with Claude",
+      "tip": "Let Claude write commit messages! It reads your changes and writes meaningful conventional commits.",
+      "category": "workflow",
+      "rarity": "uncommon",
+      "icon": "📦"
+    },
+    "git_push": {
+      "id": "git_push",
+      "name": "Ship It!",
+      "description": "Push changes to remote",
+      "tip": "Always review changes before pushing. Ask Claude to summarize what will be pushed.",
+      "category": "workflow",
+      "rarity": "uncommon",
+      "icon": "🚀"
+    },
+    "run_tests": {
+      "id": "run_tests",
+      "name": "Quality Guardian",
+      "description": "Run tests with Claude",
+      "tip": "Ask Claude: 'Run the tests and fix any failures'. This is the vibecoding verification loop!",
+      "category": "workflow",
+      "rarity": "uncommon",
+      "icon": "🧪"
+    },
+    "multi_agent": {
+      "id": "multi_agent",
+      "name": "Delegation Master",
+      "description": "Use Task tool to spawn sub-agents",
+      "tip": "Task tool creates specialized agents for complex work. Great for parallel exploration.",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "🤖"
+    },
+    "first_mcp": {
+      "id": "first_mcp",
+      "name": "MCP Pioneer",
+      "description": "Use an MCP tool",
+      "tip": "MCP extends Claude's abilities. Connect to databases, APIs, or custom tools.",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "🔌"
+    },
+    "web_searcher": {
+      "id": "web_searcher",
+      "name": "Web Explorer",
+      "description": "Search the web for information",
+      "tip": "Claude can search for latest docs, solutions, and APIs.",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "🌐"
+    },
+    "skill_invoker": {
+      "id": "skill_invoker",
+      "name": "Skill Master",
+      "description": "Use a slash command skill",
+      "tip": "Skills are shortcuts. Try /commit, /pr, /init. Create custom skills in ~/.claude/commands/",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "⚡"
+    },
+    "notebook_editor": {
+      "id": "notebook_editor",
+      "name": "Data Scientist",
+      "description": "Edit a Jupyter notebook",
+      "tip": "Claude understands notebooks! Ask for data analysis, visualizations, or ML experiments.",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "📓"
+    },
+    "config_modifier": {
+      "id": "config_modifier",
+      "name": "Customizer",
+      "description": "Modify Claude Code settings",
+      "tip": "Customize Claude with /config or edit ~/.claude/settings.json.",
+      "category": "tools",
+      "rarity": "rare",
+      "icon": "⚙️"
+    },
+    "hooks_user": {
+      "id": "hooks_user",
+      "name": "Automation Architect",
+      "description": "Set up Claude Code hooks",
+      "tip": "Hooks run scripts on events. Use them for linting, testing, or custom workflows.",
+      "category": "mastery",
+      "rarity": "epic",
+      "icon": "🪝"
+    },
+    "ralph_starter": {
+      "id": "ralph_starter",
+      "name": "Loop Master",
+      "description": "Start an autonomous coding loop",
+      "tip": "Ralph Loop lets Claude work autonomously until a goal is met. Great for complex refactoring!",
+      "category": "mastery",
+      "rarity": "legendary",
+      "icon": "🔄"
+    }
+  }
+}

package/data/i18n/en.json

@@ -0,0 +1,94 @@
+{
+  "ui": {
+    "title": "CLAUDE CODE ACHIEVEMENTS",
+    "unlocked": "Achievement Unlocked!",
+    "locked": "Locked",
+    "progress": "Progress",
+    "rarity": "Rarity",
+    "tip": "Tip",
+    "hint": "Hint"
+  },
+  "categories": {
+    "basics": { "name": "Getting Started", "description": "First steps with Claude Code" },
+    "workflow": { "name": "Workflow", "description": "Development workflow mastery" },
+    "tools": { "name": "Power Tools", "description": "Advanced Claude Code features" },
+    "mastery": { "name": "Mastery", "description": "Expert-level usage" }
+  },
+  "achievements": {
+    "first_edit": {
+      "name": "First Touch",
+      "description": "Edit a file with Claude's help",
+      "tip": "Be specific: instead of 'fix the bug', say 'fix the TypeError in login.js line 42'"
+    },
+    "first_write": {
+      "name": "Creator",
+      "description": "Create a new file",
+      "tip": "Claude can create entire files from description. Try: 'Create a React component for a login form'"
+    },
+    "claude_md_creator": {
+      "name": "Project Curator",
+      "description": "Create CLAUDE.md for project context",
+      "tip": "CLAUDE.md helps Claude understand your project. Include: tech stack, coding style, important files, and common commands."
+    },
+    "plan_mode_user": {
+      "name": "Strategic Thinker",
+      "description": "Use Plan mode for complex tasks",
+      "tip": "Press Shift+Tab twice to enter Plan mode. Great for architecture decisions and multi-step tasks."
+    },
+    "git_commit": {
+      "name": "Version Controller",
+      "description": "Commit changes with Claude",
+      "tip": "Let Claude write commit messages! It reads your changes and writes meaningful conventional commits."
+    },
+    "git_push": {
+      "name": "Ship It!",
+      "description": "Push changes to remote",
+      "tip": "Always review changes before pushing. Ask Claude to summarize what will be pushed."
+    },
+    "run_tests": {
+      "name": "Quality Guardian",
+      "description": "Run tests with Claude",
+      "tip": "Ask Claude: 'Run the tests and fix any failures'. This is the vibecoding verification loop!"
+    },
+    "multi_agent": {
+      "name": "Delegation Master",
+      "description": "Use Task tool to spawn sub-agents",
+      "tip": "Task tool creates specialized agents for complex work. Great for parallel exploration."
+    },
+    "first_mcp": {
+      "name": "MCP Pioneer",
+      "description": "Use an MCP tool",
+      "tip": "MCP extends Claude's abilities. Connect to databases, APIs, or custom tools."
+    },
+    "web_searcher": {
+      "name": "Web Explorer",
+      "description": "Search the web for information",
+      "tip": "Claude can search for latest docs, solutions, and APIs."
+    },
+    "skill_invoker": {
+      "name": "Skill Master",
+      "description": "Use a slash command skill",
+      "tip": "Skills are shortcuts. Try /commit, /pr, /init. Create custom skills in ~/.claude/commands/"
+    },
+    "notebook_editor": {
+      "name": "Data Scientist",
+      "description": "Edit a Jupyter notebook",
+      "tip": "Claude understands notebooks! Ask for data analysis, visualizations, or ML experiments."
+    },
+    "config_modifier": {
+      "name": "Customizer",
+      "description": "Modify Claude Code settings",
+      "tip": "Customize Claude with /config or edit ~/.claude/settings.json."
+    },
+    "hooks_user": {
+      "name": "Automation Architect",
+      "description": "Set up Claude Code hooks",
+      "tip": "Hooks run scripts on events. Use them for linting, testing, or custom workflows."
+    },
+    "ralph_starter": {
+      "name": "Loop Master",
+      "description": "Start an autonomous coding loop",
+      "tip": "Ralph Loop lets Claude work autonomously until a goal is met. Great for complex refactoring!"
+    }
+  }
+}