claude-launcher 0.1.0__tar.gz

claude_launcher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude Launcher Contributors
+
+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.

claude_launcher-0.1.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: claude-launcher
+Version: 0.1.0
+Summary: Fast context switching for Claude Code in multi-project environments
+Author: Solent Labs™
+License: MIT
+Project-URL: Homepage, https://github.com/solentlabs/claude-launcher
+Project-URL: Repository, https://github.com/solentlabs/claude-launcher
+Project-URL: Issues, https://github.com/solentlabs/claude-launcher/issues
+Keywords: claude,launcher,project-switcher,productivity,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: iterfzf>=1.4.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Dynamic: license-file
+
+# Claude Launcher
+
+Fast context switching for Claude Code in multi-project environments.
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Community Project** - This is an independent tool built by the community, not affiliated with Anthropic.
+
+## Overview
+
+Claude Launcher is a productivity tool for developers working with multiple Claude Code projects. It provides fast project discovery, tree-structured navigation, and intelligent context switching with an interactive fuzzy-search interface powered by fzf.
+
+## Features
+
+- 🔍 **Auto-discovery** - Automatically finds git repositories in configured directories
+- 📋 **Alphabetical organization** - Projects sorted by path for easy navigation
+- ⚡ **Smart defaults** - Cursor starts on your last opened project
+- 🔎 **Fuzzy search** - Interactive project selection powered by fzf
+- 📄 **Rich previews** - Shows CLAUDE.md, git status, and directory contents
+- 🎯 **Manual paths** - Add non-git projects manually
+- 🔄 **Git clone integration** - Clone and launch repositories directly
+- 🛡️ **Error recovery** - Automatic database corruption recovery
+- 🖥️ **Cross-platform** - Works on Linux, macOS, and Windows
+
+## Installation
+
+### From PyPI (Recommended)
+```bash
+pip install claude-launcher
+```
+
+### From Source (Development)
+```bash
+git clone https://github.com/solentlabs/claude-launcher.git
+cd claude-launcher
+pip install -e .
+```
+
+### With Development Dependencies
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Initial Setup
+Run the first-time setup wizard to configure scan directories:
+
+```bash
+claude-launcher --setup
+```
+
+You'll be prompted to enter directories to scan for projects (e.g., `~/projects`, `~/work`).
+
+### Basic Usage
+
+```bash
+# Launch interactive project selector
+claude-launcher
+
+# Jump directly to last opened project
+claude-launcher --recent
+
+# List all discovered projects
+claude-launcher --list
+```
+
+### Managing Projects
+
+```bash
+# Add a manual project path
+claude-launcher --add
+
+# Remove a manual path
+claude-launcher --remove
+
+# Clone a git repository
+claude-launcher --clone
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-launcher` | Launch interactive project selector |
+| `claude-launcher --setup` | Run first-time setup or reconfigure |
+| `claude-launcher --add` | Add a manual project path via directory browser |
+| `claude-launcher --remove` | Remove a manual path |
+| `claude-launcher --list` | List all discovered projects |
+| `claude-launcher --recent` | Jump to last opened project |
+| `claude-launcher --clone` | Clone a git repository |
+
+## Configuration
+
+Configuration files are stored in platform-specific locations:
+
+- **Linux/WSL:** `~/.config/claude-launcher/config.toml`
+- **macOS:** `~/Library/Application Support/claude-launcher/config.toml`
+- **Windows:** `%LOCALAPPDATA%\claude-launcher\config.toml`
+
+### Configuration Options
+
+```toml
+[scan]
+# Directories to scan for git repositories
+paths = [
+    "~/projects",
+    "~/work",
+    "/mnt/c/Users/username/dev",  # WSL example
+]
+
+# Maximum directory depth to scan
+max_depth = 5
+
+# Directories to skip during scanning
+prune_dirs = [
+    "node_modules",
+    ".cache",
+    "venv",
+    "__pycache__",
+    ".git",
+]
+
+[ui]
+# Preview pane width (characters)
+preview_width = 70
+
+# Show git status in preview
+show_git_status = true
+
+[history]
+# Maximum access history entries to keep
+max_entries = 50
+```
+
+### Path Expansion
+
+Paths in configuration support:
+- Tilde expansion: `~/projects` → `/home/user/projects`
+- Environment variables: `$HOME/projects` → `/home/user/projects`
+
+## Data Storage
+
+Project data (manual paths, history) is stored in SQLite:
+
+- **Linux/WSL:** `~/.local/share/claude-launcher/projects.db`
+- **macOS:** `~/Library/Application Support/claude-launcher/projects.db`
+- **Windows:** `%LOCALAPPDATA%\claude-launcher\projects.db`
+
+## How It Works
+
+1. **Discovery**: Scans configured directories for `.git` folders
+2. **Manual Paths**: Combines discovered repos with manually added paths
+3. **Sorting**: Sorts all projects alphabetically by path
+4. **Selection**: Shows fuzzy-searchable list with preview pane
+5. **Default Cursor**: Positions cursor on last opened project
+6. **Launch**: Changes to selected directory and executes `claude` command
+7. **Tracking**: Records selection for next session
+
+## Preview Pane
+
+The preview pane shows:
+
+1. **CLAUDE.md** (first 20 lines) - Project-specific Claude Code instructions
+2. **Git Status** - Current working tree status (if git repo)
+3. **Directory Listing** - Top-level files and folders
+
+## Windows Terminal Integration
+
+Add to your Windows Terminal `settings.json`:
+
+```json
+{
+    "name": "Claude Launcher",
+    "commandline": "wsl.exe -d Ubuntu -- bash -lic claude-launcher",
+    "icon": "📂"
+}
+```
+
+## Error Handling
+
+Claude Launcher includes robust error recovery:
+
+- **Database corruption**: Automatically backs up and recreates
+- **Missing manual paths**: Auto-removes from database
+- **Invalid config**: Falls back to sensible defaults
+- **Git failures**: Gracefully degrades (shows project without status)
+- **Permission errors**: Logs and continues scanning
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=claude_launcher --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_discovery.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Type checking
+mypy src/
+
+# Lint
+flake8 src/ tests/
+```
+
+### Project Structure
+
+```
+claude-workflow/
+├── src/claude_launcher/
+│   ├── core/           # Core functionality
+│   │   ├── models.py   # Data models
+│   │   ├── config.py   # Configuration management
+│   │   ├── discovery.py # Project discovery
+│   │   └── storage.py  # SQLite storage
+│   ├── ui/             # User interface
+│   │   ├── selector.py # Main TUI
+│   │   ├── preview.py  # Preview generation
+│   │   └── browser.py  # Directory browser
+│   ├── utils/          # Utilities
+│   │   └── git.py      # Git operations
+│   └── cli.py          # CLI entry point
+└── tests/              # Test suite
+```
+
+## Requirements
+
+- **Python**: 3.8 or higher
+- **fzf**: Interactive fuzzy finder ([installation guide](https://github.com/junegunn/fzf#installation))
+  - Ubuntu/Debian: `sudo apt install fzf`
+  - macOS: `brew install fzf`
+  - Windows: `choco install fzf`
+- **Git**: For repository discovery and status
+- **Claude Code CLI**: Must be installed and in PATH
+
+## Troubleshooting
+
+### "claude command not found"
+Ensure Claude Code CLI is installed and accessible in your PATH.
+
+### No projects found
+1. Run `claude-launcher --setup` to configure scan paths
+2. Verify paths exist and contain git repositories
+3. Check permissions on directories
+
+### Database errors
+The database auto-recovers from corruption. Check for `.db.backup.*` files if you need to restore data.
+
+### Permission denied during scan
+Some directories may not be readable. These are automatically skipped with a warning.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### 0.1.0 (Initial Release)
+- Project discovery with git repository scanning
+- Alphabetical sorting with last-opened default
+- Interactive fuzzy search with preview pane
+- Manual path management
+- Git clone integration
+- Error recovery
+- Cross-platform support

claude_launcher-0.1.0/README.md

@@ -0,0 +1,291 @@
+# Claude Launcher
+
+Fast context switching for Claude Code in multi-project environments.
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Community Project** - This is an independent tool built by the community, not affiliated with Anthropic.
+
+## Overview
+
+Claude Launcher is a productivity tool for developers working with multiple Claude Code projects. It provides fast project discovery, tree-structured navigation, and intelligent context switching with an interactive fuzzy-search interface powered by fzf.
+
+## Features
+
+- 🔍 **Auto-discovery** - Automatically finds git repositories in configured directories
+- 📋 **Alphabetical organization** - Projects sorted by path for easy navigation
+- ⚡ **Smart defaults** - Cursor starts on your last opened project
+- 🔎 **Fuzzy search** - Interactive project selection powered by fzf
+- 📄 **Rich previews** - Shows CLAUDE.md, git status, and directory contents
+- 🎯 **Manual paths** - Add non-git projects manually
+- 🔄 **Git clone integration** - Clone and launch repositories directly
+- 🛡️ **Error recovery** - Automatic database corruption recovery
+- 🖥️ **Cross-platform** - Works on Linux, macOS, and Windows
+
+## Installation
+
+### From PyPI (Recommended)
+```bash
+pip install claude-launcher
+```
+
+### From Source (Development)
+```bash
+git clone https://github.com/solentlabs/claude-launcher.git
+cd claude-launcher
+pip install -e .
+```
+
+### With Development Dependencies
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Initial Setup
+Run the first-time setup wizard to configure scan directories:
+
+```bash
+claude-launcher --setup
+```
+
+You'll be prompted to enter directories to scan for projects (e.g., `~/projects`, `~/work`).
+
+### Basic Usage
+
+```bash
+# Launch interactive project selector
+claude-launcher
+
+# Jump directly to last opened project
+claude-launcher --recent
+
+# List all discovered projects
+claude-launcher --list
+```
+
+### Managing Projects
+
+```bash
+# Add a manual project path
+claude-launcher --add
+
+# Remove a manual path
+claude-launcher --remove
+
+# Clone a git repository
+claude-launcher --clone
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-launcher` | Launch interactive project selector |
+| `claude-launcher --setup` | Run first-time setup or reconfigure |
+| `claude-launcher --add` | Add a manual project path via directory browser |
+| `claude-launcher --remove` | Remove a manual path |
+| `claude-launcher --list` | List all discovered projects |
+| `claude-launcher --recent` | Jump to last opened project |
+| `claude-launcher --clone` | Clone a git repository |
+
+## Configuration
+
+Configuration files are stored in platform-specific locations:
+
+- **Linux/WSL:** `~/.config/claude-launcher/config.toml`
+- **macOS:** `~/Library/Application Support/claude-launcher/config.toml`
+- **Windows:** `%LOCALAPPDATA%\claude-launcher\config.toml`
+
+### Configuration Options
+
+```toml
+[scan]
+# Directories to scan for git repositories
+paths = [
+    "~/projects",
+    "~/work",
+    "/mnt/c/Users/username/dev",  # WSL example
+]
+
+# Maximum directory depth to scan
+max_depth = 5
+
+# Directories to skip during scanning
+prune_dirs = [
+    "node_modules",
+    ".cache",
+    "venv",
+    "__pycache__",
+    ".git",
+]
+
+[ui]
+# Preview pane width (characters)
+preview_width = 70
+
+# Show git status in preview
+show_git_status = true
+
+[history]
+# Maximum access history entries to keep
+max_entries = 50
+```
+
+### Path Expansion
+
+Paths in configuration support:
+- Tilde expansion: `~/projects` → `/home/user/projects`
+- Environment variables: `$HOME/projects` → `/home/user/projects`
+
+## Data Storage
+
+Project data (manual paths, history) is stored in SQLite:
+
+- **Linux/WSL:** `~/.local/share/claude-launcher/projects.db`
+- **macOS:** `~/Library/Application Support/claude-launcher/projects.db`
+- **Windows:** `%LOCALAPPDATA%\claude-launcher\projects.db`
+
+## How It Works
+
+1. **Discovery**: Scans configured directories for `.git` folders
+2. **Manual Paths**: Combines discovered repos with manually added paths
+3. **Sorting**: Sorts all projects alphabetically by path
+4. **Selection**: Shows fuzzy-searchable list with preview pane
+5. **Default Cursor**: Positions cursor on last opened project
+6. **Launch**: Changes to selected directory and executes `claude` command
+7. **Tracking**: Records selection for next session
+
+## Preview Pane
+
+The preview pane shows:
+
+1. **CLAUDE.md** (first 20 lines) - Project-specific Claude Code instructions
+2. **Git Status** - Current working tree status (if git repo)
+3. **Directory Listing** - Top-level files and folders
+
+## Windows Terminal Integration
+
+Add to your Windows Terminal `settings.json`:
+
+```json
+{
+    "name": "Claude Launcher",
+    "commandline": "wsl.exe -d Ubuntu -- bash -lic claude-launcher",
+    "icon": "📂"
+}
+```
+
+## Error Handling
+
+Claude Launcher includes robust error recovery:
+
+- **Database corruption**: Automatically backs up and recreates
+- **Missing manual paths**: Auto-removes from database
+- **Invalid config**: Falls back to sensible defaults
+- **Git failures**: Gracefully degrades (shows project without status)
+- **Permission errors**: Logs and continues scanning
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=claude_launcher --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_discovery.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Type checking
+mypy src/
+
+# Lint
+flake8 src/ tests/
+```
+
+### Project Structure
+
+```
+claude-workflow/
+├── src/claude_launcher/
+│   ├── core/           # Core functionality
+│   │   ├── models.py   # Data models
+│   │   ├── config.py   # Configuration management
+│   │   ├── discovery.py # Project discovery
+│   │   └── storage.py  # SQLite storage
+│   ├── ui/             # User interface
+│   │   ├── selector.py # Main TUI
+│   │   ├── preview.py  # Preview generation
+│   │   └── browser.py  # Directory browser
+│   ├── utils/          # Utilities
+│   │   └── git.py      # Git operations
+│   └── cli.py          # CLI entry point
+└── tests/              # Test suite
+```
+
+## Requirements
+
+- **Python**: 3.8 or higher
+- **fzf**: Interactive fuzzy finder ([installation guide](https://github.com/junegunn/fzf#installation))
+  - Ubuntu/Debian: `sudo apt install fzf`
+  - macOS: `brew install fzf`
+  - Windows: `choco install fzf`
+- **Git**: For repository discovery and status
+- **Claude Code CLI**: Must be installed and in PATH
+
+## Troubleshooting
+
+### "claude command not found"
+Ensure Claude Code CLI is installed and accessible in your PATH.
+
+### No projects found
+1. Run `claude-launcher --setup` to configure scan paths
+2. Verify paths exist and contain git repositories
+3. Check permissions on directories
+
+### Database errors
+The database auto-recovers from corruption. Check for `.db.backup.*` files if you need to restore data.
+
+### Permission denied during scan
+Some directories may not be readable. These are automatically skipped with a warning.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### 0.1.0 (Initial Release)
+- Project discovery with git repository scanning
+- Alphabetical sorting with last-opened default
+- Interactive fuzzy search with preview pane
+- Manual path management
+- Git clone integration
+- Error recovery
+- Cross-platform support