@lkangd/cc-settings-preset

v1.1.3

Published

a day ago

A switchable, reusable runtime settings preset selector for Claude Code

0High
0Medium
0Low

lkangd

claude-code claude anthropic settings preset presets configuration cli ccsp mcp plugins skills developer-tools tui

English | 简体中文

Quick Start

前置条件： 已安装 Claude Code CLI（claude 在 PATH 中可用）。

安装

macOS（Homebrew，推荐） — 通过个人 tap lkangd/homebrew-tap 安装，会自动拉取 Node.js 20 依赖：

brew tap lkangd/tap
brew install cc-settings-preset

npm / pnpm — 需本机已有 Node.js ≥ 20.19.2：

npm install -g @lkangd/cc-settings-preset
# 或
pnpm add -g @lkangd/cc-settings-preset

安装后可用 ccsp 或 cc-settings-preset 命令。

使用

# 在项目目录中启动（推荐入口）
ccsp

# 透传 Claude Code 参数（ccsp 会接管 --settings）
ccsp claude --help
ccsp claude -p "review this PR"

# 直接运行：跳过 TUI，按名称指定预设，其余参数透传给 claude
ccsp -g work -p web
ccsp -g glm-5.1 -p Chore claude -p "汇总未关闭的 issue"
ccsp --global-preset work --project-preset web --dry-run   # 预览合并结果，不启动

# 恢复本项目最近退出的会话，并复用其原始预设 / 启动配置
ccsp --continue

# 按 session id 精确恢复某个会话，复用启动时所用的预设 / 启动配置
ccsp --resume 99580820-9437-475c-883c-399bcfba3c47

首次使用建议：

# 1. 从现有 settings 导入一份「全局基础预设」
ccsp create

# 2. 进入项目，选择预设并配置本次启动的插件 / Skill / MCP，然后启动 Claude
ccsp

# 3. 管理全局预设或项目启动预设
ccsp manage
ccsp manage --project

使用场景

CCSP（Claude Code Settings Preset）面向「同一份 Claude Code 配置，需要在不同上下文里快速切换」的日常开发。典型场景如下。

1. 多模型 / 多后端环境切换

你在不同项目里使用不同的 API Key、ANTHROPIC_BASE_URL、默认模型（如 Opus / Sonnet / 自建网关）。手动改 ~/.claude/settings.json 容易串环境。

做法： 用 ccsp create 为每个环境保存一份全局基础预设（含 env、模型相关字段等），进入项目后 ccsp 选预设即可，无需反复编辑主 settings 文件。

2. 按项目控制插件、Skill、MCP

同一套全局配置下，项目 A 需要关闭某官方插件、项目 B 要禁用 Chrome DevTools MCP、项目 C 要关掉部分 Skill。

做法： 在项目内用启动预设（Launch Preset）只覆盖 enabledPlugins、skillOverrides、deniedMcpServers，与全局基础预设合并后生成临时 settings，再启动 claude。

3. 团队内共享「基础配置」，个人保留「启动差异」

团队可约定把 .claude/settings.json 提交进仓库作为项目基线；个人仍可在本机维护全局预设，并在 .claude/.ccsp/ 下保存自己的启动组合（默认被 gitignore，避免误提交密钥）。

4. 替代「记住一长串 claude 命令」

以前可能需要：

claude --settings ~/.claude/my-api-1.json -- ...

做法： ccsp / ccsp claude -- ... 在 TUI 里选预设、勾选开关，由工具生成临时 settings 路径并调用 claude --settings <generated>。

5. 配置管理与预览

ccsp manage：浏览、重命名、删除全局基础预设，预览配置（YAML / JSON），并可直接从管理界面启动。
ccsp manage --project：管理当前仓库下的启动预设（创建 / 保存 / 重命名 / 删除 / 启动）。

6. 无头自动化 — 直接运行 + `claude -p`（亮点）

CCSP 现已支持非交互式直接启动：在命令行指定预设、合并 settings 后直接 spawn claude，无需打开 TUI。这与 Claude Code 的 print / agent 模式（claude -p "…"）天然契合，适合脚本、cron、GitHub Actions 等自动化场景。

# 一行搞定：全局基础预设 + 项目启动预设 + 非交互 prompt
ccsp -g my-gateway-api -p ci-minimal claude -p "运行测试套件并汇总失败原因"

# 预览即将启动的配置（全局两栏 + 启动层四栏）
ccsp -g my-gateway-api -p ci-minimal --dry-run

