kbwo / ccmanager-config

Configuring CCManager

CCManager (ccmanager) is a terminal UI that runs one AI coding agent per git
worktree. Its behaviour comes from two JSON files with identical shape:

Per key, the project file wins over the global file. Both are optional.

The reason this skill exists: **CCManager reports nothing when a config is
wrong.** A file that is not valid JSON is discarded whole, and unknown keys are
ignored without a message, so a typo is indistinguishable from a feature that
does not work. Every change made through this skill therefore ends with the
validator run in step 4.

Procedure

1. Decide which file to edit

Ask yourself, and the user if it is genuinely ambiguous:

• Does the setting describe the repository (which agent CLI to run, what to
  do after a worktree is created, where worktrees live)? → .ccmanager.json,
  committed.

• Does it describe this person's machine or taste (notification commands,
  key bindings, personal API/model flags)? → the global config.json.

Two traps before you write anything:

• Put .ccmanager.json at the main repository root, not inside a linked
  worktree. CCManager resolves any worktree back to the main checkout, so a
  config file inside a worktree is never read.

• If ccmanager is started in multi-project mode (the
  CCMANAGER_MULTI_PROJECT_ROOT environment variable is set, or --multi-project
  is passed), project files are skipped entirely and only the global config
  applies. Say so rather than writing a file that will be ignored.

2. Read what is already there

cat the target file if it exists, plus the other file in the pair when the
user's request depends on the merged result. Never rewrite a config from
scratch when one exists — you would silently drop settings you were not asked
about.

3. Write the config

Look every key up in references/config-reference.md (in this skill
directory) before writing it: it lists each key with its type, its default, and
what it actually does. Do not invent keys — anything not listed there is
dropped by CCManager without a word.

For the common goals — running codex/gemini/another CLI, several presets,
desktop notifications, per-worktree setup commands, worktree path patterns,
merge arguments, auto-approval — start from a worked example in
references/recipes.md and adapt it.

Three rules that cause most of the breakage:

1. Merging happens one key deep. For each top-level key present in the
   project file, that key's fields override the global ones; anything nested
   below a field is replaced wholesale, not merged. In particular a project
   commandPresets.presets array replaces the global preset list entirely — so
   list every preset the repository needs, and give defaultPresetId the id of
   one of those presets.

2. args is argv, one array element per token. ["--model", "opus"], never
   ["--model opus"].

3. A hook without "enabled": true never runs. Both command and enabled
   are required.

4. Validate — always

node <skill-dir>/scripts/validate-ccmanager-config.mjs path/to/.ccmanager.json

It parses the file the way CCManager does, checks the shape against
schema/ccmanager.schema.json, flags unknown keys (with a "did you mean"), and
catches the mistakes JSON alone cannot express: a defaultPresetId matching no
preset, duplicate preset ids, an args entry with spaces in it, a detection
strategy that does not match the command, a shortcut that can never fire, a
disabled hook, a worktree pattern without {branch}, a config file sitting in a
linked worktree. It exits non-zero on errors; warnings are advisory.

Report what it printed. If you cannot run it (no Node available), say so
explicitly instead of claiming the config is fine.

5. Tell the user how to pick it up

CCManager reads config at start-up and when it reloads. After editing a file by
hand, they should return to the ccmanager menu or restart it; sessions already
running keep the command and detection strategy they were started with.

Reviewing an existing config ("this setting does nothing")

Work down this list — these are the silent failures, in the order they bite:

1. Run the validator (step 4). Invalid JSON and unknown/misspelled keys are the
   two most common causes and both are invisible in the TUI.

2. Check the file location: main repository root, not a worktree; and
   multi-project mode disabled.

3. Check the other file. The project file only overrides keys it actually
   contains; everything else still comes from the global config.

4. For presets: a defaultPresetId pointing at a preset that lives in the other
   file silently falls back to the first preset in the list.

5. For a session that reports the wrong status: detectionStrategy must match
   the CLI being run — see the table in references/config-reference.md.

Files in this skill

• references/config-reference.md — every key: type, default, behaviour, and
  the hook environment variables.

• references/recipes.md — copy-and-adapt configurations for the usual goals.

• schema/ccmanager.schema.json — JSON Schema for both config files; usable as
  $schema in an editor for completion.

• scripts/validate-ccmanager-config.mjs — the validator from step 4.