Claude Code Context Command

Universal context usage analyzer for Claude Code - Works from any directory in any project

A powerful /context command and supporting scripts that provide detailed analysis of your Claude Code session's token usage and context efficiency. Automatically detects your project configuration and works universally across all your Claude Code projects.

🎯 What This Does

The Claude Code Context Command analyzes your current session's token usage breakdown before you start working, giving you insights into your setup's efficiency and helping you optimize your Claude Code experience:

System Prompt: Base Claude Code instructions (~8.5k tokens)
System Tools: Built-in tools like Read, Write, Edit (~15.2k tokens)
MCP Tools: Active Model Context Protocol servers and their tools (variable)
Custom Agents: Agent configurations in .claude/agents/ (project-specific)
Memory Files: .claude/CLAUDE.md and other context files (project-specific)

Why check context before working? Understanding your token allocation helps you:

🧠 Know how much headroom you have for conversations
⚡ Identify heavy MCP servers you might want to disable
🎯 Optimize agent configurations for better performance
📊 Make informed decisions about project setup

☕ Want to Help Keep Building Cool Tools?

Hey! I'm Beau Lewis, and I love building apps that help people. If this tool made your Claude Code experience better and you'd like to help me keep creating useful stuff, I'd really appreciate it!

Email: blewisxx@gmail.com
Venmo: @beauintulsa
Ko-fi: https://ko-fi.com/beaulewis

No pressure at all - just happy you're using the tool! But if you're feeling generous, it definitely helps fuel more late-night coding sessions and coffee-driven development. 🚀

📊 Sample Output

  ⎿  ⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛀⛶⛶⛶⛶
     ⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛀⛶⛶⛶⛶   Context Usage
     ⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛀⛶⛶⛶⛶   claude-sonnet-4 • 177k/200k tokens (89%)
     ⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛀⛶⛶⛶⛶
     ⛁⛁⛀⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶   ⛁ System prompt: 8.5k tokens (4.8%)
     ⛁⛁⛁⛁⛀⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶   ⛁ System tools: 15.2k tokens (8.6%)
     ⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛁⛀⛶⛶⛶⛶   ⛁ MCP tools: 135.6k tokens (76.6%)
     ⛁⛁⛁⛀⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶   ⛁ Custom agents: 15.2k tokens (8.6%)
     ⛁⛀⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶   ⛁ Memory files: 2.5k tokens (1.4%)
     ⛁⛁⛁⛁⛀⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶⛶   ⛶ Free space: 23k (11%)

     MCP tools • /mcp
     └ mcp__zen__chat (zen): 1234 tokens
     └ mcp__github-official__create_or_update_file (github-official): 567 tokens
     └ mcp__fetch__fetch (fetch): 643 tokens

     Custom agents • /agents  
     └ system-integration-specialist (Project): 8234 tokens
     └ workflow-orchestrator (Project): 4523 tokens

     Memory files • /memory
     └ Project (/workspace/CLAUDE.md): 2543 tokens

Optimization Recommendations:
High Impact (>10% token reduction):
- **Consolidate MCP Servers**: Consider disabling unused MCP servers (20-40k tokens)

✨ Key Features

🌐 Universal Project Detection: Automatically finds and analyzes the nearest .claude directory
📁 Works From Anywhere: Run from any subdirectory within any Claude Code project
⚡ Fast & Cached: Sub-2-second analysis with intelligent 2-5 minute caching
🎨 Beautiful Output: Unicode progress bars and hierarchical display
🔧 Multiple Modes: Compact, standard, and detailed analysis options
👀 No Ctrl+R Needed: All modes display instantly in Claude Code
🚀 Cross-Platform: Windows, macOS, Linux, and WSL support
📊 Comprehensive Analysis: Breaks down all token usage components
💡 Smart Recommendations: Suggests concrete optimization steps

🔒 Security

This project implements comprehensive security measures to protect against common vulnerabilities and ensure safe operation in all environments.

Security Overview