为什么现在值得重视： 自 2026 年 6 月 15 日起，Anthropic 将 Agent SDK / claude -p 的用量从订阅套餐的交互额度中分离。终端里的交互式 Claude Code 仍占用套餐额度；claude -p 改走独立的 Agent SDK 月度额度（Pro / Max / Team / Enterprise 可领取）。这意味着非交互自动化有了更便宜的专用通道——前提是仍能按任务切换 API 后端，并按需开关 plugins / skills / MCP。

CCSP 的价值： 用全局预设指向第三方 API（ANTHROPIC_BASE_URL、env 里的 Key、默认模型等），用启动预设只打开该任务需要的 plugins / skills / MCP。直接运行会合并两层配置，并把剩余 argv 交给 claude：

| 参数 | 简写 | 作用 | |------|------|------| | --global-preset | -g | 全局基础预设名（~/.ccsp/settings/） | | --project-preset | -p | 项目启动预设名，或 Detected 表示自动发现的基线 | | --dry-run | — | 打印解析后的全局 + 启动预览，不启动 claude |

说明：

至少提供 -g 或 -p 之一 才会进入直接运行；否则仍为交互式 TUI。
透传参数时，CCSP 的 flag 写在 claude 之前；claude 之后的 -p 是 Claude 的 prompt 参数，不是 CCSP 的项目预设。
仅 -p 时，全局基础回退到上次使用的预设或项目 settings 来源（与 project-manage 启动一致）。
仅 -g 时，启动层使用 Detected 基线（无需已保存的启动预设）。

工作原理

两层预设模型

