A local-first control plane for AI CLI tool configurations
English | ็ฎไฝไธญๆ
CCB (Claude Code Butler) is a local-first desktop application built with Electron, React, and TypeScript. Version 1.5.0 preserves the original product name while evolving the architecture into a rule-driven control plane that manages Claude Code and other AI CLI tools (Codex CLI, Gemini CLI, Antigravity) through a declarative JSON registry.
- Latest release:
1.5.1(2026-10-28); both GitHub Quality Check and Windows Release passed. Package downloads are handled by the maintainer; this release has not had additional local execution acceptance of the cloud-built packages. Signing and installation lifecycle acceptance remain deferred. - v1.5.0 theme: from a Claude Code-only manager to a registry-driven multi-AI-tool configuration control plane
- Managed targets: Claude Code, Codex CLI, Gemini CLI and Antigravity across configuration/MCP/Skills/subagents. Cursor, Qoder, WorkBuddy, TRAE, Pi and OpenCode are additional import sources.
- 1.5.1 safety fixes: serialized atomic writes, validation before configuration-set activation, accurate settings error feedback, bounded version requests, and upstream cancellation. Existing paths and data formats remain compatible.
- Final fixes: damaged or unreadable managed settings are preserved; startup, restart and restore failures are reported. The restart button actually restarts the service, while provider switches only refresh the UI after completion.
- Batch C: the standalone proxy requires accessToken and uses protocol-specific endpoints and SSE translation. Skill replacement stages and validates the complete import before swapping, with rollback on failure. See the standalone proxy guide for startup and protocol limits.
- Resource safety follow-up: discover default locations first and report missing, restricted and invalid entries separately. Existing paths, Skill attachments and permission fields are preserved. MCP recovery restores individual servers; native-file recovery explicitly restores a whole file. Stale writes are rejected and failed saves retain drafts. Automation and environment checks now belong to Tools.
- Acceptance evidence: local regression, real Electron workflows, release payloads and cloud CI are recorded separately in the acceptance report; source tests do not constitute installation acceptance.
- Release gates: dual dependency audits, preflight, ASAR integrity, SBOMs, SHA-256 and cloud provenance. The maintainer approved unsigned artifacts for 1.5.1 only; other versions still require Authenticode and invalid signatures are always rejected.
- Network mitigations: A+B pass local acceptance. TLS identity is bound to the normalized target; HEAD probes disable reuse and release responses while preserving 2xx/3xx behavior. New Node network entry points are restricted, and stale health callbacks cannot affect a restarted service. Existing paths, data formats and user data remain compatible.
- Runtime security: Electron 45.1.0 embeds Node 24.22.1; nine built-in modules match patched upstream sources and all six TLS and six DNS counterexamples are rejected. c-ares 1.34.9 / Undici 7.30.1 fall outside the 19 previously tracked advisory ranges. Application TLS/HEAD mitigations remain; signing and installation/upgrade/uninstallation acceptance remain deferred.
The product name remains Claude Code Butler. The name records the project's origin rather than limiting its architecture: new tools are integrated through a bounded registry and built-in capabilities, while CCB, .ccb, app identity, and repository identifiers remain stable.
-
๐ฏ Multi-Tool Config Lifecycle Management
- Manage Claude Code, Codex CLI, Gemini CLI, and Antigravity configurations from one place
- Create, edit, copy, import, export, backup, restore, and switch configurations
- Linked multi-file editing for tools with split configs (e.g. Codex
config.toml+auth.json), validated as one group before anything is written - Configuration-set snapshots per tool: save the current state, switch between sets from the tray, restore any time
- Support
JSON,TOML, andMarkdownconfig types with matching validation rules; new files can be created from registry-declared templates
-
๐ MCP Server Management
- Manage global and project-scoped MCP servers in one panel
- Support local command-based servers and remote
httpservers that do not require acommand - Enable, disable, duplicate, import, export, archive, and validate server availability
-
๐ง Editor & Settings Experience
- Monaco-based editor with on-demand runtime loading to keep the initial renderer light
- Lossless JSON whitespace formatting, syntax validation, and modal preview using the same editor; Markdown stays unchanged
- Artifact selector, effective-source indicator, bounded diff preview, and per-artifact template override controls
- Terminal presets, theme/language preferences, and editor behavior settings
-
๐ค Automation & Managed Mode
- Trigger-condition-action automation rules with time, file, and manual execution flows
- Managed-mode proxy tooling for request transformation, logging, diagnostics, and provider control
- Environment checks for Claude Code and related tooling versions
-
๐ Operations & Insights
- Usage analytics, model/token statistics, and project associations
- Agent and skill management panels for advanced workflows
- Local logging, UTF-8-safe file output, and privacy-friendly local storage
-
๐ Built for Daily Use
- Chinese and English UI
- Windows Portable, ZIP, and NSIS installer delivery paths
- Local-first architecture with no forced cloud dependency; remote tool registry is opt-in and signature-verified
Click to expand/collapse screenshots
| Configuration Management | MCP Server Control |
|---|---|
![]() |
![]() |
| Usage Analytics | Project Management |
|---|---|
![]() |
![]() |
| Automation Rules | Environment Check |
|---|---|
![]() |
![]() |
| Sub-Agent Management | Skills Management |
|---|---|
![]() |
![]() |
- Node.js ^24.22.1 and npm 12.2.1
- npm 12.2.1
- Python >= 3.10 only when running the local Semgrep audit
# Clone the repository
git clone https://github.com/NianLog/ClaudeCodeButler.git
# Navigate to project directory
cd ClaudeCodeButler
# Install locked application dependencies
npm ci
# Install the standalone proxy-server dependencies
npm ci --prefix src/proxy-server
# .npmrc disables install scripts; explicitly run only the reviewed Electron downloader
node node_modules/electron/install.js# Start in standard mode
npm run dev
# Start with admin privileges (required for some environment / terminal flows)
npm run dev:admin# Build the application
npm run build
# Type-check
npm run type-check
# Run tests once (non-watch mode)
npm run test -- --run
# Audit root and proxy-server dependencies
npm audit --audit-level=low
npm audit --audit-level=low --prefix src/proxy-server
# Launch the built app
npm start# Portable single-file build
npm run pack:portable
# Guided installer (NSIS)
npm run pack:installer
# ZIP package
npm run pack:zip
# Unpacked directory for fast smoke checks
npm run pack:dir
# Build Portable, NSIS, and ZIP in one release pass
npm run pack:win:allArtifacts are emitted to release/ by default:
CCB-Portable-{version}.exe- Single-file portable buildCCB-Setup-{version}.exe- Assisted installer with custom install directory and shortcut optionsCCB-{version}-win.zip- ZIP packagewin-unpacked/- Unpacked directory build
Before packaging, run npm run release:preflight:preview during development and npm run release:preflight for a production release. The production preflight intentionally fails closed while REGISTRY_TRUSTED_PUBLIC_KEYS is empty.
If the build machine sits behind a TLS-intercepting network, configure the trusted root once via NODE_EXTRA_CA_CERTS or the npm cafile setting โ disabling TLS verification is never accepted in this project. Electron distribution downloads can be accelerated with ELECTRON_MIRROR / ELECTRON_BUILDER_BINARIES_MIRROR; verify the downloaded archive against the official SHASUMS256.txt afterwards.
- The Portable target is convenient, but Electron Builder's single-file Portable flow extracts to a temporary directory before the app process becomes visible. On Windows, that means noticeably slower startup than
win-unpackedor the NSIS installer. - The NSIS installer is the recommended option when startup latency matters and a traditional installation flow is acceptable.
- The project keeps the original compressed Portable strategy to avoid large package size growth.
# Default release targets for the current platform
npm run dist
# macOS
npm run dist:mac
# Linux
npm run dist:linux
# All configured platforms
npm run dist:all- Electron: 45.1.0
- electron-vite: 5.0.0
- Vite: 7.3.6
- TypeScript: 6.0.3
- React: 19.3.1
- Ant Design: 6.6.7
- Zustand: 5.0.16
- Monaco Editor: 0.55.1 via
@monaco-editor/react4.7 (on-demand runtime) - Recharts: 2.15.4
- react-markdown: 9.1 / remark-gfm: 4.0.1
- chokidar: 3.6.0 โ file watching
- express: 5.1.0 โ managed-mode proxy-server package
- node-cron: 4.6.0 โ automation scheduling
- js-yaml: 4.3.2 โ YAML parsing
- smol-toml: 1.8.0 โ dependency-free TOML validation for Codex configs
- https-proxy-agent: 7.x โ upstream proxying for managed mode
- Vitest: 4.x (33 files / 211 tests, CI-blocking)
- ESLint: 8.57.1 (zero errors, CI-blocking with a changed-files ratchet)
- electron-builder: 26.15.3
- patch-package: 8.0.1
- Semgrep CLI: 1.169.0 (isolated in the root
.venv)
ClaudeCodeButler/
โโโ src/
โ โโโ main/ # Electron main process: services, utils, IPC registry
โ โโโ preload/ # The single contextBridge exposed to the renderer
โ โโโ renderer/ # React UI, Zustand stores, panels, locales
โ โโโ shared/ # Cross-process domain contract: tool registry model,
โ โ # registry validator, builtin registry JSON
โ โโโ proxy-server/ # Managed-mode proxy (standalone npm package)
โโโ scripts/ # dev-runner, release-preflight, signing helpers
โโโ resources/ # Icons, screenshots, packaged resources
โโโ docs/ # Version planning documents
โโโ tests/ # Unit tests per layer (main/preload/proxy/renderer/shared)
โโโ release/ # Packaging output (gitignored)
- The main process owns all filesystem, path, and subprocess access; the renderer runs fully sandboxed with a narrow IPC surface
- Tool support is declared in a declarative JSON registry (never executable code); remote registries must pass an Ed25519 โ SHA-256 โ size โ schema โ version verification chain that fails closed
- All JSON persistence is atomic (temp + rename); every artifact edit is authorized against a registry-derived allowlist and backed up before writing
- External commands run through a parameterized executor (
shell: false); network egress goes through SSRF-guarded clients
Detailed module boundaries and data flows are documented in ARCHITECTURE.md, and the user-visible capability inventory in CAPABILITIES.md.
Main and renderer communicate through a normalized IPC result shape:
{ success: true, data: T }
{ success: false, error: string }# Development
npm run dev
npm run dev:admin
# Build / preview
npm run build
npm run preview
# Quality gates
npm run type-check
npm run lint
npm run lint:changed
npm run test -- --run
npm audit --audit-level=low
npm audit --audit-level=low --prefix src/proxy-server
npm run release:preflight:preview
# Packaging
npm run pack:portable
npm run pack:installer
npm run pack:zip
npm run pack:dir
npm run pack:win:all@/โsrc/renderer/src/@shared/*โsrc/shared/*
Semgrep is isolated from the Node.js toolchain in the root .venv. Recreate and run the audited rulesets with:
python -m venv .venv
source .venv/Scripts/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-security.txt
semgrep scan \
--config p/security-audit \
--config p/owasp-top-ten \
--config p/javascript \
--exclude-rule javascript.crypto-js.cryptojs-weak-algorithm.cryptojs-weak-algorithm \
--exclude-rule javascript.koa.web.cors-default-config-koa.cors-default-config-koa \
--exclude-rule javascript.express.web.cors-default-config-express.cors-default-config-express \
--timeout 60 \
--timeout-threshold 3 \
--json-output .semgrep/security-audit.json \
--sarif-output .semgrep/security-audit.sarif \
.The three excluded registry rules require the Semgrep Pro engine. Their corresponding CryptoJS, Koa, and Express CORS cases were manually reviewed; details and the exact rationale are retained in SECURITY_AUDIT_REPORT.md.
- Renderer-only dependencies are intentionally kept out of runtime
dependencieswhere possible to reduce packaged size. - Monaco is loaded at runtime instead of being part of the initial renderer dependency graph.
- On Windows, UTF-8 handling is explicitly enforced in dev and logging related flows to reduce mojibake risk.
- Built-in registry now covers four tools: Claude Code, Codex CLI (full six capabilities incl.
config.tomlvia a comment-preservingTOML_FILE_V1codec andauth.jsonkey management), Gemini CLI, and Antigravity. - Linked multi-file editing (
editGroup): split-config tools validate the whole group first, then write sequentially through the existing authorize โ backup โ atomic-write chain. - Configuration-set snapshots (
configSet) with a per-tool dropdown in the config page and a two-layer tray quick-switch menu; Claude Code keeps its original workspace channel with hot reload. - Packaging size nearly halved (
app.asar23.16 โ 11.76 MB) via on-demand Monaco runtime, dependency pruning (axios/uuid removed), and maximum compression; network egress moved to native clients. - Single-instance lock, Windows notifications now show the app name, and startup work is deferred to idle batches.
- Parameterized privilege elevation with
execFile, executable allowlists, and platform-specific escaping; elevation confirmation now fails closed. - GitHub Actions are pinned to full commit SHAs to reduce mutable-tag supply-chain risk.
- Removed default-open CORS from the local proxy server and removed the unused CORS dependencies.
- Updated security-sensitive dependencies; root and proxy-server npm audits now report 0 vulnerabilities.
- Added a reproducible Semgrep environment, raw JSON/SARIF output workflow, and a maintained security audit report.
- Added a declarative JSON tool registry model with bounded validation and an embedded Claude Code compatibility adapter.
- Added generic
PATH_EXISTS/COMMAND_EXISTSdetection and registry-allowlisted artifact discovery. - Added a lazy-loaded AI Tool Configuration panel and effective-registry snapshot cache with storage fingerprint invalidation.
- Added backup history/restore workflows; generic backups retain at most 20 versions per artifact path.
- Added explicit, integrity-checked registry installation and last-known-good rollback; automatic checks fetch only the small manifest.
- Added Ed25519 raw-bundle signature verification and a key-rotation contract; remote registry remains fail-closed preview until the production publisher public key is injected.
- Added artifact-specific template ownership with
USER_OVERRIDE > REGISTRY > EMBEDDEDprecedence, legacy customized-template migration, and bounded diff preview. - Added registry controls under Settings/About and an on-demand local performance snapshot exporter with no sampling timer and no upload.
- Non-critical data now loads in idle batches after critical first-render initialization; app exit waits for idempotent cleanup before allowing quit.
- Claude configuration workspace paths now use a compatibility facade;
1.5.0keeps reading.ccb/claude-configsand never silently creates or migrates to a new location. - Added release preflight and a combined Windows Portable/NSIS/ZIP command; hardened Electron windows with sandboxing plus fail-closed new-window and external-navigation policies.
- Architecture and capability references live in ARCHITECTURE.md and CAPABILITIES.md; the audit evidence trail is in SECURITY_AUDIT_REPORT.md.
- The former global customizable default template is now outdated and has been replaced by per-artifact template ownership in
Settings -> Editor Settings. - Reworked template preview into an artifact-aware bounded diff while the editor continues to provide validation and formatting.
- Fixed config copy behavior to open an editor with a localized copy suffix and defer file creation until explicit save.
- Improved config-type aware validation so Markdown-based preference files are no longer forced through JSON parsing in preview flows.
- Added NSIS installer packaging as a lower-latency alternative to the single-file Portable build.
We welcome bug reports, feature proposals, documentation improvements, and code contributions.
- Fork the repository
- Create a branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m "feat: add amazing feature") - Push the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Use Conventional Commit prefixes: feat / fix / docs / refactor / perf / test / chore.
This project is licensed under the MIT License. See LICENSE for details.
Thanks to these open source projects and tools:
If this project helps you, please give it a โญ Star!
Made by NianSir
Toolchain update (2026-10-28): Electron 45.1.0, React 19, AntD 6, Zustand 5; isolated Node 24.22.1 / npm 12.2.1 for builds and the standalone proxy. TypeScript remains on parser-supported 6.0.3. Embedded Node patches have been verified; 45.0.0 evidence is historical.
The header selects one managed target. Native files, validation and backup/restore remain in Configuration. Imports use selection, redacted preview and per-item receipts; conflicts default to skip and incompatible permission/auth/variable/model semantics are blocked. Generic TRAE/Pi subagents are not converted. Skills/roles can be restored from local backups; MCP restores the whole native file. Unsaved drafts guard navigation and exit and stay in process memory. Existing paths and user data are preserved.