The Claude Code Context Command has undergone extensive security hardening, transforming from a security score of 4/10 to 9/10 through systematic vulnerability elimination and implementation of defense-in-depth security controls.

Security Features

Our security implementation includes:

🛡️ Command Injection Prevention: All external command execution uses secure spawn() with strict argument validation
🔐 Path Traversal Protection: Comprehensive path validation prevents directory traversal attacks across all file operations
✅ Download Integrity Verification: SHA256 checksum validation ensures downloaded files haven't been tampered with
🔍 Input Validation & Sanitization: Multi-layer validation for all user inputs, file paths, and external data
🚫 Secure File Operations: All file system operations include path validation and access controls
🔒 Error Sanitization: Sensitive information is filtered from error messages to prevent data disclosure
⚡ Safe Process Execution: Elimination of unsafe exec() calls in favor of controlled spawn() operations
🛠️ Dependency Security: Regular security audits and updates of all dependencies

Security Testing

The project includes a comprehensive security test suite with 25+ test cases covering:

Command injection prevention across all input vectors
Path traversal protection for file operations
Input validation boundary testing
Error handling security verification
Process execution safety validation
Download integrity verification testing

Run security tests with:

npm test -- --grep "security"

Security Reporting

If you discover a security vulnerability, please report it responsibly:

Email: Send details to the maintainer (see support section)
GitHub Security: Use GitHub's private security reporting feature
Include: Clear reproduction steps, impact assessment, and suggested fixes

Please do not open public issues for security vulnerabilities.

Security Score Transformation

Our comprehensive security improvements eliminated all 25+ identified vulnerabilities:

Before: 4/10 security score with critical command injection risks
After: 9/10 security score with enterprise-grade security controls
Achievement: Zero tolerance for command execution vulnerabilities

The remaining 1 point reflects our commitment to continuous security improvement and regular security audits.

🛠 Requirements

Claude Code: Must be installed and configured
Node.js: Version 14.0.0 or later
Platform: Windows, macOS, Linux, or WSL

📦 Installation Options

Choose your preferred installation method:

Option 1: Quick Install (Recommended)

Linux/macOS/WSL:

git clone https://github.com/Beaulewis1977/claude-code-context-command.git
cd claude-code-context-command
./installers/install.sh

Windows (PowerShell):

git clone https://github.com/Beaulewis1977/claude-code-context-command.git
cd claude-code-context-command
.\installers\install.ps1

Option 2: One-Liner Web Install

curl -sSL https://raw.githubusercontent.com/Beaulewis1977/claude-code-context-command/main/installers/install-web.sh | bash

Option 3: NPM Global Package

npm install -g claude-code-context-command

Note: NPM package will be available after initial repository setup

Option 4: Manual Installation

Create directories:

mkdir -p ~/.claude/scripts ~/.claude/commands

Download and copy files:

# Download repository
git clone https://github.com/Beaulewis1977/claude-code-context-command.git
cd claude-code-context-command

