kezaco 🤔

Make Claude Code speak plain language 🗣️

Fais parler Claude Code simplement

You use Claude Code but don't always understand what it's doing? kezaco adds simple, non-technical explanations to every action, with visual risk indicators so you always know what's safe.

Tu utilises Claude Code mais tu comprends pas toujours ce qu'il fait ? kezaco ajoute des explications simples à chaque action, avec des indicateurs de risque visuels pour toujours savoir ce qui est safe.

✨ Before / After · Avant / Après

Creating file src/utils/helpers.js...

🟢 I'm creating a file that will contain
small helper functions we'll reuse
throughout the app.
→ Why? To keep our code DRY and organized.

🚀 Quick Start

# Install with npx (recommended)
npx kezaco install

# Or install globally
npm install -g kezaco
kezaco install

That's it! Claude Code will now explain what it's doing in French by default.

English?

npx kezaco install --lang en

🎚️ Verbosity Levels · Niveaux de Verbosité

Choose how detailed you want explanations to be:

| Level | Description | Best for | |-------|-------------|----------| | beginner | 📚 Detailed with analogies, glossary, and tips | Learning & non-technical users | | normal | 📝 Simple explanations with "Why?" | Default - most users | | minimal | ⚡ Ultra-concise: emoji + 5 words max | Experienced users | | tech | 💻 Technical language, optional rationale | Developers |

Examples by Level · Exemples par Niveau

🟢 I'm reading the package.json file (it's like your project's
ID card - it lists all installed tools, similar to an ingredient
list on a food package).
   → Why? To understand what tools are already available.
   → Best practice: Always check this file before adding new tools!

🟢 I'm reading the package.json file to check dependencies.
   → Why? To avoid installing duplicates.

🟢 Reading package.json

🟢 Parsing package.json to analyze the dependency tree.

Changing Level · Changer de Niveau

# At installation
npx kezaco install --level beginner

# Or anytime after
kezaco level tech

🚦 Risk Indicators · Indicateurs de Risque

Every action starts with a visual risk indicator:

| Indicator | Level | Description | Exemples | |:---------:|-------|-------------|----------| | 🟢 | Safe | Reversible, no impact | Read, create, search | | 🟡 | Caution | Modifies state - verify first | Edit, install, configure | | 🔴 | Danger | Irreversible or sensitive | Delete, push, deploy |

🟢 Safe Actions:

• Reading files (cat, head, tail, grep)
• Creating new files
• Searching/exploring codebase
• Running read-only commands (ls, pwd, git status)

🟡 Caution Actions:

• Modifying existing files
• Installing packages (npm install, pip install)
• Changing configuration
• Git operations (add, commit)

🔴 Danger Actions:

• Deleting files or directories
• Git push (especially to main/master)
• Running destructive commands (rm -rf)
• Database migrations
• Production deployments

📖 Commands Reference

| Command | Description | |---------|-------------| | kezaco install | Enable explanations (french, normal by default) | | kezaco install --lang en | Enable in english | | kezaco install --level beginner | Enable with beginner verbosity | | kezaco level <level> | Change verbosity level | | kezaco status | Show current configuration | | kezaco uninstall | Disable and clean up | | kezaco --help | Show help |

Full Installation Options

# All options combined
npx kezaco install --lang en --level tech

# Short flags
npx kezaco install -l en -L beginner

| Option | Short | Values | |--------|-------|--------| | --lang | -l | fr (default), en | | --level | -L | beginner, normal (default), minimal, tech |

🔧 How it Works

kezaco adds instructions to your ~/.claude/CLAUDE.md file (Claude Code's global configuration). That's it - nothing else is modified, no data is collected.

~/.claude/CLAUDE.md
├── <!-- kezaco:start -->
├── <!-- lang:fr -->
├── <!-- level:normal -->
├── [Instructions for Claude Code]
└── <!-- kezaco:end -->

❓ FAQ

No. kezaco only adds text instructions to Claude Code's config file. It doesn't run any code during Claude Code's operation.

Yes! kezaco only modifies its own block (between <!-- kezaco:start --> and <!-- kezaco:end -->). Any other content in your CLAUDE.md is preserved.

Your language setting is preserved. The new level feature is added with default (normal).

Contributions welcome! Add templates in lib/templates/[lang]/ and submit a PR.

🧪 Testing

Quick validation after installation:

# Check status
kezaco status

# Should show:
# ✅ kezaco is active
#   📝 Language: en
#   📊 Level: normal

# Fresh install
kezaco uninstall 2>/dev/null
kezaco install --lang en --level beginner
kezaco status

# Change level
kezaco level tech
kezaco status

# Error handling
kezaco install --level invalid  # Should show error

# Cleanup
kezaco uninstall
kezaco status  # Should show not installed

🤝 Contributing

PRs welcome! Ideas for contributions:

• 🌍 New languages - Add templates in lib/templates/[lang]/
• 📝 Better explanations - Improve existing templates
• 🐛 Bug fixes - Report issues or submit fixes
• 💡 Features - Suggest new features via issues

📄 License

MIT - Use it however you want!