121 lines
3.5 KiB
Markdown
121 lines
3.5 KiB
Markdown
# project-selector
|
|
|
|
FZF-based project selector for Claude Code. Navigate to projects by category, auto-create CLAUDE.md files, link skills from a marketplace, and manage running Claude sessions to prevent CPU overload.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Add to your .bashrc or .zshrc
|
|
source /path/to/project-selector/cw.sh
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
cw # Launch project selector
|
|
cw --resume # Launch with args passed to claude
|
|
```
|
|
|
|
## Features
|
|
|
|
### Category-Based Navigation
|
|
|
|
Select from organized project categories:
|
|
|
|
| Category | Paths |
|
|
|----------|-------|
|
|
| Sales | `/opt/clients/client-upfrontops/*` |
|
|
| Admin | `/opt/personal/*`, `/opt/docker-vpn` |
|
|
| Fun | `/opt/fun/*` |
|
|
| Pre-Revenue | `/opt/pre-revenue/*` |
|
|
| Clients | `/opt/clients/*` |
|
|
| Personal | `/opt/personal/*` |
|
|
| Infrastructure | `/opt/infra/*`, `/opt/docker-vpn`, `/opt/marketplace`, `/opt/tools` |
|
|
| All Repos | Scans all `.git` directories under `/opt` |
|
|
| Manual Selection | Drill down from `/opt` |
|
|
|
|
### Session Management
|
|
|
|
Prevents CPU overload from too many concurrent Claude instances:
|
|
|
|
- **Info Display**: Shows running Claude sessions at startup (load <60%, <4 sessions)
|
|
- **Hard Block**: Must kill a session to proceed (load >=60% OR >=4 sessions)
|
|
- **Orphan Detection**: Flags sessions with no controlling terminal as `(ORPHAN)`
|
|
- **Graceful Termination**: SIGTERM with 5-second wait, then SIGKILL if needed
|
|
|
|
```
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
Load: 34% (5-min avg) | Sessions: 2 running
|
|
/opt/clients/acme-corp (2h 15m, 47% CPU)
|
|
/opt/pre-revenue/newapp (45m, 23% CPU)
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
```
|
|
|
|
### CLAUDE.md Scaffolding
|
|
|
|
When navigating to a directory without a CLAUDE.md file:
|
|
|
|
1. Prompts to create one
|
|
2. Asks for project description
|
|
3. Asks for common commands
|
|
4. Generates structured CLAUDE.md
|
|
|
|
### Skill Linking
|
|
|
|
Links skills from `/opt/marketplace/skills/` to projects:
|
|
|
|
1. Multi-select skills with fzf (Tab to toggle)
|
|
2. Creates `.claude/skills/` directory
|
|
3. Symlinks selected skills
|
|
|
|
### Git Integration
|
|
|
|
- Auto-detects git repos (stops drill-down at `.git`)
|
|
- Prompts to initialize git for non-repo directories
|
|
- Shows parent repo context when in subdirectory
|
|
|
|
## Navigation Controls
|
|
|
|
| Action | Key |
|
|
|--------|-----|
|
|
| Select | Enter |
|
|
| Cancel | Esc |
|
|
| Go back | Select `[GO BACK]` |
|
|
| Change category | Select `[CHANGE CATEGORY]` |
|
|
| Start here | Select `[START HERE]` |
|
|
| Create folder | Select `[NEW FOLDER]` |
|
|
| Multi-select (skills) | Tab |
|
|
|
|
## Dependencies
|
|
|
|
- `fzf` - Fuzzy finder for selection UI
|
|
- `claude` - Claude Code CLI (auto-detects `~/.local/bin/claude` for native installer)
|
|
|
|
## Configuration
|
|
|
|
Categories and paths are defined in `cw.sh`. Edit the case statement in the `cw()` function to customize.
|
|
|
|
## Session Management Thresholds
|
|
|
|
| Condition | Behavior |
|
|
|-----------|----------|
|
|
| Load <60% AND sessions <4 | Show info, continue |
|
|
| Load >=60% OR sessions >=4 | Must kill a session |
|
|
|
|
Load is calculated as 5-minute load average divided by CPU count.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
project-selector/
|
|
├── cw.sh # Main bash function
|
|
├── README.md # This file
|
|
├── .gitignore # Ignores CLAUDE.md
|
|
└── docs/
|
|
└── plans/ # Design documents
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|