Claude Code配置文件管理

ccprofile

配置文件管理器 Claude 代码 --切换技能组、子代理、斜线命令、插件和MCP服务器，以优化您的上下文窗口。

的问题

Claude代码加载 全部 将技能、代理、斜线命令、插件和MCP服务器定义注册到系统提示中。安装了30多种技能后，即使当前任务不需要大多数功能，也会浪费数千个令牌。

解决方案

ccprofile 允许您定义命名配置文件，将技能、代理、命令、插件和MCP服务器分组。用一个命令在它们之间切换，只在上下文窗口中保留您需要的内容，或者将配置文件绑定到目录并让 ccprofile auto 为你切换。

安装

npm install -g ccprofile
ccprofile init

这 init 命令：

• 验证是否安装了Claude代码
• 创造 ~/.claude/profiles/ 和 ~/.claude/skills-disabled/ 目录
• 安装同伴技能(/profile-edit)用于人工智能辅助的个人资料编辑
• 扫描您当前的技能和插件，并建议配置文件分组

快速开始

# See how many tokens each installed skill costs you
ccprofile stats

# Capture your current setup so you can always get back to it
ccprofile snapshot baseline

# Create a profile for document work
ccprofile create docs "Document processing"

# Add skills that should stay active when this profile is used
ccprofile add docs skill pdf
ccprofile add docs skill docx
ccprofile add docs skill xlsx

# Agents and slash commands work the same way
ccprofile add docs agent doc-reviewer
ccprofile add docs command summarize

# Disable plugins you don't need for doc work
ccprofile add docs plugin "frontend-design@claude-plugins-official" --disable

# Preview exactly what would change — no writes
ccprofile use docs --dry-run

# Activate the profile (moves unused skills to ~/.claude/skills-disabled/)
ccprofile use docs

# Check what's active and how many tokens you're saving
ccprofile current

# Go back to your original state (restores skills, plugins, AND MCP servers)
ccprofile reset

命令

所有读取命令均接受 --json 用于脚本编写。 use 和 reset 接受 --dry-run 无需编写任何内容即可预览更改。

衡量代币节省

ccprofile的全部目的是缩小系统提示，这样它就可以向您显示 这到底要花多少钱。Claude Code加载每个技能/代理/命令的元数据 （姓名+描述）在每次转弯时都会显示在系统提示中，直到实际 调用。 ccprofile stats 估算每个项目的经常性闲置成本以及如何估算 每个配置文件都节省了很多：

$ ccprofile stats
Idle token cost per item (loaded into the system prompt every turn):

  [on]    180 tok  skill    playwright-cli
  [on]     95 tok  skill    pdf
  [on]     60 tok  agent    code-reviewer
  [on]     22 tok  command  deploy
  [off]     0 tok  skill    ccprofile   # non-auto-invocable → ~0 idle cost

  Total if all enabled: ~620 tokens
  Currently active:     ~275 tokens

Estimated savings per profile (vs. everything enabled):

  docs             active ~190 tok, saves ~430 tok

估计对每个项目的前体使用~4个字符/令牌启发式，以及 标记的项目 disable-model-invocation: true 被计为~0，因为它们是 未自动加载。

每个项目自动切换

将配置文件绑定到目录，ccprofile将从任何地方获取它 在那棵树里面：

ccprofile bind docs ~/work/docs-repo
cd ~/work/docs-repo/src
ccprofile auto          # activates "docs" (re-syncs if drifted, no-op if in sync)

auto 将插件/MCP更改应用于 全球 ~/.claude/settings.json 只有；它没有 --project 模式。如果需要更改项目级设置， 显式激活 ccprofile use <profile> --project.

要使其自动运行，请在每个会话之前运行它，例如从shell别名运行：

alias cc='ccprofile auto && claude'

或克劳德密码 SessionStart 钩住 ~/.claude/settings.json （注意 技能在会话开始时加载，因此由钩子触发的切换需要 对 下一个 会话）：

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "ccprofile auto" }] }
    ]
  }
}

绑定存储在 ~/.claude/profiles/.bindings.json.

配置文件架构

配置文件是JSON文件，具有 version 字段（当前 2).对于 skills, agents，以及 commands 列表：

• 缺钥匙 --在应用配置文件时，保持该类型不受影响；
• 空列表 [] --禁用此类所有内容（受保护的除外 同伴技能等项目）；
• 非空列表 --保持这些项目处于活动状态。

v0.4.0之前编写的旧配置文件（否 version 字段）已使用 [] 意味着 “未触碰”；它们在负载时是标准化的，因此它们的行为不会改变。

共享个人资料

配置文件是纯JSON格式，因此您可以对其进行版本控制或与团队共享：

ccprofile export docs > docs-profile.json     # or: ccprofile export docs docs-profile.json
ccprofile import docs-profile.json            # validates shape; --force to overwrite
curl -s https://example.com/team-docs.json | ccprofile import -

运作原理

激活是 声明式：所需的环境计算如下 你的 原始基线与轮廓重叠，所以你得到的是纯净的 这两件事的作用——从来没有哪个配置文件碰巧是活动的 在两者之间。当你奔跑时 ccprofile use <name>:

