Commands

[English] · Commands-zh

Commands

Full reference for all cc-proficiency CLI commands.

init

Set up configuration and the session hook.

cc-proficiency init

No options. Runs interactively. What it does:

Detects GitHub username via gh CLI
Auto-detects locale from LANG/LC_ALL
Injects a Stop hook into ~/.claude/settings.json
Runs a full analysis of existing sessions
Creates a private Gist and pushes the first badge

Safe to re-run. If a Gist already exists, it updates rather than creating a new one.

analyze

Parse sessions and compute proficiency scores.

cc-proficiency analyze [--full]

Flag	Behavior
(none)	Incremental: only sessions not yet processed
`--full`	Re-analyzes all sessions from scratch

Example output:

Running full analysis...

  Claude Code Proficiency — @yourname
  ────────────────────────────────────────
  CC Mastery     ███████████████░░░░░   77  ●
  Tool & MCP     ███████████████████░   96  ◐
  Agentic        ██████████████░░░░░░   69  ◐
  Prompt Craft   ████████████████░░░░   81  ◐
  Context Mgmt   ████████████████████  100  ●
  ────────────────────────────────────────
  Hooks   Edit (1411x), Bash (928x), Write (542x) +5
  Skills  dev-buddy-once (5x), chatroom (2x) +5
  Tools   Read 2046 · Bash 1045 · Write 379 · Edit 367 (+12 more)
  ────────────────────────────────────────
  139 sessions · 4 projects

Confidence indicators: ● high · ◐ medium · ○ low

process

Process queued sessions from the Stop hook.

cc-proficiency process

No options. This command is called automatically by the hook after each session. You can also run it manually to drain the queue.

Behavior:

Acquires ~/.cc-proficiency/queue.lock (breaks stale locks older than 60 seconds)
Deduplicates entries by session_id
Parses transcripts with per-line error handling
Computes scores, renders SVG, pushes to Gist if configured
Atomically rotates the queue file

badge

Generate the SVG badge file.

cc-proficiency badge [--output <file>] [--animated]

Flag	Behavior
(none)	Saves to `~/.cc-proficiency/cc-proficiency.svg`
`--output <file>`	Saves to the specified path
`--animated`	Generates the animated variant (bars fill on load, numbers fade in)

The badge is a multi-locale SVG that automatically displays in the viewer's preferred language using SVG <switch> elements with systemLanguage attributes. All 6 supported languages are embedded in a single file.

Example:

cc-proficiency badge --output my-badge.svg
# Badge written to my-badge.svg

cc-proficiency badge --animated
# Badge saved to /home/you/.cc-proficiency/cc-proficiency-animated.svg

Requires prior analysis. If no data exists, prints: No analysis data. Run 'cc-proficiency analyze' first.

push

Upload the badge SVGs and data to your private GitHub Gist.

cc-proficiency push

No options. Requires gh to be authenticated and a Gist to be configured (run init first).

Pushes three files atomically: the static badge, the animated badge, and the JSON data store.

Example output:

✓ Badge + data pushed to Gist
  Static:   https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency.svg
  Animated: https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency-animated.svg

explain

Show score drivers and improvement tips.

cc-proficiency explain

No options. Reads the last analysis result and prints:

All 5 domains ranked by percentage (score / max achievable × 100)
The 2 weakest domains with specific improvement tips
Feature inventory: hooks, skills, MCP servers, top tools, flags

Scores are shown as percentages of each domain's theoretical maximum, so domains with different ceilings are comparable on the same scale.

Example output:

  Claude Code Proficiency — @yourname

  Strengths:
    Context Mgmt   100% (94/94 max)
    Tool & MCP      86% (74/86 max)
    Prompt Craft    80% (65/81 max)
    CC Mastery      92% (71/77 max)
    Agentic         76% (65/86 max)

  Areas to Improve:
    Agentic (76%)
       → Try more CC features: subagents, MCP servers, skills,
         plan mode, worktrees
    Prompt Craft (80%)
       → Structure prompts with markdown lists, provide code blocks
         and file references

  Feature Usage:
    Hooks:  Edit (1411x), Bash (928x), Write (542x) +5
    Skills: dev-buddy-once (5x), chatroom (2x) +5
    MCP:    github, context7
    Tools:  Read (2046), Bash (1045), Write (379), Edit (367) +12 more
    Flags:  ✓ Plan  ✓ Memory  ✗ Rules  ✓ Agents  ✓ Skills

  139 sessions · 4 projects

Improvement tips per domain:

Domain	Tip
CC Mastery	Enhance CLAUDE.md with imports, add hooks with matchers, create rules files, use plan mode
Tool & MCP	Chain tools deliberately (Grep→Read→Edit), set up MCP servers, use LSP integration
Agentic	Use subagents with different types, try parallel agents and worktrees
Prompt Craft	Structure prompts with markdown lists, provide code blocks and file references
Context Mgmt	Use cross-session memory files, work across multiple projects, update CLAUDE.md

achievements

View achievement progress.

cc-proficiency achievements

No options. Displays all 15 achievements with progress bars.

Example output:

  Achievements (7/15)

  👣 First Steps          ████████████ Done!
  🌱 Getting Started      ████████████ Done!
  💯 Century Club         ████░░░░░░░░ 43/100
  ⏱  10 Hour Mark         ████████████ Done!
  🏅 Centurion            ████░░░░░░░░ 39/100
  ⭐ Perfect Score        ████████████ Done!
  🎯 Well-Rounded         ██████████░░ Done!
  🏆 Master Class         ████████████ Done!
  🔥 Week Warrior         ████████████ Done!
  💪 Monthly Grinder      ███░░░░░░░░░ 9/30
  🗺  Explorer            ████████░░░░ 4/5
  🤖 Agent Master         ████████████ Done!
  🔌 MCP Explorer         ████████████ Done!
  🦉 Night Owl            ████████████ Done!
  🌐 Community            ░░░░░░░░░░░░ 0/1

