claude-toolkit

A standardized toolkit for Claude Code configurations across Hexium team projects. This package installs predefined templates and configurations to ensure consistent AI-assisted development practices.

🚨 Prerequisites

Claude Code must be installed first before using this toolkit. Install Claude Code from claude.ai/code if you haven't already.

✨ Features

• Standardized Configuration: Consistent Claude Code settings across all team projects
• Security-First: Pre-configured permissions with safe defaults
• Expert Agents: 5 specialized AI agents for accessibility, security, performance, code review, and documentation
• Template System: Ready-to-use agents, commands and configurations
• Status Line Integration: Built-in status line with usage tracking via ccusage
• Easy Installation: One-command setup for new projects

📦 Installation & Setup

Installation Modes

Choose your installation type based on your needs:

User Installation (Global Settings)

npx @hexium/claude-toolkit@latest user-install

Installs to your global ~/.claude/ directory with user settings and MCP server configuration.

Project Installation (Project Settings)

npx @hexium/claude-toolkit@latest project-install

Installs to your project's .claude/ directory with team configurations.

💡 Get Help

Both installation scripts support help flags for detailed usage information:

npx @hexium/claude-toolkit@latest user-install --help
npx @hexium/claude-toolkit@latest project-install --help

Use -h or --help to see all available options, examples, and detailed descriptions.

Requirements

• Node.js 18.0.0 or higher
• npm or yarn package manager

What Gets Created

After installation, the following configuration is created in the appropriate location:

• settings.json - Team configuration with permissions and defaults
• agents/hxm/ - Hexium team expert AI agents
• commands/hxm/ - Hexium team custom commands
• .mcp.json - MCP server configuration (project installation only)

⚙️ Configuration

MCP Environment Variables

The toolkit includes MCP server integrations that may require environment variables. Add these to your global shell profile:

# ~/.zshrc or ~/.bashrc
export CLICKUP_API_KEY="your_clickup_api_key"
export CLICKUP_TEAM_ID="your_clickup_team_id"

After adding these variables, restart your terminal or run:

source ~/.zshrc  # or ~/.bashrc

Important: Settings Management

Settings management works differently for user and project installations:

User Installation (~/.claude/)

For user installations, the toolkit uses an interactive merge process that respects your existing settings:

• Interactive installation: Prompts you to select which settings to update
• Force mode: --force flag overwrites all settings
• Opt-out capability: You can choose to skip specific setting changes during installation
• No local overrides: User-level settings cannot be overridden by .local.json files
• Backup creation: Automatic backups are created before any changes

Project Installation (.claude/)

For project installations, settings follow Claude Code's standard hierarchy:

⚠️ DO NOT edit .claude/settings.json directly!

The settings.json file contains team-wide standards and should remain unchanged as it will be overwritten by the setup script. For project-specific customizations, create a .claude/settings.local.json file:

# Create local settings override
touch .claude/settings.local.json

Example .claude/settings.local.json:

{
  "permissions": {
    "allow": ["Bash(npm:dev)", "Bash(docker:*)"]
  },
  "model": "opus"
}

Configuration Hierarchy (project level only):

1. .claude/settings.local.json (highest priority - project-specific overrides)
2. .claude/settings.json (team defaults)

Default Permissions

The toolkit includes safe default permissions:

Allowed:

• Basic file operations (find, grep, rg, ls)
• Safe git commands (status, log, diff)
• MCP integrations (clickup, context7, sentry)

Denied:

• Network requests (curl)
• Environment files (.env, .env.*)
• Secrets directory (./secrets/**)

📁 Project Structure

claude-toolkit/
├── bin/
│   ├── user-install.js      # User installation script
│   └── project-install.js   # Project installation script
├── lib/
│   ├── file-utils.js        # File operation utilities
│   └── settings-merger.js   # Settings management utilities
├── scripts/
│   └── validate.js          # Validation script
├── templates/
│   ├── agents/              # Expert agents templates
│   ├── commands/            # Custom commands templates
│   ├── settings.json        # Team configuration template
│   └── .mcp.json           # MCP server configuration
└── README.md

🛠 Development Scripts

# Validate installation
npm test

# Re-run user setup
npx @hexium/claude-toolkit@latest user-install --force

# Re-run project setup
npx @hexium/claude-toolkit@latest project-install --force

🏗 Team Standards

This toolkit enforces Hexium team standards:

• Model: Claude Sonnet 4 default
• Default Mode: Plan mode for complex tasks
• Status Line: Integrated usage tracking with ccusage
• Auto-commit: Disabled by default

🤖 Expert Agents

The toolkit includes 5 specialized AI agents that activate automatically:

🎯 Accessibility Expert

• WCAG 2.1/2.2 compliance audits with AA/AAA standards
• ARIA implementation and semantic HTML validation
• Keyboard navigation and screen reader compatibility
• Color contrast analysis and inclusive design

📚 Context7 Expert

• Live documentation retrieval from official sources
• Version-specific API usage and examples
• Framework integration patterns (React, Next.js, FastAPI)
• Migration guides and deprecation warnings

🔍 Code Review Expert

• Multi-layered analysis of security, performance, and quality
• OWASP Top 10 security pattern detection
• Algorithm efficiency and database optimization
• Design patterns and SOLID principles validation

🛡️ Security Expert

• OWASP Top 10 2023 vulnerability assessment
• Dependency scanning for CVEs and supply chain risks
• Secret detection and crypto implementation review
• Threat modeling using STRIDE methodology

⚡ Performance Expert

• Core Web Vitals optimization (LCP, FID, CLS)
• Bundle analysis and backend scalability assessment
• Database optimization and caching strategies
• Load testing framework and capacity planning

🔧 Custom Commands

The toolkit includes 4 intelligent commands for development workflow:

📈 HXM Bump

• Smart version bumping with automatic semver analysis
• Commit history analysis to suggest appropriate increment (major/minor/patch)
• Multi-language support (Node.js, Rust, Python, PHP)
• Conventional commit message generation

💬 HXM Commit

• Intelligent commit messages using conventional commit format
• Git diff analysis to determine commit types (feat, fix, docs, etc.)
• Staging options with --all or --files flags
• Extended descriptions for complex changes

📚 HXM Document

• Flexible documentation generator (inline JSDoc/docstrings or centralized markdown)
• Project structure analysis for relevant documentation sections only
• Organized output in structured /documentation/ folders
• Brief/detailed modes based on coverage needs

🔍 HXM Explain

• Code architecture and pattern explanation tool
• Audience-tailored explanations (developer, architect, junior)
• Multiple formats (technical deep-dive, visual diagrams, tutorials)
• Dependency mapping and data flow analysis

📊 Status Line Integration

The toolkit includes a built-in status line that displays usage information:

• Command: npx ccusage@latest statusline
• Display: Shows Claude Code usage metrics in the status line
• Configuration: Zero padding for clean display
• Updates: Automatically refreshes with latest usage data

The status line provides real-time insights into your Claude Code usage patterns and helps track project development metrics.

🔌 MCP Integration

Pre-configured MCP servers for enhanced Claude Code capabilities:

📋 ClickUp

• Task management integration with project workflows
• Issue tracking and team collaboration
• Requirements: CLICKUP_API_KEY and CLICKUP_TEAM_ID environment variables

📖 Context7

• Live documentation retrieval from official sources
• Version-specific API references and examples
• Framework integration patterns and best practices

🐛 Sentry

• Error monitoring and debugging integration
• Performance tracking and issue analysis
• Production insights for development workflow

🤝 Contributing

This is an internal Hexium team tool. For issues or suggestions:

1. Open an issue at GitHub Issues
2. Follow team development standards
3. Test changes with npm test

📄 License

MIT License - see LICENSE for details.

🔗 Links

• GitHub Repository
• npm Package
• Hexium Agency

Made with ❤️ by the Hexium Team