1. 技能：个人资料中列出的技能将保留 ~/.claude/skills/。所有其他移动到 ~/.claude/skills-disabled/.同伴 ccprofile 技能总是保持活跃，所以 /profile-edit 永远不会消失。
2. 代理和斜线命令：使用相同的保留列表机制 ~/.claude/agents[-disabled]/ 和 ~/.claude/commands[-disabled]/.一个配置文件 不 某一种类的清单未涉及该种类；一 空的 列表([])禁用此类所有内容（受保护的项目除外）。
3. 插件：集合 enabledPlugins 臀部向内倾斜 ~/.claude/settings.json 与覆盖有配置文件切换的基线值相比。从配置文件A切换到配置文件B 恢复A的切换 --它们不会积累。
4. MCP服务器：与的覆盖语义相同 enabledMcpjsonServers / disabledMcpjsonServers.

首次从干净状态激活配置文件时，ccprofile会记录 基线快照 您的技能、代理、命令、插件和MCP 中的设置 ~/.claude/profiles/.baseline.json. ccprofile reset 恢复 基线，触摸 只有它记录的：你安装的技能或 您启用的插件 而 基线未知配置文件是否处于活动状态，以及 与您设置的完全相同。直接在配置文件之间切换可以保留 原始基线。

基线捕获 一 设置文件--全局 ~/.claude/settings.json 或单个项目的 .claude/settings.json （参见 --project 在......下面保持 reset 能够完全撤消一切，ccprofile 拒绝 在以下情况下针对不同的设置目标激活配置文件 另一个仍然处于活动状态（例如，全局激活，而 --project 一个是活的）。跑 ccprofile reset 首先，然后切换目标。

配置文件存储为JSON文件 ~/.claude/profiles/.

项目级别

使用 --project 将设置更改（插件、MCP服务器）应用于 当前项目 .claude/settings.json 而不是全球性的：

ccprofile use docs --project

技能、代理和斜线命令始终存在 ~/.claude/ 并且被切换 全球不管 --project. --project 由支持 use; auto 始终以全局设置文件为目标。在切换之前先重置 项目目标和全球目标（见上文）。

同伴技能

运行后 ccprofile init一 /profile-edit slash命令在Claude Code中可用。它是 非自动发票 （空闲时令牌成本为零），仅在您显式键入时激活 /profile-edit。当您需要AI帮助以交互方式配置配置文件时，请使用它。

重要说明

• 更改需要重新启动Claude Code。 技能和插件在会话开始时加载，而不是在会话中期加载。
• 备份：修改前 settings.json，会自动创建带时间戳的备份（保留最近的5个）。
• 安全写入：使用原子文件写入，激活通过锁文件序列化(~/.claude/profiles/.lock)所以a SessionStart 手动指令不能交错文件移动。从崩溃的运行中损坏的锁会自动回收。
• 非破坏性: ccprofile reset 恢复首次激活前捕获的基线——技能、插件切换和MCP服务器列表都会恢复到原始状态，而您安装或切换的任何内容 之后 激活是不受影响的。基线跟踪单个设置文件，因此针对不同的目标（全局与全局）进行激活。 --project)当配置文件处于活动状态时，将被拒绝，直到您 reset.
• 健康检查: ccprofile doctor 验证目录、设置文件、配置文件、绑定、基线/标记一致性和锁定状态，并标记活动和禁用目录中存在的项。

在Claude Code内部使用

由于这是一个CLI工具，您可以直接从Claude Code会话运行它，而无需使用AI令牌：

! ccprofile use docs

为什么不是AI技能？

关键在于 保存令牌通过人工智能运行配置文件管理将违背目的。该工具完全在您的shell中运行-零API调用，零令牌消耗。

可选 /profile-edit 伴侣技能仅适用于需要人工智能帮助编辑个人资料的情况。使用 disable-model-invocation: true，因此，在您明确调用它之前，它的成本为零。

警告/兼容性

• 与Claude Code内部相结合。 ccprofile依赖于以下约定 克劳德代码没有正式记录：主动技能/代理/命令 住在 ~/.claude/{skills,agents,commands}/ 并通过移动它们而被禁用 给兄弟姐妹 *-disabled/ 目录，以及插件和MCP服务器 切换通过 enabledPlugins, enabledMcpjsonServers，以及 disabledMcpjsonServers 钥匙在 settings.json.如果克劳德代码更新 更改这些文件的加载或存储方式后，ccprofile可以自动停止任何 直到更新到匹配为止。它与Anthropic无关。
• 令牌估计值是近似值。 ccprofile stats 估算闲置成本 从一 ~4 chars/token 对每个项目的正面名称进行启发式 描述（包括YAML块标量，如 description: >).上下文 由插件和MCP服务器提供 不 算起来了——确实如此 通常是最大的份额，因为MCP工具模式仅在运行时已知。 将这些数字视为决定禁用什么的相对指导，而不是 对上下文窗口的精确统计。
• 更改将应用于下一次会话。 技能和插件加载在 会话启动，因此任何切换只有在您重新启动Claude Code后才生效。 这也意味着由以下因素触发的开关 SessionStart 钩子总是一个 会议落后。

许可证

麻省理工学院