Implement claude-tools: CLI tool awareness + CLAUDE.md scaffolding

[vredchenko]

Summary

The claude-tools plugin teaches Claude Code about powerful CLI tools it wouldn't otherwise know to use (gron, eza, bat, delta, etc.) and provides CLAUDE.md scaffolding based on a battle-tested template. This is valuable because Claude defaults to cat, ls, grep when better alternatives exist on the system, and writing a good CLAUDE.md from scratch is tedious.

Original Intent

List of CLI tools for Claude to use, such as gron, mc, eza, etc — which can be more efficient than the default set that comes with Claude out of the box.

Commands

/claude-tools:setup

Purpose: Configure Claude Code for the current project — create .claude/ directory, settings, and CLAUDE.md.

Behavior:

1. Check if .claude/ directory exists; create if not
2. Check if CLAUDE.md exists at project root
   • If yes → offer to update (merge new sections, preserve existing content)
   • If no → generate from template
3. Scan the project to populate CLAUDE.md:
   • Tech stack: Detect from package.json, pyproject.toml, Cargo.toml, go.mod, Makefile
   • Directory layout: Map top-level directories with purpose annotations
   • Build/test commands: Extract from scripts in package.json, Makefile targets, etc.
   • Conventions: Detect from config files (.eslintrc, biome.json, ruff.toml, .editorconfig)
4. Generate CLAUDE.md using this template structure:

   # CLAUDE.md
   
   ## Project overview
   <name> — <one-line description from manifest>
   
   ## Tech stack
   | Component | Tool | Version |
   |-----------|------|---------|
   | Runtime | Bun | 1.3.x |
   | Language | TypeScript | 5.x |
   | Linter | Biome | 1.9.x |
   
   ## Directory layout
   | Path | Purpose |
   |------|---------|
   | `src/` | Source code |
   | `tests/` | Test files |
   
   ## Commands
   | Command | Purpose |
   |---------|---------|
   | `bun test` | Run tests |
   | `bun run build` | Build |
   
   ## Conventions
   - <detected conventions>
   
   ## CLI tools available
   - `rg` (ripgrep) — use instead of grep for searching
   - `gron` — flatten JSON for grep-able output
   - <other detected tools>

5. Create .claude/settings.json if it doesn't exist:

   {
     "permissions": {
       "allow": [],
       "deny": []
     }
   }

6. Output summary of created/updated files

Edge cases:

• Monorepo → detect workspaces and document each package
• Existing CLAUDE.md with custom sections → preserve all custom content, only add missing sections
• No manifest files → ask user about the project

/claude-tools:context

Purpose: Generate or refresh the CLAUDE.md context file with current project state.

Behavior:

1. Read existing CLAUDE.md if present
2. Re-scan project for changes since last generation:
   • New directories
   • Changed dependencies
   • New/removed scripts
   • New config files
3. Update each section while preserving user-written content:
   • Sections with <!-- auto-generated --> markers → regenerate
   • Sections without markers → preserve as-is
4. Add ## Last updated timestamp
5. Show diff of changes before applying

Edge cases:

• User has heavily customized CLAUDE.md → only update auto-generated sections
• Large monorepo → limit depth, summarize rather than enumerate

/claude-tools:tools (new)

Purpose: Reference guide for CLI tools available on the system that Claude should prefer.

Behavior:

1. Detect which enhanced CLI tools are installed by checking which / command -v:
   • File viewing: bat (vs cat), less
   • Directory listing: eza (vs ls), tree
   • Searching: rg (ripgrep, vs grep), fd (vs find), fzf
   • JSON: gron (flatten for grep), jq (query/transform)
   • Disk usage: gdu (vs du), ncdu
   • Git: delta (diff pager), gh (GitHub CLI), tea (Forgejo CLI)
   • System: btop (vs top), glances
   • File management: mc (Midnight Commander)
   • HTTP: httpie (vs curl), xh
   • Text editing: micro (vs nano/vi)
2. Output a reference table:

   Available Enhanced CLI Tools
   
   | Default  | Better Alternative | Installed | Notes |
   |----------|-------------------|-----------|-------|
   | cat      | bat               | ✓         | Syntax highlighting, line numbers |
   | ls       | eza               | ✗         | Icons, git integration |
   | grep     | rg (ripgrep)      | ✓         | 10x faster, .gitignore aware |
   | find     | fd                | ✗         | Simpler syntax, faster |
   | du       | gdu               | ✓         | Interactive, fast |
   | top      | btop              | ✓         | Beautiful, mouse support |
   | curl     | httpie/xh         | ✗         | Human-friendly HTTP |
   | jq       | gron + grep       | ✓         | Flatten JSON then grep |
   

3. For each installed tool, provide a one-line usage tip
4. Offer to add the tool list to CLAUDE.md

Edge cases:

• None of the enhanced tools installed → provide installation suggestions
• Tools installed but not in PATH → check common locations (~/.local/bin, ~/.cargo/bin)

Hooks

None — this plugin operates through commands only.

File Manifest

File	Est. Lines	Purpose
commands/setup.md	100-120	Create .claude/ dir and CLAUDE.md
commands/context.md	80-100	Update CLAUDE.md with project state
commands/tools.md	90-110	CLI tool reference and detection
README.md	150-180	Full plugin documentation
.claude-plugin/plugin.json	15-20	Plugin manifest

README Outline

1. Overview — What claude-tools does: CLI awareness + CLAUDE.md management
2. Quick Start — Installation + /claude-tools:setup
3. Commands — Table with all 3 commands
4. CLAUDE.md Template — Full reference of the generated template structure
5. CLI Tool Reference — Complete table of default vs enhanced tools
6. Tool Installation — Quick install commands for missing tools
7. Customization — How to add custom sections to CLAUDE.md that survive regeneration

Prerequisites

• No external tools required — the plugin detects what's available
• Enhanced tools are optional recommendations, not requirements

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• CLI tool comparison table is comprehensive (15+ tools)
• CLAUDE.md template is production-ready
• Plugin provides clear value beyond Claude's defaults