Help us improve
Share bugs, ideas, or general feedback.
From darkroom
Syncs cc-settings with upstream Claude Code changelog (maintainer) or updates local cc-settings install (user).
npx claudepluginhub darkroomengineering/cc-settingsHow this skill is triggered — by the user, by Claude, or both
Slash command
/darkroom:ccThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Two-mode skill: **sync** keeps the cc-settings repo current with Claude Code upstream (maintainer task); **update** pulls the latest cc-settings into your local install (everyone).
Analyzes Claude Code setup including CLAUDE.md, commands, agents, skills, MCP, and CI/CD; evaluates mastery levels; researches latest trends; suggests prioritized upgrades.
Manages Claude Code settings including settings.json (user/project/enterprise), permissions, sandbox, plugins, env vars, and tools via docs-management delegation. For config setup and troubleshooting.
Guides users through configuring and optimizing Claude Code settings, workflows, and team rules across five learning levels.
Share bugs, ideas, or general feedback.
Two-mode skill: sync keeps the cc-settings repo current with Claude Code upstream (maintainer task); update pulls the latest cc-settings into your local install (everyone).
Audit cc-settings against Claude Code changelog; identify features to adopt and duplication to remove; stops for approval.
Track the official Claude Code changelog and keep cc-settings (schemas, config, hooks, agents, docs) in sync with new features. Removes anything that duplicates native functionality.
This is run on a weekly cadence. The mechanical parts are scripted; the judgment calls (which features to adopt, what counts as duplication) require human review at the gate.
Always run from the cc-settings repo root. If you're not there, ask the user
where it is — don't guess.
pwd # should end in /cc-settings
git status # tree must be clean before starting
If the tree is dirty, ask the user to commit or stash first. Sync work needs a clean baseline so the diff is reviewable.
bun run upstream:scan
This compares upstream/claude-code-manifest.json against the live
@anthropic-ai/claude-code npm version. Two outcomes:
manifest=A → live=B.Fetch the official changelog and extract entries between the manifest version (exclusive) and the live version (inclusive):
WebFetch url: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
prompt: Extract entries for versions <A+1> through <B> verbatim. List each
version's bullet points exactly as written.
Do not paraphrase. Quote the upstream bullets verbatim — the user needs to see exactly what was said upstream to validate your categorization.
For each upstream change, decide which bucket it falls into. Read these files to inform the decision (use parallel tool calls):
| Bucket | What to check |
|---|---|
| Settings keys | src/schemas/settings.ts (zod schema, strict — drift fails parse) |
| Hook events / types | src/schemas/hooks.ts (5-arm discriminated union as of v10.3.0) |
| MCP fields | src/schemas/mcp.ts (shared mcpCommon for cross-transport fields) |
| Env vars | upstream/claude-code-manifest.json knownEnvVars, docs/settings-reference.md env table, config/10-core.json env block |
| Hook wiring | config/40-hooks.json, src/hooks/, src/scripts/ |
| Statusline | src/hooks/statusline.ts (Payload type) |
| Agent frontmatter | agents/*.md (currently uses tools, disallowedTools, maxTurns, permissionMode, effort, isolation, hooks, mcpServers, initialPrompt) |
| Slash commands | MANUAL.md "All Skills" table, skills/*/SKILL.md triggers |
| User-facing docs | MANUAL.md, CLAUDE-FULL.md, docs/settings-reference.md, docs/hooks-reference.md |
Bucket each change as one of:
cc-settings has historically duplicated upstream work, then deleted it once the upstream version stabilized. Watch for these patterns:
Skill tool
replaced our skill-activation.ts in v10.1.0).Write a markdown table to the chat:
## v<A> → v<B> sync plan
### Adopt
| Change | Files | Notes |
|---|---|---|
| ... | ... | ... |
### Dedupe
| Native feature | What to remove | Why redundant |
|---|---|---|
### Docs-only
| Change | File |
|---|---|
### Skip
| Change | Reason |
|---|---|
Then ask the user one question: which rows do they approve?
Do not edit before approval.
For approved adoptions, edit the files directly. Schemas first (they're the contract), then config, then docs. For deduptions, delete the orphaned code and any tests that asserted on it.
After each schema edit, also update upstream/claude-code-manifest.json
(knownSettingsKeys, knownHookTypes, knownEnvVars) — the scanner uses
this as the source of truth.
upstream/claude-code-manifest.json
- claudeCodeVersion: "<B>"
- lastScan: <today ISO>
src/setup.ts
- VERSION: bump (minor for new features, patch for fixes-only)
CHANGELOG.md
- Prepend new section: "## [<new-version>] — <today YYYY-MM-DD>"
CHANGELOG entry structure (mirror prior entries — 10.1.0, 10.2.0, 10.2.1, 10.3.0 are good examples):
bun run typecheck
bun test
bun run upstream:scan # should now show "no drift detected"
bun run compose | head # spot-check that new fields surface in settings.json
If any fail: fix before moving on. Tests must pass.
git add -A
git commit -m "feat(v<new-version>): sync with Claude Code v<B>
<one-paragraph summary>
Adopted:
- ...
Deletions:
- ..."
git push origin main
Use conventional commit prefix feat(v<X.Y.Z>): so the version stands out in
git log. Do not push if anything in Phase 7 is failing.
~/.claude/settings.json. cc-settings is the
source — users get the changes by re-running setup.sh.bun run upstream:scan is the
manual drift detector; this skill is the only sync path.cc-settings exists in three time zones:
upstream/claude-code-manifest.json.Drift between (1) and (2) means the scanner is stale. Drift between (2) and (3) means our schemas accept things our installer never configures, or vice versa — usually fine, but worth flagging.
This mode aligns all three.
Pull the latest cc-settings into your local ~/.claude/ install.
The cc-settings working tree is usually at ~/.claude/cc-settings/. Some users (notably the original maintainers) keep it elsewhere — e.g. ~/Developer/.... Find it:
# Try the documented default first
[ -d "$HOME/.claude/cc-settings/.git" ] && CC_REPO="$HOME/.claude/cc-settings"
# If not there, the version sentinel doesn't record the path — ask the user
[ -z "$CC_REPO" ] && echo "Where is your cc-settings working tree? (path)"
Verify the path is a clone of darkroomengineering/cc-settings:
git -C "$CC_REPO" remote -v | grep -q 'darkroomengineering/cc-settings' || {
echo "Not a cc-settings clone"; exit 1;
}
# Installed version
INSTALLED=$(jq -r .version "$HOME/.claude/.cc-settings-version" 2>/dev/null)
# Latest version on remote main (read from src/setup.ts in origin/main)
git -C "$CC_REPO" fetch --quiet origin main
LATEST=$(git -C "$CC_REPO" show origin/main:src/setup.ts | grep -E '^const VERSION' | sed -E 's/.*"([0-9.]+)".*/\1/')
echo "Installed: $INSTALLED"
echo "Latest: $LATEST"
If equal: report "already up to date" and stop. If installed > latest: surface the discrepancy (manual edit?) and ask.
Show commits and the relevant CHANGELOG entries:
# Commits between the installed version and origin/main
# (find the tag/commit that bumped to $INSTALLED, then log from there)
git -C "$CC_REPO" log --oneline "HEAD..origin/main" | head -20
# CHANGELOG entries above the installed version
awk -v v="$INSTALLED" '
/^## \[/ { found = ($0 ~ "\\[" v "\\]") ? 1 : 0; if (found) exit }
!found { print }
' "$CC_REPO/CHANGELOG.md"
Display this block to the user. Stop. Wait for confirmation before applying. Don't auto-pull — give them the chance to read and bail.
# Hard-stop if the user has uncommitted edits on their cc-settings checkout —
# `git pull` will either merge or fail, both worse than asking.
if ! git -C "$CC_REPO" diff --quiet || ! git -C "$CC_REPO" diff --cached --quiet; then
echo "Local uncommitted changes in $CC_REPO:"
git -C "$CC_REPO" status --short
echo "Stash, commit, or discard before updating. Aborting."
exit 1
fi
# Hard-stop if they're not on main — they probably forked / are working on a feature
BRANCH=$(git -C "$CC_REPO" branch --show-current)
[ "$BRANCH" != "main" ] && {
echo "On branch '$BRANCH', not main. Switch first or update manually."
exit 1
}
git -C "$CC_REPO" pull --ff-only origin main
bash "$CC_REPO/setup.sh"
If the user has hand-edits to ~/.claude/settings.json (custom permissions, hooks, env), the installer preserves them automatically. Pass --interactive if they want to review each merge:
bash "$CC_REPO/setup.sh" --interactive
NEW=$(jq -r .version "$HOME/.claude/.cc-settings-version")
[ "$NEW" = "$LATEST" ] && echo "Updated to $LATEST" || echo "Sentinel still reports $NEW (expected $LATEST)"
Then tell the user:
Restart Claude Code to pick up the new agents/skills/hooks. New skills only auto-invoke after restart.
If the update introduced new MCP servers or env vars, mention those by name (read from the rendered CHANGELOG section in Phase 3).
cc-settings repo. Maintainer-facing sync work goes through sync mode.bun "$CC_REPO/src/setup.ts" --rollback to restore the most recent backup in ~/.claude/backups/.git -C "$CC_REPO" checkout <tag> first, then run bash setup.sh directly.