Skip to main content

FOR EVERYONE

Multiple projects

If you work across several repos — a few clients, a couple of side projects, a monorepo — claude-kit fits that without anything bleeding together. The rule of thumb: one /kit-init per project.

Why per-project​

The kit deliberately sets up each project on its own, rather than once at a parent level:

  • It travels with the repo. A project's agents, skills, rules, and kit.config.json all live in its own .claude/. Commit that and the whole team shares the same setup — clone the repo elsewhere and it just works.
  • Clean memory. Each project maps to its own memory wing, so decisions and context never leak from one project into another. See Memory.

In a workspace or monorepo, run /kit-init inside each project rather than at the root. /kit-init notices whether you're in a single project or a folder of several and recommends accordingly.

Shared defaults across a folder​

Per-project doesn't mean repeating yourself. If one folder holds several projects and you want them to share a preference — the same language, the same plan format, the same annotation setup — drop a .claudekit/config.json into the parent folder.

It cascades to everything beneath it, the way .editorconfig does: the nearest folder wins, and its settings merge over each project's own config without trampling a project's specific choices.

clients/
  .claudekit/config.json     # shared defaults for everything below
  acme/
    .claude/                 # acme's own setup; inherits + can override
  globex/
    .claude/                 # globex's own setup; inherits + can override

So you set the shared bits once, and each project still gets the last word on its own specifics.

How it works under the hood
  • Project config. Each project's .claude/kit.config.json is the source of truth for that project, loaded by scripts via scripts/lib/kit-config.sh → load_kit_config, which flattens it into KIT_* environment variables.
  • The cascade. After loading the project config, load_kit_config walks ancestor directories for .claudekit/config.json files and deep-merges them over the project config (far → near, nearest wins) using jq '.[0] * .[1]'. It re-exports the fields that make sense at folder scope — KIT_LANG, KIT_PLANS_FORMAT, the KIT_ANNOTATE_* set — and exposes the fully merged result as KIT_EFFECTIVE_CONFIG.
  • No .claudekit/? No change. Projects without any ancestor .claudekit/ behave exactly as they did before — the cascade is purely additive.

Where to go next​