convez.ai
ComandoDesign & UIIniciante
aholten

Colorful Claude Code

aholten/colorful-claude-code

Emojis e cores para comandos bash no Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin que adiciona emojis e cores ao código terminal executado pelo Claude Code, transformando comandos crípticos em elementos visualmente categorizados. Funciona como ferramenta educativa para ajudar usuários a entender o que cada comando faz apenas olhando para o ícone e cor associados.

Instalação

$npx convez-ai aholten/colorful-claude-code

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
10
Contribuidores
1

Casos de uso

  • Aprender e entender comandos bash através de pistas visuais
  • Melhorar legibilidade de execuções de terminal no Claude Code
  • Ensinar programação com reforço visual de categorias de comandos

Veredito

Ferramenta educativa bem pensada que transforma a experiência visual do Claude Code ao tornar comandos bash intuitivos através de categorizações visuais. Especialmente útil para iniciantes que ainda estão aprendendo a reconhecer comandos de terminal.

README

A tradução para o português deste README ainda está na fila.

Colorful Claude Code

Enhanced understanding at a glance.

When Claude Code runs terminal commands on your behalf, it can be hard to follow what's happening — especially if you're not familiar with the command line. Commands flash by, and unless you already know what grep, sed, or chmod means, you're left wondering what just happened on your computer.

Colorful Claude Code fixes this. It adds emoji and color-coded backgrounds to every command Claude Code runs, turning cryptic terminal text into something you can actually read at a glance.

Before:

cd /my-project && npm install && npm test

After:

📁 cd /my-project ✅ && 📦 npm install ✅ && 📦 npm test

Each command gets its own color and emoji. Operators like && and | get annotated too. Even commands nested inside $(...) are highlighted. If you don't recognize a command, the emoji gives you an immediate visual hint about what category it falls into — file operations, network requests, package management, destructive actions, and so on.

Why this matters

There are a lot of people who want to use Claude Code. There aren't a lot of people who are intimately familiar with all of the bash commands it runs. Even seasoned software engineers and command line experts can learn something from these visual reinforcements.

This plugin is an educational tool. It draws from the same principle as highlighting parts of speech while learning a language — color and symbols create visual contrast that helps your brain categorize and retain what you're seeing.

Over time, you'll start recognizing commands by their colors before you even read the text.

What you'll see

EmojiCategoryExamples
🔀Version controlgit
📦Package managersnpm, npx, pnpm, yarn
🐳Containersdocker
🐍Pythonpython, pip
🦀Rustcargo, rustc
🔵Gogo
☕Javajava, javac
💎Rubyruby, gem
🔨Build toolsmake, cmake
🌐Networkcurl, wget
🔑Remote accessssh, scp
📁Navigationcd
📋Listingls
🐱Reading filescat
🔍Searchinggrep, rg
🔎Finding filesfind, fd
💬Outputecho
🗑️Deletingrm
⚡Elevated privilegessudo
💀Stopping processeskill
🔒Permissionschmod, chown
✏️Text processingsed, awk
🗜️Archivestar, zip

Operators between commands are also annotated:

EmojiOperatorMeaning
✅&&Run next command only if previous succeeded
⚠️||Run next command only if previous failed
🔗|Pipe output to next command
⏩;Run next command regardless

Commands that aren't in the map still get a neutral background color so the full command remains visually consistent.

Nesting is visualized too: content inside matched pairs — "quotes", 'quotes', `backticks`, $(substitutions), (subshells), {groups} — renders with a partially transparent version of the command's background color, one opacity step per nesting level (full → 55% → 30%, capped there). A quoted argument to git fades through translucent oranges while a quoted echo fades through grays. At a glance you can see exactly where a string or substitution begins and ends.

Terminal cells can't render true transparency, so the effect is an alpha blend baked into the color: on terminals that advertise 24-bit color (COLORTERM=truecolor) the blend is computed exactly from the real Okabe-Ito RGB values; elsewhere it falls back to stepped 256-color shades. Force a mode with COLORFUL_COLOR_MODE=truecolor or COLORFUL_COLOR_MODE=256 if the auto-detection guesses wrong for your terminal.

How it works

This is a Claude Code plugin that uses a hook — a script that runs automatically before Claude Code executes a Bash command. It does not change what the command does. It only adds a visual annotation so you can see what's happening.

The plugin:

  1. Receives the command Claude Code is about to run
  2. Parses it into individual commands, operators, and nested expressions
  3. Looks up each command in its built-in emoji/color map
  4. Displays the annotated version with emoji and colors

It handles compound commands (cd /app && npm install), pipes (cat file | grep error), command substitutions (echo $(date)), and subshells ((git add . && git commit)).

