npm package: @localtech/claude-code-toolkit
Description: Portable Claude Code toolkit with agents, skills, and hooks for professional development workflows
Author: Carlos Fadhel
Latest version: 1.0.7

# Claude Code Toolkit

🚀 **Portable AI-Enhanced Development Environment**

Transform any project into a professional, AI-powered development workspace with specialized agents, reusable skills, automated hooks, and intelligent workflows.

## ✨ What's Included

### 🤖 **Specialized AI Agents**
- **code-reviewer**: Automated code quality and security analysis
- **doc-writer**: Professional documentation generation
- **test-generator**: Comprehensive test suite creation
- **debugger**: Systematic debugging assistance
- **researcher**: Technical research and insights
- **mobile-ui-specialist**: Professional mobile UI/UX development

### 🛠️ **Reusable Skills**
- **professional-documentation-writer**: Creates comprehensive project docs
- **mobile-ui-ux-master**: Eliminates layout and consistency issues
- **claude-code-hooks-master**: Automation and workflow enhancement
- **persistent-memory-system**: Project knowledge management

### 🔄 **Automated Hooks**
- **Pre-commit**: Code quality checks, linting, type checking
- **Post-commit**: Documentation updates, notifications, memory logging
- **Pre-push**: Deployment validation, security checks
- **Custom**: Intelligent workflow analysis and suggestions

### 🧠 **Intelligent Memory System**
- **Decisions**: Architectural choices and rationale
- **Learnings**: Development insights and patterns
- **Preferences**: User preferences and working styles
- **Context**: Current project state and evolution

## 🚀 Quick Start

### Option 1: Install from Source (Development)

```bash
# Clone or navigate to the toolkit directory
cd claude-code-toolkit

# Install dependencies
npm install

# Build the TypeScript
npm run build

# Link globally for local development
npm link

# Now you can use claude-toolkit anywhere
claude-toolkit --version
```

### Option 2: Install from npm (When Published)

```bash
# Install globally
npm install -g claude-code-toolkit

# Verify installation
claude-toolkit --version
```

### Option 3: Install in Existing Project

```bash
# Navigate to your project
cd your-project

# Install toolkit
claude-toolkit install

# Set up hooks (Linux/macOS/Git Bash)
.claude/hooks/hook-manager.sh setup
.claude/hooks/hook-manager.sh install
```

### Option 4: Create New Project with Toolkit

```bash
# Create new React project
claude-toolkit template my-awesome-app --type react

# Create new Node.js API
claude-toolkit template my-api --type node

# Create new Vue.js app
claude-toolkit template my-vue-app --type vue

# Create new Python service
claude-toolkit template my-service --type python
```

### Option 5: Manual Setup (Copy & Paste)

If you prefer manual setup, copy the `templates/.claude` directory to your project root, along with `templates/AGENTS.md` and `templates/CLAUDE.md`.

## 📦 Publishing to npm

To publish this package to npm:

```bash
# Login to npm (one-time)
npm login

# Build the package
npm run build

# Publish to npm
npm publish

# Or publish with public access (for scoped packages)
npm publish --access public
```

## 📋 Detailed Setup Guide

### Step 1: Install the Toolkit

```bash
# From source (development)
cd claude-code-toolkit && npm install && npm run build && npm link

# Or from npm (when published)
npm install -g claude-code-toolkit
```

### Step 2: Install in Your Project

```bash
# Navigate to your project
cd your-project-directory

# Install Claude Code toolkit
claude-toolkit install
```

This creates:
```
your-project/
├── .claude/
│   ├── AGENTS.md          # Agent configurations
│   ├── CLAUDE.md          # Global settings
│   ├── skills/            # Reusable skills
│   ├── hooks/             # Automation scripts
│   └── memory/            # Project knowledge
└── [your project files]
```

### Step 3: Upload Skills to Claude