| 层级 | 存储位置 | 作用 | |------|----------|------| | 全局基础预设（Base Preset） | ~/.ccsp/settings/*.json | 一份完整的 settings 快照（可从 user / project / project-local 或任意 JSON 导入） | | 项目启动预设（Launch Preset） | <项目>/.claude/.ccsp/launch-presets/*.json | 仅记录相对基础的差异：插件开关、Skill 覆盖、MCP 拒绝列表 |

启动时 CCSP 不会直接改写 ~/.claude/settings.json 或项目里的 .claude/settings.json，而是写入 临时合并文件（.claude/.ccsp/tmp/<timestamp>-settings.json），再执行：

claude --settings <临时文件> [你传入的其它参数]

ASCII 逻辑图

┌─────────────────────────────────────────────────────────────────────────┐
│                           用户执行 ccsp / ccsp claude                    │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ① 发现现有 Settings 来源（按存在性收集，非运行时合并）                         │
│    · .claude/settings.local.json  (project-local)                       │
│    · .claude/settings.json        (project)                             │
│    · ~/.claude/settings.json      (user)                                │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
         ~/.ccsp 中已有基础预设？                  尚无基础预设
                    │                                   │
                    ▼                                   ▼
    ┌───────────────────────────┐          使用空基础 {} 或
    │ TUI：选择全局基础预设       │          先 ccsp create 导入
    │ （记住每个 cwd 上次选择）   │
    └───────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ② 解析「有效基线」                                                          │
│    · 插件：user < project < project-local < 所选基础预设                   │
│    · Skill：扫描 ~/.claude/skills、项目 skills/commands、已启用插件缓存      │
│    · MCP：合并 .mcp.json、~/.claude.json、插件 manifest 等来源              │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ③ TUI：项目启动层（Launch Preset）                                         │
│    · 左：已有启动预设列表  右：插件 | Skill | MCP 三列开关                     │
│    · 可保存为新预设 / 覆盖当前预设 / 临时启动不保存                             │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ④ finalizeSettings(base, launch)                                        │
│    · 以基础预设为主拷贝全文                                                 │
│    · 去掉基础里的 enabledPlugins / skillOverrides / deniedMcpServers      │
│    · 再写入 launch 层的上述三个字段（若有）                                   │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ⑤ 写入 .claude/.ccsp/tmp/*.json（目录默认 gitignore，最多保留 50 份）        │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ⑥ spawn: claude --settings <tmp> [sanitized args]                       │
│    · 剥离用户传入的 --settings / --settings=...（由 ccsp 统一管理）          │
└─────────────────────────────────────────────────────────────────────────┘

针对 Claude Code Settings 的痛点

| 痛点 | 说明 | |------|------| | 多文件、多层作用域 | Claude Code 同时存在 user / project / project-local settings，手工维护时难以一眼看清「最终生效」的是哪一层。 | | 切换成本高 | 换 API、换模型、换插件组合往往要改 JSON 或记不同 --settings 路径。 | | 易误改主配置 | 直接编辑 ~/.claude/settings.json 容易把个人密钥、全局默认一起改掉。 | | 插件 / Skill / MCP 分散 | enabledPlugins、skillOverrides、deniedMcpServers 与 env 等字段混在同一文件，缺少面向「本次启动」的轻量视图。 | | 提交风险 | 项目 settings 若含 env 里的 Key，误提交到 Git 风险高。 |

CCSP 的优势

非破坏性启动：通过临时 settings 文件注入配置，不强制覆盖你的主 settings 文件。
两层分离：全局「基础环境」与项目「启动差异」解耦，适合多仓库并行开发。
可视化开关：在终端 TUI 中浏览 JSON、切换插件 / Skill / MCP，比手改数组更不易出错。
直接运行：-g / -p / --dry-run 供脚本与 CI 使用；配合 claude -p 做无头 agent 任务。
记忆上次选择：按项目目录记住上次使用的基础预设与启动预设。
可恢复会话：每次启动都会把会话与所用预设 / 启动配置绑定，ccsp --continue 与 ccsp --resume <id> 可一键恢复原配置并续上对应 Claude 会话。
安全默认值：.claude/.ccsp/ 初始化时写入 .gitignore（忽略全部），降低临时文件与本地预设误提交概率。

会话恢复（Session Resume）

Claude 退出后，CCSP 会主动发现 Claude 真实分配的 session id（启动前对 ~/.claude/projects/<编码后的 cwd>/ 做快照，退出时做 diff——--session-id 在交互模式下并不可靠，所以我们不直接 pin），并把它和本次启动配置绑定，存入 .claude/.ccsp/sessions.json（最多 50 条，按 lastUsedAt 淘汰）：

ccsp --resume <uuid>：用绑定里的输入重新 finalize 启动配置，并以 claude --resume <uuid> 一步启动。
ccsp --continue：选取本项目里最近退出的 ccsp 会话，按其 id 确定性地恢复。具体例子：先启 A 再启 B，先退出 A，再 ccsp --continue，恢复的是 A（带 A 当时的预设 / 启动配置），不是 B。
若绑定对应的 Claude 会话已不存在（如旧版本残留），CCSP 会丢弃该绑定并回退到交互式选择。

局限与误解澄清（请务必阅读）

| 不能做到 / 需注意 | 说明 | |-------------------|------| | 不是 Claude Code 替代品 | 仅包装 claude 子进程；未安装 CLI 时会报错退出。 | | 不自动回写主 settings | 不会把合并结果写回 ~/.claude/settings.json；若你希望永久生效，仍需自行同步或使用 ccsp create 更新基础预设。 | | 接管 --settings | 传入的 --settings 会被忽略并提示警告；路径由 CCSP 生成。 | | 启动层字段有限 | Launch Preset 只覆盖 enabledPlugins、skillOverrides、deniedMcpServers；其它字段（如 env）来自基础预设。 | | 不能通过 UI 新增 MCP Server | 仅支持基于已发现 MCP 的禁用（deniedMcpServers），不能创建新 server 配置。 | | create / manage 仍以 TUI 为主 | 创建与管理预设需交互界面；无头启动请用直接运行或自行编辑 JSON。 | | Derived 预设 | 数据模型支持 derived 类型，但当前 CLI 未暴露创建/管理衍生预设的完整流程。 | | 项目存储默认本地 | launch-presets、tmp 与 sessions.json 都在 .claude/.ccsp/ 下，默认不进 Git；团队共享需另行约定导出方式。 | | 临时文件有上限 | tmp 中的 settings 文件按 lastUsedAt 淘汰，最多保留 50 份；statusline 脚本每次退出都会清理。 | | Resume 只覆盖 ccsp 启动的会话 | ccsp --continue / --resume 只能看到通过新版 ccsp 启动并记录过绑定的会话；直接用 claude 启动的会话不在范围内。 |

命令参考

| 命令 | 说明 | |------|------| | ccsp | 默认流程：选基础预设 → 配置启动层 → 启动 claude | | ccsp -g <name> | 直接运行：仅指定全局基础预设（启动层 = Detected） | | ccsp -p <name> | 直接运行：仅指定项目启动预设（全局基础 = 上次使用或项目 settings） | | ccsp -g <global> -p <launch> | 直接运行：两层都指定，然后启动 claude | | ccsp … --dry-run | 配合 -g / -p：预览解析结果，不 spawn | | ccsp … claude [args…] | 直接或交互均可；CCSP 参数写在 claude 前，Claude 参数写在后 | | ccsp claude [args...] | 同上，并将 args 传给 claude（不含 --settings） | | ccsp --continue | 恢复本项目最近退出的 ccsp 会话，复用原始预设 / 启动配置 | | ccsp --resume <uuid> | 按 session id 精确恢复某个会话，复用启动时所用的预设 / 启动配置（未知绑定时回退到交互式选择） | | ccsp create | 交互式创建全局基础预设 | | ccsp manage | 管理全局基础预设（预览 / 重命名 / 删除 / 新建 / 启动） | | ccsp manage --project | 管理当前项目的启动预设 | | ccsp config | 配置 ccsp 偏好（仅 env 预览、statusline） |

常用快捷键（TUI）

选择基础预设： j/k 或方向键移动，f 在「仅 env」与「完整配置」预览间切换，Enter 确认，q 退出。

管理全局预设（ccsp manage）： l 启动，r 重命名，d 删除，c 新建，o 在 Finder 中打开文件，q 退出。

项目启动层： 在预设与插件 / Skill / MCP 列间切换并开关；支持保存为启动预设。终端内 Ctrl+L 可刷新界面。

配置（ccsp config）： j/k 或方向键移动，space/Enter 切换当前选项，q 退出。

偏好设置（`ccsp config`）

ccsp config 打开左右两栏视图（左侧为选项，右侧为当前聚焦选项的说明），用于管理存放在 ~/.ccsp/config.json 的全局（按用户）偏好。两项默认均为开启：

| 选项 | 默认 | 作用 | |------|------|------| | Global preset env-only | 开启 | 基础预设选择页默认只预览所选预设的 env 字段。在该页面按 f 可在「仅 env」与「完整配置」视图间切换；关闭后默认展示完整配置。 | | Show statusline | 开启 | 在 Claude Code 底部注入 ccsp statusline，显示当前预设与开关概览（CCSP: <base>/<launch> \| plugins(…) \| skills(…) \| MCPs(…)）。关闭后不再注入，也不会生成任何 statusline 脚本。 | | Settings preview format | yaml | 基础预设选择页（ccsp）与管理页（ccsp manage）右侧预览所选预设配置的渲染格式 —— yaml 或 json，两者都带语法高亮。 |

目录结构

~/.ccsp/
├── index.json                 # 全局基础预设索引
├── settings/
│   └── <name>-settings.json   # 基础预设内容
├── config.json                # 用户偏好（仅 env 预览、statusline）
└── last-settings.json         # 各项目 cwd 上次使用的基础预设名

<项目>/.claude/.ccsp/          # 默认整目录 gitignore
├── launch-presets/
│   ├── index.json
│   └── <name>-launch.json     # 仅含启动层覆盖字段
├── tmp/
│   └── <stem>-settings.json   # 本次启动的最终配置（最多 50 份，按使用时间淘汰）
├── sessions.json              # sessionId → 启动配置 的绑定，供 --continue / --resume
└── last-used.json             # 上次使用的启动预设

从源码开发

git clone https://github.com/lkangd/cc-settings-preset.git
cd cc-settings-preset
pnpm install
pnpm run dev          # 直接跑 tsx src/cli.ts
pnpm run check        # typecheck + build + test

贡献指南

欢迎 Issue 与 Pull Request。参与前建议：

先搜已有 Issue，避免重复讨论；新功能请先开 Issue 简述动机与用法。
本地验证： pnpm run check 须通过；若改动 CLI 行为，请补充或更新 tests/ 下对应用例。
风格： 与现有代码保持一致（ESM、strict TypeScript、Ink 组件 + flows/ 状态机）；避免无关重构。
范围控制： CCSP 聚焦 settings 预设与启动编排，不引入与 Claude Code 无关的重依赖。
文档： 用户可见行为变更请同步更新 README.md 与 README.zh-hans.md。
提交信息： 使用简洁英文或中文均可，说明「为什么」而不仅是「改了什么」。

报告 Bug 请附带： 操作系统、Node 版本、ccsp 调用方式、相关 ~/.ccsp 或 .claude/.ccsp 结构（请打码密钥）、终端报错全文。