Achievement data is pulled from the remote Gist store when gh is authenticated, so streak and unlock dates are accurate. See Achievements for the full list.

status

Show hook activity, queue state, and configuration.

cc-proficiency status

No options. Example output:

  cc-proficiency status

  Username:    yourname
  Gist ID:     a1b2c3d4e5f6
  Auto-upload: true
  Locale:      en
  Leaderboard: not joined

  Sessions processed: 139
  Last updated:       2026-03-18T10:22:00.000Z

  Queue pending:      0

  Hook log (last 10 entries):
    [2026-03-18T10:22:00Z] QUEUED /path/to/session.jsonl
    [2026-03-18T09:11:00Z] QUEUED /path/to/session.jsonl
    ...

  Last hook fired: 2026-03-18T10:22:00Z
  Queue lock:  none

The queue lock shows ← STALE if held for more than 60 seconds, indicating a stuck process run.

config

View or set configuration values.

cc-proficiency config [key] [value]

Usage	Behavior
`cc-proficiency config`	Print all config as JSON
`cc-proficiency config <key>`	Print a single value
`cc-proficiency config <key> <value>`	Set a value and save

Configurable keys:

Key	Type	Description
`username`	string	GitHub username
`gistId`	string	Private Gist ID for badge
`autoUpload`	boolean	Auto-push badge after each session
`public`	boolean	Make the badge Gist public (default: false)
`locale`	string	CLI output language: `en`, `zh-CN`, `es`, `fr`, `ja`, or `ko`
`leaderboard`	boolean	Leaderboard opt-in flag
`publicGistId`	string	Public profile Gist ID (set by `share`)

Examples:

cc-proficiency config
# { "username": "yourname", "gistId": "a1b2c3...", ... }

cc-proficiency config locale zh-CN
# Set locale = zh-CN

cc-proficiency config autoUpload false
# Set autoUpload = false

share

Join or leave the community leaderboard.

cc-proficiency share [--remove]

Flag	Behavior
(none)	Join the leaderboard
`--remove`	Leave the leaderboard

Joining (cc-proficiency share):

Prerequisites: gh authenticated, Gist configured, analysis data present.

What happens:

Prints a privacy notice listing what will be shared
Syncs your data to your private Gist
Creates a separate public Gist with your public profile JSON
Opens a GitHub Issue on the cc-proficiency repo to register you
Saves leaderboard: true and publicGistId to config

Example output:

  Joining the cc-proficiency leaderboard...

  This will share publicly:
    - GitHub username, domain scores, streak, achievement count
    - Total sessions and hours, member since date

  NOT shared: session details, project names, file paths, tools

  ✓ Public gist created: abc123
  ✓ Registration issue created
    https://github.com/Z-M-Huang/cc-proficiency/issues/42

  Your profile will appear once the issue is processed.

Leaving (cc-proficiency share --remove):

Opens a removal Issue on the repo
Deletes your public Gist
Clears leaderboard and publicGistId from config

See Leaderboard and Privacy for full details.

leaderboard

View community rankings.

cc-proficiency leaderboard [--sort=<field>] [--limit=N]

Option	Default	Values
`--sort`	`avg`	`avg`, `cc-mastery`, `tool-mcp`, `agentic`, `prompt-craft`, `context-mgmt`, `hours`, `streak`
`--limit`	`20`	Any positive integer

Example output:

  cc-proficiency Leaderboard (12 users)
  ──────────────────────────────────────────────────────────
   #  User             Avg   CC   Tool  Agen  Prmp  Ctx
  ──────────────────────────────────────────────────────────
    1  @alice            94    97    96    91    95    91
    2  @bob              87    82    91    85    88    89
    3  @yourname         84    77    96    69    81   100  ◄
  ...
  ──────────────────────────────────────────────────────────
  12 users · Updated just now

  --sort=<avg|cc-mastery|tool-mcp|agentic|prompt-craft|context-mgmt|hours|streak>
  --limit=N (default 20)

Your own entry is marked with ◄. Results are cached to avoid hammering GitHub.

uninstall

Remove the hook and clean up local data.

cc-proficiency uninstall

No options. What it does:

Removes the Stop hook from ~/.claude/settings.json
Deletes all files in ~/.cc-proficiency/
Removes the ~/.cc-proficiency/ directory

After running, also remove the npm package:

npm uninstall -g cc-proficiency

Note: This does not delete your GitHub Gist. Delete it manually at gist.github.com if desired.

update

Update cc-proficiency to the latest version.

cc-proficiency update
# Checking for updates...
# Already on the latest version (v0.2.6).

# Or when outdated:
# Update available: v0.2.6 → v0.3.0
# Updating cc-proficiency...
# ✓ Updated to v0.3.0

Checks the npm registry for the latest version and installs it globally. If the global npm directory requires elevated permissions, suggests the appropriate command (sudo on Unix, Administrator terminal on Windows).

Uses npm install -g cc-proficiency@<version> internally (only updates this package, not others).

version

Print version information.

cc-proficiency version
# cc-proficiency v0.2.4 (scoring v3)

Prints the npm package version and the internal scoring engine version. The scoring version increments when rule weights change, allowing detection of stale cached results.

cc-proficiency

English

中文

Español

Français

日本語

한국어

Commands

Commands

init

analyze

process

badge

push

explain

achievements

status

config

share

leaderboard

uninstall

update

version

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cc-proficiency

Clone this wiki locally