bitwize-music-studio/setup
Detects your Python environment and guides you through installing plugin dependencies. Use on first-time setup or when MCP server fails to start.
npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill setupBase directory for this skill: ${CLAUDE_PLUGIN_BASE_DIR}
Guide the user through installing bitwize-music plugin dependencies based on their Python environment and requested components.
You help users install and verify plugin dependencies.
Run these checks in parallel:
# Python version
python3 --version
# Check if externally managed
python3 -c "import sysconfig; print(sysconfig.get_path('purelib'))" 2>&1 | grep -q "/usr" && echo "EXTERNALLY_MANAGED" || echo "USER_MANAGED"
# Check for pipx
command -v pipx >/dev/null 2>&1 && echo "pipx: installed" || echo "pipx: not installed"
# Check for venv support
python3 -m venv --help >/dev/null 2>&1 && echo "venv: supported" || echo "venv: not supported"
# Platform
uname -s
IMPORTANT: Run these checks sequentially, not in parallel. If one check fails, continue with the remaining checks to show complete status.
CRITICAL: Always check the venv, not system Python!
# Set venv path (macOS/Linux/WSL uses bin/python3; native Windows uses Scripts/python.exe)
VENV_PYTHON=~/.bitwize-music/venv/bin/python3
[ -f "$VENV_PYTHON" ] || VENV_PYTHON=~/.bitwize-music/venv/Scripts/python.exe
# Check if venv exists
if [ -f "$VENV_PYTHON" ]; then
echo "✅ Venv exists at ~/.bitwize-music/venv"
# Check each component in the venv
$VENV_PYTHON -c "import mcp; print('✅ mcp installed')" 2>&1 || echo "❌ mcp not installed"
$VENV_PYTHON -c "import matchering; print('✅ matchering installed')" 2>&1 || echo "❌ matchering not installed"
$VENV_PYTHON -c "import boto3; print('✅ boto3 installed')" 2>&1 || echo "❌ boto3 not installed"
$VENV_PYTHON -c "from playwright.sync_api import sync_playwright; print('✅ playwright installed')" 2>&1 || echo "❌ playwright not installed"
# Check for version drift against requirements.txt
$VENV_PYTHON -c "
import importlib.metadata, pathlib
reqs = pathlib.Path('${CLAUDE_PLUGIN_ROOT}/requirements.txt').read_text()
stale = []
for line in reqs.splitlines():
line = line.split('#')[0].strip()
if not line or '==' not in line:
continue
name, _, ver = line.partition('==')
name = name.split('[')[0].strip()
try:
installed = importlib.metadata.version(name)
if installed != ver:
stale.append(f' {name}: {installed} → {ver}')
except importlib.metadata.PackageNotFoundError:
stale.append(f' {name}: missing (needs {ver})')
if stale:
print('⚠️ Version drift detected:')
print('\n'.join(stale))
else:
print('✅ All package versions match requirements.txt')
" 2>&1
else
echo "❌ Venv not found at ~/.bitwize-music/venv"
echo " Run: python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL"
echo " Or: py -3 -m venv ~/.bitwize-music/venv # Windows"
fi
All components are installed together in the venv via requirements.txt.
Always use the unified venv approach — it works on all platforms and is automatically detected by the plugin.
# Create unified venv (if it doesn't exist)
python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL
py -3 -m venv ~/.bitwize-music/venv # Windows (native)
# Install ALL plugin dependencies
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # Windows (native)
# Set up document hunter browser
~/.bitwize-music/venv/bin/playwright install chromium # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/playwright.exe install chromium # Windows (native)
That's it! The plugin automatically detects and uses the platform venv (~/.bitwize-music/venv on macOS/Linux/WSL, %USERPROFILE%\.bitwize-music\venv on native Windows). No configuration needed.
Works on:
Present a clear, simple installation guide:
python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # macOS/Linux/WSL
~/.bitwize-music/venv/bin/playwright install chromium # macOS/Linux/WSL
py -3 -m venv ~/.bitwize-music/venv # Windows (native)
~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # Windows (native)
~/.bitwize-music/venv/Scripts/playwright.exe install chromium # Windows (native)
/plugin status/bitwize-music:setup again to verifyAfter user reports they've installed, re-run the checks from Step 2 and confirm:
✅ MCP server: Ready
✅ Audio mastering: Ready
✅ Cloud uploads: Ready
✅ Document hunter: Ready
Next steps: Run /bitwize-music:configure to set up your workspace paths.
Use clear sections with checkboxes for status:
## bitwize-music Setup
### Environment
- Python: 3.12.3
- System: Linux
### Component Status
- [❌] MCP server
- [❌] Audio mastering
- [❌] Cloud uploads
- [❌] Document hunter
### Installation
Run these commands to install all plugin dependencies (macOS/Linux/WSL shown; see Step 3 for the Windows native `py -3` / `Scripts\` equivalents):
python3 -m venv ~/.bitwize-music/venv
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt
~/.bitwize-music/venv/bin/playwright install chromium
**After installation:**
1. Restart Claude Code
2. All components will work automatically
3. Run `/bitwize-music:setup` to verify
The plugin automatically detects `~/.bitwize-music/venv` — everything just works!
Take bitwize-music-studio/setup from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.
The instructions reference pip.
Without those the skill loads but fails at the first command.