npm package: @kosmas10/folder-llm-analyzer
Description: A single-file HTML application that allows you to analyze entire folders of files using Large Language Models (LLM). Upload a folder, ask questions, and get AI-powered insights across all your files. Built with React and bundled for maximum reliability.
Author: Kosmas Karadimitriou
Latest version: 0.0.15

# Folder LLM Analyzer

**Version:** 0.0.13  
**Package:** `@kosmas10/folder-llm-analyzer`

A single-file HTML application that allows you to analyze entire folders of files using Large Language Models (LLM). Upload a folder, ask questions, and get AI-powered insights across all your files.

## 🎯 Key Features

- **📁 Multi-format Support**: Analyzes text files (.txt, .md, .json, .csv, .js, .py, etc.) and PDF files
- **⚡ Batch Processing**: Process multiple files simultaneously with progress tracking
- **📊 Export Results**: Export analysis results to Excel (.xlsx) or CSV format
- **🔄 Real-time Progress**: See which file is currently being processed
- **🛡️ Error Handling**: Graceful error handling with detailed error messages
- **💻 No Installation Required**: Single HTML file that runs in any modern browser
- **⚡ Fast Loading**: 2-stage bundled React architecture for reliable, efficient loading
- **🎯 Claude Artifact Support**: Automatically detects and uses Claude when running as a Claude Artifact

## 🏗️ Architecture: 2-Stage Bundled React

This application uses a **simplified 2-stage loading architecture** with bundled React:

### Stage 1: Bootstrap (User Installs This)
- **File**: `folder-llm-analyzer-bootstrap.html`
- **Purpose**: Ultra-minimal loader (~25 lines)
- **What it does**: Fetches the latest bundled app from npm/CDN

### Stage 2: Bundled Application (Auto-Updates)
- **Package**: `@kosmas10/folder-llm-analyzer` (this package)
- **File**: `dist/folder-llm-analyzer.html`
- **Purpose**: The full Folder LLM Analyzer application
- **What it does**: Provides the complete folder analysis experience

### Why This Architecture?

1. **🛡️ Future-Proof**: Stage 1 never changes, so users never need to update their local file
2. **🔄 Auto-Updates**: The application updates automatically via npm/CDN
3. **📦 Self-Contained**: All dependencies are bundled - no external CDN issues
4. **⚡ Fast**: Single HTML file with all assets inlined

## 🚀 Quick Start

### Option A: Using the Bootstrap (Recommended)

1. **Download the bootstrap file** (one time only):
   ```bash
   curl -O https://cdn.jsdelivr.net/npm/@kosmas10/folder-llm-analyzer@latest/folder-llm-analyzer-bootstrap.html
   ```

2. **Open it in your browser**:
   - Double-click the file, or
   - Open it from your browser's File menu

3. **That's it!** The application will load automatically and stay up-to-date.

### Option B: Direct CDN Link

Simply navigate to:
```
https://cdn.jsdelivr.net/npm/@kosmas10/folder-llm-analyzer@latest/folder-llm-analyzer-bootstrap.html
```

## 📖 Usage

### 1. Configure Your LLM

**If running as a Claude Artifact**: The app automatically detects the Claude environment and uses Claude directly - no configuration needed!

**If running standalone**: On first launch, you'll be prompted to configure your AI provider:

- **Claude**: Requires an API key from [console.anthropic.com](https://console.anthropic.com)
- **OpenAI**: Requires an API key from [platform.openai.com](https://platform.openai.com)

Your API key is stored locally in your browser and never sent anywhere except to your chosen LLM provider.

### 2. Select a Folder

Click "Choose Folder" and select a folder containing files you want to analyze.

### 3. Enter Your Query

Type your question or analysis request (e.g., "Summarize the main points", "What are the key findings?")

### 4. Start Analysis

Click "Start Analysis" to begin processing. You'll see real-time progress for each file.

### 5. Export Results

Download results as Excel (.xlsx) or CSV files.

## 📁 Supported File Types

- **Text Files**: .txt, .md, .json, .csv, .xml, .html
- **Code Files**: .js, .ts, .jsx, .tsx, .py, .java, .cpp, .c
- **Style Files**: .css, .scss, .sass
- **Config Files**: .yml, .yaml, .log, .sql
- **Documents**: .pdf, .docx

## 💡 Example Queries

- "Summarize the main points of each document"
- "What are the key findings or conclusions?"
- "Extract all dates mentioned in the files"
- "What are the common themes across all documents?"
- "Identify any security concerns or vulnerabilities"
- "What are the technical requirements mentioned?"

## 🔧 Development

### Prerequisites
- Node.js >= 18.0.0
- npm

### Setup
```bash
cd folder-llm-analyzer
npm install
```

### Development Server
```bash
npm run dev
```

### Build
```bash
npm run build
```

The build produces a single HTML file at `dist/folder-llm-analyzer.html`.

## 📦 Package Structure

```
@kosmas10/folder-llm-analyzer/
├── dist/
│   └── folder-llm-analyzer.html       # Bundled application
├── folder-llm-analyzer-bootstrap.html  # Bootstrap loader
├── README.md                            # This file
└── LICENSE                              # MIT License
```

## 🌐 Browser Compatibility

- ✅ Chrome/Chromium 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+

## 🔒 Privacy & Security

- **Local Storage**: API keys stored in browser localStorage only
- **No Tracking**: No analytics or tracking code
- **Direct API Calls**: Your data goes directly to your chosen LLM provider
- **Open Source**: Full source code available for inspection

## 🐛 Troubleshooting

### Application Won't Load

1. Check your internet connection
2. Ensure cdn.jsdelivr.net is accessible (not blocked by firewall)
3. Try clearing browser cache
4. Check browser console for errors (F12)

### LLM Not Responding

1. Verify your API key is correct
2. Check you have API credits/quota available
3. Ensure the API endpoint is accessible
4. Try reconfiguring with the LLM Config button

### Folder Won't Upload

1. Ensure your browser supports the File System Access API
2. Try selecting a smaller folder first
3. Check that files are in supported formats

## 📝 Version History

### 0.0.7 (Current)
- **Complete React rewrite** using bundled React architecture
- Bundled React application with Tailwind CSS
- Simplified 2-stage loading (no intermediate loader needed)
- All dependencies bundled (PDF.js, mammoth, lucide-react, xlsx)
- Improved component-based architecture for maintainability
- TypeScript for type safety

### 0.0.6
- Removed all informational console.log statements
- Console now only shows errors

### 0.0.5
- Fixed lucide icon initialization error
- Added safe icon initialization with retry mechanism

### 0.0.4
- Bootstrap file updated with cleaner code structure

### 0.0.3
- Improved Claude Artifact detection

### 0.0.2
- Added Claude Artifact detection and automatic configuration

### 0.0.1
- Initial release

## 🤝 Contributing

Contributions are welcome! Please visit:
https://github.com/kosmas10/ai-chat-extensions

## 📄 License

MIT License - See LICENSE file for details

## 🆘 Support

For issues, questions, or feature requests:
- **GitHub Issues**: https://github.com/kosmas10/ai-chat-extensions/issues
- **Package**: https://www.npmjs.com/package/@kosmas10/folder-llm-analyzer

## 🔗 Related Packages

- **Chat & Verify**: [@kosmas10/chat-and-verify](https://www.npmjs.com/package/@kosmas10/chat-and-verify)
- **Portal**: [@kosmas10/portal](https://www.npmjs.com/package/@kosmas10/portal)

---

**Made with ❤️ for AI-powered folder analysis**