Requirements

  • Claude Code v1.0.33 or later
  • Bash (included with macOS, Linux, Git Bash on Windows, and WSL)
  • A terminal that supports emoji and 256-color ANSI codes (most modern terminals do)

No other dependencies. No Node.js, no Python, nothing to download.

Install

From the Claude Code plugin marketplace

Once listed on the marketplace, install directly from Claude Code:

/plugin install colorful-claude-code

Manual install (from source)

  1. Clone this repository:
git clone https://github.com/aholten/colorful-claude-code.git
cd colorful-claude-code
  1. Load it as a local plugin for a single session:
claude --plugin-dir .
  1. Or, for a persistent install, open Claude Code in this directory and just ask:

"install this plugin"

The bundled install skill (skills/install/SKILL.md) walks Claude through it: it first checks whether your environment allows custom hooks at all (some managed/corporate setups don't — see Watcher mode below), then asks whether you want local (this project only) or global (all projects) scope, edits the right settings file, validates it, and smoke-tests the hook.

Update

If installed via the plugin marketplace, updates happen automatically.

If installed from source:

cd colorful-claude-code
git pull

Uninstall

If installed via the plugin marketplace:

/plugin uninstall colorful-claude-code

If installed from source, either ask Claude ("uninstall this plugin") or run:

./uninstall.sh

Watcher mode (hooks blocked by corp policy?)

Some organizations set allowManagedHooksOnly=true, which prevents custom user hooks from running. The watcher script is a workaround — it tails Claude Code's JSONL conversation log from a separate terminal and prints the same colorful emoji annotations whenever a Bash command is executed.

You don't need to figure this out yourself: when you ask Claude to install the plugin, the install skill detects managed policy first and sets up watcher mode instead of a hook that would silently never fire.

Quick start

Open a second terminal in your project directory and run:

bash /path/to/colorful-claude-code/scripts/watcher.sh

It auto-detects the most recent conversation log for the current project. You can also pass a specific session ID:

bash /path/to/colorful-claude-code/scripts/watcher.sh <session-id>

Set up a ccc alias

Add this to your ~/.bashrc or ~/.zshrc:

alias ccc='bash /path/to/colorful-claude-code/scripts/watcher.sh'

Then just run ccc in a separate terminal while using Claude Code.

Requirements

Same as the base requirements above — the watcher is pure bash too, reusing the hook's own JSON scanner to parse the log. No Python, no Node.js.

Testing

The project includes a test suite to verify everything works:

./test.sh

You can also run tests for specific components:

./test.sh parser     # test command segmentation (operators, quotes, substitutions)
./test.sh mapping    # test emoji/color lookups
./test.sh renderer   # test colored output
./test.sh hook       # test the full hook pipeline
./test.sh watcher    # test JSONL command extraction

Project structure

colorful-claude-code/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── hooks/
│   └── hooks.json           # Hook configuration
├── skills/
│   └── install/
│       └── SKILL.md         # Install skill — environment preflight, hook install, watcher fallback
├── scripts/
│   ├── annotate-pre.sh      # Main hook — parsing, mapping, and rendering in one script
│   └── watcher.sh           # Standalone log watcher for restricted environments
├── CLAUDE.md                # Onboarding pointers Claude reads when you ask it to install
├── uninstall.sh             # Non-interactive uninstall
├── test.sh                  # Test suite
├── LICENSE                  # MIT
└── README.md

Adding or changing command mappings

The live command-to-emoji mappings are the _lookup and _lookup_op tables inside scripts/annotate-pre.sh — the hook is pure bash with zero runtime dependencies, so the map is built in rather than read from a file. Each entry looks like this:

git)                echo "🔀 214 16"  ;;
  • First field — the emoji shown before the command (_ means no emoji)
  • Second — background color (256-color ANSI code)
  • Third — foreground text color, chosen to contrast with the background

Edit those tables to add new commands, change emoji, or adjust colors. Changes take effect on the next command — no need to reinstall. The background colors follow the Okabe-Ito colorblind-safe palette (documented in the comment above _lookup), so if you add a command, pick the existing category color that matches what it does.

Tuning output width

Long segments are broken at word boundaries into chunks of at most 60 characters so each styled span fits on one visual line. If you run a wider terminal and want denser output, set COLORFUL_CHUNK_WIDTH in your shell config:

export COLORFUL_CHUNK_WIDTH=80

Rough sizing guide (accounting for UI overhead):

Terminal widthSuggested COLORFUL_CHUNK_WIDTH
8050
10070
12090
140+110

Too high and long segments wrap visually, losing the bg highlight on the overflow. Too low wastes horizontal space. The hook doesn't auto-detect because Claude Code doesn't pass terminal size or a TTY through to PreToolUse hooks.

Author

Anthony Holten @aholten on GitHub

Ver o original no GitHub

Bom para

Relacionados