1. Go to [claude.ai/settings](https://claude.ai/settings)
2. Click **Skills** in the left sidebar
3. Click **Upload skill** for each `.zip` file created:
   - `mobile-ui-ux-master.zip`
   - `professional-documentation-writer.zip`
   - `claude-code-hooks-master.zip`
   - `persistent-memory-system.zip`

### Step 4: Set Up Automation Hooks

```bash
# Make hooks executable
.claude/hooks/hook-manager.sh setup

# Install Git hooks for automatic execution
.claude/hooks/hook-manager.sh install

# Test that everything works
.claude/hooks/hook-manager.sh test
```

### Step 5: Start Developing with AI Enhancement

Now you can use natural language commands like:

```
> Create a professional README for this project
> Review this React component for mobile responsiveness
> Generate unit tests for the user authentication module
> Debug why this API endpoint is failing
> Research the best practices for state management
```

## 🎯 Key Features Explained

### Intelligent Agent Assignment
The toolkit automatically routes your requests to the most appropriate agent:

- **"Review this code"** → `code-reviewer` agent
- **"Write documentation"** → `doc-writer` agent
- **"Make this mobile-friendly"** → `mobile-ui-specialist` agent
- **"Debug this issue"** → `debugger` agent
- **"Research this technology"** → `researcher` agent

### Skill-Based Consistency
Skills ensure consistent, professional results:

- **Mobile UI/UX**: Eliminates card height mismatches, text overflow, padding inconsistencies
- **Documentation**: Creates comprehensive, well-structured docs
- **Memory**: Maintains project context across sessions

### Automated Quality Assurance
Hooks run automatically to maintain code quality:

- **Pre-commit**: Catches issues before they enter version control
- **Post-commit**: Updates docs, logs decisions, sends notifications
- **Pre-push**: Validates deployment readiness
- **Continuous**: Learns from your patterns to suggest improvements

## 🔧 CLI Commands

```bash
# Install toolkit in current project
claude-toolkit install

# Create new project with toolkit pre-installed
claude-toolkit template <name> [--type react|vue|node|python]

# List all available components
claude-toolkit list

# Update toolkit to latest version
claude-toolkit update

# Diagnose installation and health
claude-toolkit doctor
```

## 📊 Project Types Supported

### React Applications
```bash
claude-toolkit template my-react-app --type react
```
- Includes styled-components setup
- Mobile-first responsive components
- TypeScript configuration
- Testing framework ready

### Vue.js Applications
```bash
claude-toolkit template my-vue-app --type vue
```
- Vue 3 with Composition API
- Mobile-optimized components
- TypeScript support
- Vue testing utilities

### Node.js APIs
```bash
claude-toolkit template my-api --type node
```
- Express.js setup
- API documentation generation
- Testing with Jest
- Security middleware

### Python Services
```bash
claude-toolkit template my-service --type python
```
- FastAPI framework
- Automatic API documentation
- Pytest for testing
- Type hints and validation

## 🧠 Memory System

The toolkit includes an intelligent memory system that learns from your development patterns:

### Decisions Tracking
Logs architectural decisions with rationale:
```
## 2025-12-22 - Tech Stack Choice
**Decision**: Use React with TypeScript for better type safety
**Context**: Starting new web application
**Rationale**: Type safety reduces runtime errors
```

### Learning Accumulation
Captures insights and patterns:
```
## 2025-12-22 - Component Architecture
**Insight**: Container/presentational pattern improves testability
**Context**: Refactoring authentication components
**Application**: Use consistently across all feature modules
```

### Context Awareness
Maintains current project state:
```
## Current Status
- Phase: Development
- Focus: User authentication
- Next: Payment integration
- Blockers: API rate limiting
```

## 🔄 Workflow Integration

### Git Workflow Enhancement
```bash
# Traditional workflow
git add .
git commit -m "Add feature"
git push

# Enhanced workflow (automatic)
git add .
git commit -m "Add user authentication"  # Hooks run automatically
# → Code quality checks pass
# → Documentation updated
# → Memory system logs decision
# → Team notifications sent
git push  # Deployment validation runs
# → Security checks pass
# → Build verification succeeds
```

### CI/CD Integration
The hooks system integrates seamlessly with existing CI/CD:

- **Local validation** before pushing to remote
- **Consistent standards** across team members
- **Early issue detection** reduces CI failures
- **Automated deployment prep** ensures smooth releases

## 🎨 Customization

### Agent Configuration
Edit `.claude/AGENTS.md` to customize agent behaviors:

```markdown
## custom-agent
**Name**: custom-agent
**Description**: Your specialized agent
**Tools**: custom tools
**Triggers**: When you say "custom task"
**Instructions**: Your specific instructions
```

### Skill Development
Create new skills in `.claude/skills/your-skill/`:

```
your-skill/
├── SKILL.md          # Skill definition
├── templates/        # Reusable templates
├── scripts/          # Helper scripts
└── examples/         # Usage examples
```

### Hook Customization
Modify hooks in `.claude/hooks/` to match your workflow:

```bash
# Customize quality checks
edit .claude/hooks/pre-commit/code-quality-guardian.sh

# Modify notification settings
edit .claude/hooks/post-commit/smart-automations.sh
```

## 🔐 Security & Privacy

### Local Execution
- All processing happens locally
- No code sent to external servers
- Claude.ai integration respects your privacy settings

### Secure Hooks
- Hooks run with minimal permissions
- No sensitive data logged
- Configurable security scanning
- Safe automation practices

## 📈 Performance Optimization

### Hook Performance
- Pre-commit: < 10 seconds (developer experience)
- Pre-push: < 30 seconds (deployment safety)
- Post-commit: < 60 seconds (background tasks)

### Caching Strategies
- Dependency analysis caching
- Build artifact reuse
- Incremental validation
- Smart test selection

## 🐛 Troubleshooting

### Common Issues

**Hooks not running:**
```bash
# Check Git hooks installation
.claude/hooks/hook-manager.sh status

# Reinstall hooks
.claude/hooks/hook-manager.sh install
```

**Skills not available:**
```bash
# Check skill uploads
claude-toolkit doctor

# Re-upload skills to Claude.ai
# Visit https://claude.ai/settings → Skills
```

**Memory system not working:**
```bash
# Check memory directory
ls -la .claude/memory/

# Reset memory system
rm -rf .claude/memory/
claude-toolkit install --force
```

### Getting Help

1. **Run diagnostics**: `claude-toolkit doctor`
2. **Check logs**: Look in `.claude/hooks/logs/`
3. **Test components**: `claude-toolkit list`
4. **Update toolkit**: `claude-toolkit update`

## 🤝 Contributing

### Adding New Skills
1. Create skill directory: `.claude/skills/new-skill/`
2. Add `SKILL.md` with metadata and instructions
3. Test with: `claude-toolkit doctor`
4. Submit via GitHub template repository

### Improving Agents
1. Edit `.claude/AGENTS.md`
2. Test agent responses
3. Document improvements
4. Share with community

### Enhancing Hooks
1. Modify hook scripts in `.claude/hooks/`
2. Test with: `.claude/hooks/hook-manager.sh test`
3. Ensure performance requirements
4. Document changes

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- Built for the Claude Code community
- Inspired by modern development workflows
- Designed for productivity and consistency

---

**🎉 Ready to supercharge your development workflow?**

**From source:**
```bash
cd claude-code-toolkit && npm install && npm run build && npm link && claude-toolkit install
```

**From npm (when published):**
```bash
npm install -g claude-code-toolkit && claude-toolkit install
```

Then experience AI-enhanced development like never before!