AJ Avezzano
dd7557ea62
- Auto-discovers Claude Code (~/.claude/settings.json) alongside Claude Desktop - Generated icons/app.icns (macOS) and icons/app.ico (Windows) from rounded PNGs - bcc.spec: PyInstaller spec for all platforms (.app on macOS, onefile on Windows/Linux) - .github/workflows/release.yml: builds and publishes GitHub Release on version tags - scripts/build_icons.py: regenerates icon files from source PNGs - requirements-dev.txt: adds pyinstaller and pillow for building - CLAUDE.md: initial repo guidance for Claude Code Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Install runtime dependency
|
|
pip install -r requirements.txt
|
|
python bcc.py # run the GUI
|
|
python test_core.py # run unit tests (23 tests, no GUI needed)
|
|
|
|
# Build a self-contained binary
|
|
pip install -r requirements-dev.txt
|
|
python scripts/build_icons.py # regenerate icons/app.icns + icons/app.ico if needed
|
|
pyinstaller bcc.spec
|
|
# macOS → dist/BetterClaudeConfig.app
|
|
# Windows → dist/BetterClaudeConfig.exe
|
|
# Linux → dist/BetterClaudeConfig
|
|
```
|
|
|
|
Requires Python 3.10+. Runtime dependency: `PySide6>=6.6`. Build-time: `pyinstaller>=6.0`, `pillow>=10.0`.
|
|
|
|
## Architecture
|
|
|
|
The codebase is split into two layers:
|
|
|
|
**`bcc_core.py`** — All logic with no GUI imports. Contains:
|
|
- `Profile` / `ServerEntry` dataclasses (the data model)
|
|
- `discover_profiles()` — scans the platform's app-support directory for `Claude*` folders (Claude Desktop) **and** always adds `~/.claude/settings.json` (Claude Code, cross-platform)
|
|
- `load_config` / `extract_servers` / `apply_servers` / `write_config` — the read/write pipeline; writes are atomic with rotating timestamped backups in `.bcc_backups/`
|
|
- `parse_pasted_json()` — accepts three JSON shapes (full config, inner map, or bare server object)
|
|
- `check_dependency()` / `diagnostics_text()` / `pin_command_path()` — PATH resolution logic; distinguishes "found on normal PATH" (ok) vs "found only on augmented PATH" (warn) vs "not found" (missing). Uses an `lru_cache`-memoized `augmented_path()` that extends the inherited PATH with common runtime locations (nvm, homebrew, cargo, volta, etc.)
|
|
- `test_remote()` — synchronous HTTP reachability check, intended to run off the UI thread
|
|
|
|
**`bcc.py`** — PySide6 GUI that is a thin shell over `bcc_core`. Key classes:
|
|
- `MainWindow` — manages the profile combo, two server tables (active/disabled), action bar, and dirty state
|
|
- `ServerEditor` — right-panel form with a `QStackedWidget` for stdio vs remote pages; calls `core.check_dependency()` on every field change
|
|
- `KeyValueTable` — reusable widget for env vars and headers
|
|
- `ConnTester(QThread)` — background thread for remote reachability tests
|
|
|
|
**The cardinal rule**: `apply_servers()` only ever writes to `mcpServers` and `_disabledMcpServers`. All other keys in the user's config are preserved verbatim and in their original order.
|
|
|
|
Disabled servers are parked under `_disabledMcpServers` (which Claude Desktop ignores) so they can be re-enabled without losing their definition.
|
|
|
|
## Packaging
|
|
|
|
- **`bcc.spec`** — PyInstaller spec; handles macOS (onedir → `.app` bundle) and Windows/Linux (onefile). Platform-aware icon selection.
|
|
- **`icons/app.icns`** (macOS) and **`icons/app.ico`** (Windows) are pre-generated and committed; source PNGs are in `icons/twin-gears/rounded/`.
|
|
- **`scripts/build_icons.py`** — regenerates both icon files from source PNGs. Uses `iconutil` (macOS-only) for `.icns`, Pillow for `.ico`.
|
|
- **`.github/workflows/release.yml`** — builds on all three platforms on tag push, publishes as GitHub Release assets.
|
|
|
|
To release: `git tag vX.Y.Z && git push --tags`.
|
|
|
|
## Key constants
|
|
|
|
- `ACCENT` at the top of `bcc.py` — the one constant to change for a rebrand
|
|
- `KNOWN_FIELDS` in `bcc_core.py` — fields the editor renders; anything else on a server object is preserved as `_extra` in `ServerEditor`
|
|
- `DISABLED_KEY = "_disabledMcpServers"` — the parking key for disabled servers
|
|
- `MAX_BACKUPS = 15` — rolling backup limit per config file
|