@asifkibria/claude-code-toolkit 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing to Claude Code Toolkit
+
+Thank you for your interest in contributing! This project aims to be a community-driven toolkit for maintaining and optimizing Claude Code installations.
+
+## Ways to Contribute
+
+### 1. Report Issues
+- Use GitHub Issues to report bugs
+- Include your OS, Node.js version, and Claude Code version
+- Provide steps to reproduce the issue
+- Include error messages and logs if applicable
+
+### 2. Suggest Features
+- Open a GitHub Issue with the "enhancement" label
+- Describe the problem you're trying to solve
+- Explain your proposed solution
+- Consider how it fits with existing tools
+
+### 3. Submit Code
+
+#### Getting Started
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR_USERNAME/claude-code-toolkit.git
+cd claude-code-toolkit
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+#### Development Workflow
+
+1. Create a feature branch: `git checkout -b feature/my-feature`
+2. Make your changes
+3. Add tests for new functionality
+4. Ensure all tests pass: `npm test`
+5. Build successfully: `npm run build`
+6. Commit with conventional commits: `git commit -m "feat: add new feature"`
+7. Push and create a Pull Request
+
+#### Code Style
+
+- Use TypeScript for all new code
+- Follow existing code patterns
+- Add JSDoc comments for public functions
+- Keep functions focused and small
+- Handle errors gracefully
+
+#### Testing Requirements
+
+- All new features must have tests
+- Maintain or improve code coverage
+- Test edge cases and error conditions
+- Use descriptive test names
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Check coverage
+npm run test:coverage
+```
+
+#### Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(scanner): add support for detecting corrupted JSON
+fix(cli): handle missing projects directory gracefully
+docs: update installation instructions
+test(scanner): add edge case tests for nested images
+```
+
+### 4. Improve Documentation
+
+- Fix typos or unclear explanations
+- Add examples and use cases
+- Translate to other languages
+- Write tutorials or blog posts
+
+## Adding New Tools
+
+When adding a new tool to the toolkit:
+
+1. **Plan the feature**
+   - Open an issue to discuss the approach
+   - Get feedback from maintainers
+
+2. **Implement in the scanner library** (`src/lib/scanner.ts`)
+   - Add core functionality as exported functions
+   - Keep it framework-agnostic
+
+3. **Add MCP tool** (`src/index.ts`)
+   - Add tool definition in `ListToolsRequestSchema` handler
+   - Implement handler in `CallToolRequestSchema` switch
+
+4. **Add CLI command** (`src/cli.ts`)
+   - Add command handler function
+   - Update help text
+   - Add to main switch
+
+5. **Write tests** (`src/__tests__/`)
+   - Unit tests for library functions
+   - Integration tests if needed
+
+6. **Update documentation**
+   - Add to README.md
+   - Update tool reference tables
+
+## Project Structure
+
+```
+src/
+├── index.ts          # MCP server entry point
+├── cli.ts            # CLI entry point
+├── lib/
+│   └── scanner.ts    # Core library functions
+└── __tests__/
+    └── scanner.test.ts
+```
+
+## Pull Request Process
+
+1. Update the README.md with details of changes if applicable
+2. Update the CHANGELOG.md (if we have one)
+3. Ensure CI passes (tests, build, lint)
+4. Get at least one code review approval
+5. Squash and merge with a clear commit message
+
+## Code of Conduct
+
+### Our Standards
+
+- Be respectful and inclusive
+- Welcome newcomers and help them get started
+- Accept constructive criticism gracefully
+- Focus on what's best for the community
+
+### Unacceptable Behavior
+
+- Harassment, discrimination, or personal attacks
+- Trolling or inflammatory comments
+- Publishing others' private information
+- Other unprofessional conduct
+
+## Questions?
+
+- Open a GitHub Discussion for general questions
+- Tag maintainers in issues if you need help
+- Join the community chat (if available)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for helping make Claude Code better for everyone!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asif Kibria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# Claude Code Toolkit
+
+[![npm version](https://badge.fury.io/js/%40asifkibria%2Fclaude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)](https://github.com/asifkibria/claude-code-toolkit)
+
+A comprehensive MCP server and CLI toolkit for maintaining, optimizing, and troubleshooting your Claude Code installation.
+
+## Why This Toolkit?
+
+Claude Code stores conversation history, tool results, and context in local files. Over time, these can:
+
+- **Grow large** - Slowing down startup and responses
+- **Contain errors** - Corrupted data blocking API calls
+- **Accumulate clutter** - Old backups and orphaned files
+- **Become opaque** - Hard to understand what's using space
+
+This toolkit gives you visibility and control over your Claude Code data.
+
+## Features
+
+### Health Monitoring
+- Quick health checks with actionable recommendations
+- Identify problematic files before they cause issues
+- Track conversation sizes and growth
+
+### Conversation Analytics
+- View detailed statistics (messages, tool uses, images)
+- Find your largest conversations
+- Sort by size, activity, or modification date
+
+### Troubleshooting Tools
+- **Fix oversized images** - Resolve the infamous "image dimensions exceed max" error ([#2939](https://github.com/anthropics/claude-code/issues/2939))
+- **Scan for issues** - Detect problems before they break your workflow
+- **Restore from backups** - Recover when things go wrong
+
+### Maintenance Utilities
+- Automatic backup creation before changes
+- Clean up old backup files
+- Free up disk space safely
+
+## Installation
+
+### As MCP Server (Recommended)
+
+Add to Claude Code so you can ask Claude to maintain itself:
+
+```bash
+# Using npx (no install needed)
+claude mcp add --scope user toolkit -- npx -y @asifkibria/claude-code-toolkit claude-code-toolkit-server
+
+# Or install globally first
+npm install -g @asifkibria/claude-code-toolkit
+claude mcp add --scope user toolkit -- claude-code-toolkit-server
+```
+
+### As CLI Tool
+
+```bash
+# Using npx
+npx @asifkibria/claude-code-toolkit health
+
+# Or install globally
+npm install -g @asifkibria/claude-code-toolkit
+claude-code-toolkit health
+
+# Short alias
+cct health
+```
+
+### From Source
+
+```bash
+git clone https://github.com/asifkibria/claude-code-toolkit.git
+cd claude-code-toolkit
+npm install && npm run build && npm test
+```
+
+## Usage
+
+### Inside Claude Code (MCP)
+
+Once installed as an MCP server, just ask Claude:
+
+> "Check my Claude Code health"
+
+> "Show me my conversation statistics"
+
+> "Scan for any issues"
+
+> "Fix the problems you found"
+
+> "Clean up old backups older than 30 days"
+
+### Command Line
+
+```bash
+# Quick health check - start here!
+cct health
+
+# View conversation statistics
+cct stats
+cct stats --limit 20 --sort messages
+
+# Scan for issues (dry run)
+cct scan
+
+# Fix all detected issues
+cct fix
+
+# Fix specific file
+cct fix -f ~/.claude/projects/myproject/conversation.jsonl
+
+# Manage backups
+cct backups
+cct restore /path/to/backup.jsonl.backup.2024-01-01T00-00-00
+cct cleanup --days 30 --dry-run
+cct cleanup --days 30
+```
+
+## Tool Reference
+
+### MCP Tools
+
+| Tool                     | Description                                      |
+| ------------------------ | ------------------------------------------------ |
+| `health_check`           | Quick health check with recommendations          |
+| `get_conversation_stats` | Detailed statistics about all conversations      |
+| `scan_image_issues`      | Scan for oversized images and other issues       |
+| `fix_image_issues`       | Fix detected issues (creates backups)            |
+| `list_backups`           | List all backup files with sizes and dates       |
+| `restore_backup`         | Restore a conversation from backup               |
+| `cleanup_backups`        | Delete old backup files to free space            |
+
+### CLI Commands
+
+| Command          | Description                      |
+| ---------------- | -------------------------------- |
+| `health`         | Quick health check               |
+| `stats`          | Show conversation statistics     |
+| `scan`           | Scan for issues (dry run)        |
+| `fix`            | Fix all detected issues          |
+| `backups`        | List backup files                |
+| `restore <path>` | Restore from backup              |
+| `cleanup`        | Delete old backups               |
+
+### CLI Options
+
+| Option              | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `-f, --file <path>` | Target specific file                           |
+| `-d, --dry-run`     | Preview without making changes                 |
+| `--no-backup`       | Skip creating backups (not recommended)        |
+| `--days <n>`        | For cleanup: delete backups older than n days  |
+| `--limit <n>`       | For stats: limit number of results             |
+| `--sort <field>`    | For stats: size, messages, images, or modified |
+| `-h, --help`        | Show help                                      |
+| `-v, --version`     | Show version                                   |
+
+## Common Issues This Solves
+
+### "Image dimensions exceed max allowed size"
+
+This error poisons your conversation context, making all subsequent requests fail - even `/compact`. The toolkit detects and fixes these oversized images automatically.
+
+```bash
+cct scan   # See what's wrong
+cct fix    # Fix it
+```
+
+### "My Claude Code is slow to start"
+
+Large conversation files slow everything down. Use stats to find the culprits:
+
+```bash
+cct stats --sort size --limit 5
+```
+
+### "I accidentally broke something"
+
+Backups are created automatically before any fix. Restore anytime:
+
+```bash
+cct backups                    # Find your backup
+cct restore /path/to/backup    # Restore it
+```
+
+### "My disk is filling up"
+
+Clean up old backups:
+
+```bash
+cct cleanup --days 7 --dry-run  # Preview
+cct cleanup --days 7            # Delete
+```
+
+## How It Works
+
+1. **Scans** `~/.claude/projects/` for conversation files (`.jsonl`)
+2. **Analyzes** each message for issues (oversized images, malformed data)
+3. **Reports** findings with actionable recommendations
+4. **Fixes** issues by replacing problematic content with placeholders
+5. **Backs up** original files before any modifications
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests (30 tests)
+npm test
+
+# Watch mode for development
+npm run dev
+
+# Test coverage
+npm run test:coverage
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- How to report issues
+- How to suggest features
+- How to submit pull requests
+- Code style and testing requirements
+
+## Roadmap
+
+Future features under consideration:
+
+- [ ] Conversation export (markdown, JSON)
+- [ ] Context size estimation
+- [ ] Duplicate detection
+- [ ] Conversation archiving
+- [ ] Usage analytics dashboard
+- [ ] Automatic scheduled maintenance
+
+Have an idea? [Open an issue](https://github.com/asifkibria/claude-code-toolkit/issues)!
+
+## License
+
+MIT - see [LICENSE](LICENSE)
+
+## Related Resources
+
+- [Claude Code Documentation](https://docs.anthropic.com/claude-code)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code GitHub Issues](https://github.com/anthropics/claude-code/issues)
+
+---
+
+**Made with care for the Claude Code community**

package/dist/__tests__/scanner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scanner.test.d.ts.map

package/dist/__tests__/scanner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/scanner.test.ts"],"names":[],"mappings":""}