Token-Efficient Command Architecture

Overview

This repository demonstrates a token-efficient approach to Claude Code commands, reducing AI token consumption by 85-90% through npm script delegation.

🎯 Choosing the Right Approach

This repository demonstrates various ways of setting up Claude Code commands, including methods that limit token usage. You'll see these three methods:

Approach	Token Cost	Best For	Example
Direct Implementation	~2000 tokens	Learning patterns, one-off tasks, custom logic	Claude analyzes and formats commits directly
Script Delegation	~100 tokens	Repetitive tasks, stable operations	npm run lint instead of manual checks
Hybrid Approach	~500 tokens	Complex orchestration, intelligent automation	Script collects data, Claude makes decisions

When to Use Each Approach

Use Direct Implementation when:

• Teaching or learning new patterns
• Solving unique, one-time problems
• Customization is more valuable than efficiency
• You need to see Claude's problem-solving process

Use Script Delegation when:

• The task is repetitive and well-defined
• The logic rarely changes
• Speed and consistency matter more than flexibility
• You're doing the same thing multiple times per session

Use Hybrid Approach when:

• You need both efficiency and intelligence
• The task has stable parts and variable parts
• You want to leverage existing tools with AI judgment
• Real-world complexity requires both patterns

Each command in this repository includes metadata showing its approach and typical token usage, helping you understand the real costs and benefits of different patterns.

The Problem

Traditional Claude Code commands embed all logic directly in markdown files:

• Commands average 250-450 lines
• Claude reads entire file content on each use
• 19 commands × 300 lines = 5,700 lines per full scan
• Significant token consumption for repetitive tasks

The Solution: NPM Script Delegation

Architecture

┌─────────────────────┐
│  Minimal Command    │  (20-40 lines)
│   /hygiene.md       │
└──────────┬──────────┘
           │ Delegates to
           ▼
┌─────────────────────┐
│   NPM Scripts       │  (package.json)
│  npm run hygiene    │
└─────────────────────┘

Token Savings

Command	Original	Optimized	Reduction
/hygiene	264 lines	30 lines	88%
/commit	296 lines	33 lines	88%
/maintainability	458 lines	42 lines	90%
/todo	305 lines	43 lines	85%
Average	330 lines	37 lines	89%

Implementation Guide

1. Create NPM Scripts

Add comprehensive scripts to package.json:

{
  "scripts": {
    "hygiene": "npm run hygiene:quick --silent",
    "hygiene:quick": "npm run lint:check && npm run test:check",
    "lint:check": "eslint . --max-warnings 10 || echo 'No linter'",
    "test:check": "npm test || echo 'No tests'"
  }
}

2. Minimize Command Files

Transform verbose commands into minimal delegates:

Before (264 lines):

# Project Hygiene Check

[... 250+ lines of bash logic ...]

After (30 lines):

# Project Hygiene Check

\`\`\`bash
npm run hygiene:full --silent
\`\`\`

3. Benefits

For Users

• Faster Claude responses - Less content to parse
• Lower costs - Fewer tokens consumed
• Better performance - Scripts run natively
• Reusability - Scripts work without Claude

For Development

• Maintainability - Logic in one place
• Testability - Scripts testable independently
• Version control - Smaller diffs
• Cross-platform - NPM works everywhere

Usage Patterns

Direct NPM Script Execution

Users can run scripts directly without Claude:

npm run hygiene
npm run lint:check
npm run maintain:debt

Command Templates

Commands become simple script invocations:

/hygiene        # → npm run hygiene
/commit feat    # → npm run quality:pre-commit && git commit
/todo list      # → npm run todo:list

Migration Strategy

Phase 1: High-Value Commands

Migrate commands with most lines first:

1. /maintainability (458 → 42 lines)
2. /issue (442 → ~40 lines)
3. /version-tag (437 → ~40 lines)

Phase 2: Core Workflow

Migrate frequently-used commands:

1. /hygiene (264 → 30 lines)
2. /commit (296 → 33 lines)
3. /todo (305 → 43 lines)

Phase 3: Remaining Commands

Complete migration for all commands.

NPM Script Categories

Core Workflow

"hygiene": "Full health check",
"todo:list": "Show tasks",
"commit:check": "Pre-commit validation"

Quality Checks

"lint:check": "Code style validation",
"test:check": "Run test suite",
"build:check": "Build verification"

Git Operations

"git:status:summary": "Quick git status",
"git:check:staged": "Verify staged files",
"git:unpushed": "Count unpushed commits"

Maintainability

"maintain:files": "Count code files",
"maintain:debt": "Find TODO/FIXME",
"maintain:largest": "Identify large files"

Best Practices

1. Script Naming Convention

• Use colons for namespacing: category:action
• Keep names descriptive but concise
• Group related scripts together

2. Error Handling

• Use || echo 'message' for graceful failures
• Provide helpful error messages
• Return appropriate exit codes

3. Silent Flags

• Use --silent to reduce noise
• Pipe to /dev/null when appropriate
• Keep output focused and relevant

4. Composition

• Build complex scripts from simple ones
• Use && for sequential execution
• Create :quick and :full variants

Examples

Minimal Hygiene Command

---
allowed-tools: [Bash]
description: Project health check
---

# Project Hygiene Check

\`\`\`bash
npm run hygiene:full --silent
\`\`\`

Minimal Commit Command

---
allowed-tools: [Bash]
description: Quality-checked commit
---

# Quality Commit

\`\`\`bash
npm run quality:pre-commit --silent || exit 1
git commit -m "$1: $2"
\`\`\`

Measuring Success

Token Metrics

• Original: ~5,700 lines total
• Optimized: ~700 lines total
• Savings: 87% reduction

Performance Metrics

• Faster command execution
• Reduced Claude response time
• Lower API costs

Developer Experience

• Scripts work standalone
• Easy to test and debug
• Familiar npm ecosystem

Future Optimizations

1. Node.js Scripts

For complex logic, use JavaScript:

// scripts/maintainability.js
#!/usr/bin/env node
const score = calculateMaintainability();
console.log(`Score: ${score}/100`);

2. Configuration Files

Move thresholds to config:

// .claude-config.json
{
  "lint": { "maxWarnings": 10 },
  "test": { "minCoverage": 80 }
}

3. Command Aliases

Create ultra-minimal aliases:

# h.md (alias for hygiene)
\`\`\`bash
npm run hygiene
\`\`\`

Conclusion

By delegating to npm scripts, we achieve:

• 87% token reduction on average
• Better performance through native execution
• Improved maintainability with centralized logic
• Cross-platform compatibility via npm

This architecture represents best practices for token-efficient Claude Code command development.