# Copy files
cp scripts/* ~/.claude/scripts/
cp commands/context.md ~/.claude/commands/

# Set permissions (Linux/macOS/WSL)
chmod +x ~/.claude/scripts/*.js

Test installation:

node ~/.claude/scripts/context-cmd.js summary

Option 5: GitHub Template

Click the "Use this template" button on the GitHub repository
Clone your new repository
Run the installation script for your platform
Customize as needed for your workflow

🚀 Usage

Basic Usage

Once installed, use the /context command in Claude Code to analyze your setup before starting work:

/context                    # Quick overview - fits Claude Code display (22 lines)
/context standard          # Moderate detail - top servers and agents (45 lines)  
/context detailed          # Full breakdown - complete analysis with progress bars (100+ lines)

Choose the right mode for your needs:

Quick check before starting? Use /context
Planning optimizations or reviewing setup? Use /context standard
Deep analysis or troubleshooting performance? Use /context detailed

Manual Command Line Usage

You can also run the analyzer directly:

# From any directory in a Claude Code project
node ~/.claude/scripts/context-cmd.js              # Compact mode (default)
node ~/.claude/scripts/context-cmd.js standard     # Moderate detail
node ~/.claude/scripts/context-cmd.js detailed     # Full analysis

Output Modes

Compact Mode (/context):

📋 Essential token breakdown with percentages
📊 Top 3 MCP servers and agents only
🚀 Fits Claude Code display - no Ctrl+R needed!
⚡ Perfect for quick checks before starting work

Standard Mode (/context standard):

📈 Moderate detail with top 5 servers per category
🔧 Shows top 3 tools per server for focused optimization
📋 5 most resource-heavy agents listed
💡 Balanced view for planning and optimization

Detailed Mode (/context detailed):

🎨 Beautiful progress bars and full visual breakdown
📊 Complete listing of all MCP tools by server
🔍 Every custom agent with individual token counts
💡 Comprehensive optimization recommendations
🏥 Perfect for troubleshooting and deep analysis

🧭 How It Works

Smart Project Detection

The tool automatically:

Walks up the directory tree from your current location
Finds the nearest .claude directory (your project root)
Analyzes that project's configuration including:
- MCP servers from settings.local.json
- Custom agents from .claude/agents/
- Memory files like .claude/CLAUDE.md
Provides project-specific analysis with accurate token counts

Token Analysis Components

Component	Description	Typical Size
System Prompt	Base Claude Code instructions	~8.5k tokens
System Tools	Built-in Read, Write, Edit, etc.	~15.2k tokens
MCP Tools	Active MCP server tools	Variable (0-150k+)
Custom Agents	Project-specific agent files	Variable (0-50k+)
Memory Files	CLAUDE.md and context files	Variable (0-20k+)

Performance Features

Intelligent Caching: 2-5 minute cache prevents redundant analysis
Project-Specific Caching: Separate cache per project
Timeout Protection: 10-second execution limit prevents hangs
Parallel Processing: Concurrent analysis of system components
Error Recovery: Graceful fallbacks when analysis fails

✨ Instant Display in Claude Code

No more waiting or pressing Ctrl+R! All three modes have been optimized to display immediately in Claude Code:

Compact Mode: 22 lines - fits perfectly within Claude Code's default display
Standard Mode: 45 lines - shows immediately with moderate scrolling
Detailed Mode: 100+ lines - full analysis displays instantly, no buffer delays

The command now uses optimized stdout handling to ensure you see results the moment analysis completes.

📋 Examples

High MCP Usage Scenario

MCP tools: 145.6k tokens (76.3%)
└ mcp__github-official__ (15 tools): 45.2k tokens
└ mcp__database-tools__ (8 tools): 32.1k tokens  
└ mcp__web-scraper__ (12 tools): 28.3k tokens

Recommendation: Consider disabling unused MCP servers

Agent-Heavy Project

Custom agents: 42.1k tokens (22.3%)
└ api-integration-specialist: 15.2k tokens
└ database-architect: 12.8k tokens
└ security-auditor: 14.1k tokens

Recommendation: Review agent file sizes and consolidate

Balanced Usage

Context Usage: 165k/200k tokens (82.5%)
⛁ System: 23.7k (12.1%) ⛁ MCP: 85.2k (43.4%) 
⛁ Agents: 28.1k (14.3%) ⛁ Memory: 15.2k (7.7%)
⛁ Free: 22.8k (11.4%)

Status: Well-optimized project setup

Pre-Work Workflow

# Quick check before starting work
/context                    # "52% usage, plenty of headroom"

# Planning a complex task
/context standard          # Review MCP servers, identify what's available

# Troubleshooting slow responses
/context detailed          # Find the MCP server using 45k tokens

🔧 Platform Compatibility

Platform	Shell Script	PowerShell	NPM	Manual
Windows	✅ (WSL/Git Bash)	✅	✅	✅
macOS	✅	❌	✅	✅
Linux	✅	❌	✅	✅
WSL	✅	✅	✅	✅

🐛 Troubleshooting

Common Issues

"No .claude directory found"

# Make sure you're in a Claude Code project directory
ls -la .claude/  # Should show project configuration

"Node.js not found"

# Install Node.js from https://nodejs.org/
node --version  # Should show v14.0.0 or later

"Permission denied"

# Fix script permissions (Linux/macOS/WSL)
chmod +x ~/.claude/scripts/*.js

"Analysis timeout"

# The analyzer includes a 10-second timeout for safety
# Large projects with many MCP servers may need optimization

Getting Help

Installation Issues: Check our Installation Guide
Usage Questions: See Usage Documentation
Bug Reports: Open an issue

🔄 Updating

Git-based installations:

cd claude-code-context-command
git pull
./installers/install.sh  # Re-run installer

NPM installations:

npm update -g claude-code-context-command

🗑 Uninstalling

Remove files:

rm -rf ~/.claude/scripts/context-*.js
rm ~/.claude/scripts/package.json
rm ~/.claude/commands/context.md

NPM installations:

npm uninstall -g claude-code-context-command
# Then manually remove files as above

🏗 Development

Project Structure

claude-code-context-command/
├── scripts/                    # Core analysis scripts
│   ├── context-analyzer.js     # Main analysis engine  
│   ├── context-analyzer-simple.js  # Fast analyzer
│   ├── context-cmd.js          # Command wrapper with caching
│   └── package.json            # Node.js module config
├── commands/
│   └── context.md              # Claude Code slash command
├── installers/                 # Installation scripts
│   ├── install.sh              # Linux/macOS/WSL
│   ├── install.ps1             # Windows PowerShell
│   └── install-web.sh          # Web installer
├── npm/                        # NPM package files
└── docs/                       # Documentation

Contributing

We'd love your help! Whether you want to fix bugs, add features, improve docs, or test on different platforms.

Quick start:

Fork this repository
Create a feature branch: git checkout -b feature-name
Make your changes
Test on multiple platforms
Submit a pull request

For detailed guidelines, see CONTRIBUTING.md

Local Development

# Clone and test
git clone https://github.com/Beaulewis1977/claude-code-context-command.git
cd claude-code-context-command

# Test scripts directly
node scripts/context-analyzer.js summary

# Test installation
./installers/install.sh

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support & Help

GitHub Issues: Report bugs or request features
Documentation: Full documentation
Repository: Source code

🎉 Acknowledgments

Built for the Claude Code community
Inspired by the need for better context management in AI development
Thanks to all contributors and users providing feedback

Designed & Built by Beau Lewis • Made with ❤️ for the Claude Code community

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.claude		.claude
.github		.github
commands		commands
docs		docs
examples		examples
installers		installers
lib		lib
npm		npm
scripts		scripts
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
claude-code-context-command		claude-code-context-command
package.json		package.json
setup-branch-protection.sh		setup-branch-protection.sh

License

Beaulewis1977/claude-code-context-command

Folders and files

Latest commit

History

Repository files navigation

Claude Code Context Command

🎯 What This Does

☕ Want to Help Keep Building Cool Tools?

📊 Sample Output

✨ Key Features

🔒 Security

Security Overview

Security Features

Security Testing

Security Reporting

Security Score Transformation

🛠 Requirements

📦 Installation Options

Option 1: Quick Install (Recommended)

Option 2: One-Liner Web Install

Option 3: NPM Global Package

Option 4: Manual Installation

Option 5: GitHub Template

🚀 Usage

Basic Usage

Manual Command Line Usage

Output Modes

🧭 How It Works

Smart Project Detection

Token Analysis Components

Performance Features

✨ Instant Display in Claude Code

📋 Examples

High MCP Usage Scenario

Agent-Heavy Project

Balanced Usage

Pre-Work Workflow

🔧 Platform Compatibility

🐛 Troubleshooting

Common Issues

Getting Help

🔄 Updating

🗑 Uninstalling

🏗 Development

Project Structure

Contributing

Local Development

📄 License

🙋‍♂️ Support & Help

🎉 Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages