# 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