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

# Add to your .bashrc or .zshrc
source /path/to/project-selector/cw.sh

Usage

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