BMP PUA Unicode Workaround
Claude Code filters Unicode characters in the BMP Private Use Area (U+E000-U+F8FF), which includes most Nerd Font icons. This skill provides tools for working with these icons.
Quick Reference
| Range | Status | Examples |
|---|---|---|
| U+E000-U+F8FF (BMP PUA) | Filtered - use placeholders | Powerline, Devicons, Font Awesome, Octicons |
| U+F0000+ (Supplementary PUA-A) | Works directly | Material Design Icons (nf-md-*) |
Automatic Features
When reading files: A PostToolUse hook automatically identifies all PUA characters, showing icon names, codepoints, and whether they're filtered.
When writing files: A PostToolUse hook automatically converts placeholder syntax to actual Unicode characters.
Placeholder Syntax
When writing icons in the filtered BMP PUA range, use placeholder syntax:
- By codepoint:
{{ U+E0A0 }}(without the spaces) - By name:
{{ nf-fa-star }}(without the spaces)
Icon Lookup
Search for icons by name:
bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/lookup-icon.py "<search query>"
Example searches:
git branch→ finds git-related iconsfolder→ finds folder/directory iconswizard→ finds wizard icons
Character Identification
Identify a specific character:
bash# Direct argument (this is nf-md-battery, a Supplementary PUA icon) python3 ${CLAUDE_PLUGIN_ROOT}/scripts/identify-icons.py -c "" # From stdin echo "" | python3 ${CLAUDE_PLUGIN_ROOT}/scripts/identify-icons.py -
Workflow
- Reading files - Hook automatically shows icon info; use this to understand what icons are present
- Writing icons - Search with lookup script, then use placeholder syntax for filtered icons
- Comparing icons - Use identify script to check if two characters are the same icon
- Material Design Icons (U+F0000+) can be written directly without placeholders
Manual Conversion
If placeholders weren't converted (e.g., hook didn't run):
bash${CLAUDE_PLUGIN_ROOT}/scripts/convert-placeholders.py /path/to/file
