Common questions about Claude Code Kit — installation, conflicts, multi-project use, customization boundaries.

Installation & setup

Will this conflict with my existing CLAUDE.md?

Yes — install.sh will warn before overwriting. Run with --upgrade if you want to merge with kit defaults preserving your changes, or back up your existing file first and pick what to keep.

If you want to keep your existing CLAUDE.md unchanged, install with --profile minimal which only adds hooks and .claude/settings.json.

Does the kit work with versions of Claude Code older than X?

The kit uses Claude Code's hook system and skill semantic matching. Both have been in Claude Code for several minor releases — anything from late 2025 onward should work. If doctor.sh runs cleanly, you're fine.

Can I install in a non-git directory?

Yes, but you'll lose the safety net of branch-protect.sh and conventional-commit.sh (they only fire on git operations). Everything else works.

How do I uninstall?

curl -fsSL https://raw.githubusercontent.com/tansuasici/claude-code-kit/main/uninstall.sh | bash

By default this removes everything kit-managed. Flags:

--keep-tasks — preserves tasks/lessons.md, tasks/decisions.md, tasks/handoff.md
--keep-project — preserves CLAUDE.project.md, agent_docs/project/, .claude/hooks/project/
--dry-run — show what would be removed without deleting

Day-to-day use

Will Claude really follow these rules?

Mostly yes, with caveats. Hooks are deterministic — exit code 2 blocks the action, the agent can't bypass them. Rules in CLAUDE.md are advisory — Claude reads them but compliance depends on the model and prompt context.

The kit's design is: deterministic for things that must happen (file protection, branch protection, dangerous commands), advisory for things that should happen (planning, scope discipline, verification).

What if I disagree with a kit default?

Override it in CLAUDE.project.md. The overlay always wins. See Customize CLAUDE.project.md.

If you think the default is wrong universally (not just for your project), open an issue — kit defaults aren't sacred.

Why are some hooks opt-in?

auto-format, auto-lint, skill-compliance, and skill-extract-reminder add latency to every edit. Some projects don't want that. The kit ships them disabled; you opt in via Enable Opt-In Hooks or --profile strict at install.

Does the kit work on Windows?

The hooks are bash scripts. If you have Git Bash, WSL, or any bash-compatible shell, they work. PowerShell-only setups won't run hooks (they'll silently skip). The advisory rules and skills work regardless of shell.

Compatibility

Does this work alongside Cursor / Copilot / Aider?

Yes — they read different config files. You can run all of them simultaneously.

For shared source of truth, generate cross-tool configs from the kit:

./scripts/convert.sh all

This produces .cursorrules, .windsurfrules, .aider.conf.yml, and AGENTS.md from your kit content. See Multi-project setup.

Can I use this without npx (offline / air-gapped)?

Yes. Manual install:

git clone --depth 1 https://github.com/tansuasici/claude-code-kit /tmp/cck
cp /tmp/cck/CLAUDE.md /tmp/cck/CODEBASE_MAP.md /tmp/cck/CLAUDE.project.md .
cp -r /tmp/cck/agent_docs /tmp/cck/tasks /tmp/cck/scripts /tmp/cck/.claude .
rm -rf /tmp/cck

You'll handle upgrades manually too.

Does it work with monorepos?

Yes, with one caveat: install at the repo root (where .git lives). The kit's hooks and CLAUDE.md apply across the entire repo. If you have very different stacks per package and want per-package rules, layer those into project-specific docs referenced by stack folder, e.g.:

## Stack-Specific Rules

- Frontend (`packages/web/`): Server Components first
- Backend (`packages/api/`): All routes use envelope pattern
- Mobile (`packages/mobile/`): React Native, never web-only APIs

Multi-project / scaling

Yes. Three options, in order of weight:

User-level — put rules in ~/.claude/CLAUDE.md, available across every project
Fork the kit — your org's defaults baked into your own CLAUDE.md
Manual copy — just cp between repos (works for small teams)

See Multi-project setup.

How do upgrades work?

npx @tansuasici/claude-code-kit init --upgrade

Touches only kit-managed files (listed in .kit-manifest). Your CLAUDE.project.md, agent_docs/project/, .claude/hooks/project/, and your custom skills are never touched.

What if a kit upgrade introduces a rule I don't like?

You can either:

Override in CLAUDE.project.md (overlay wins)
Skip that version: --upgrade --version v1.6.3
Pin a version: --version v1.6.3 on init

Or open an issue if you think the rule is wrong.

Skills & customization

When should I write a custom skill vs add to CLAUDE.project.md?

Need	Where
Single rule like "always X"	`CLAUDE.project.md`
Multi-step audit you'll re-run	Custom skill (`.claude/skills/<name>/SKILL.md`)
Reference doc the agent reads sometimes	`agent_docs/project/<topic>.md`
Deterministic enforcement (block an action)	`.claude/hooks/project/<name>.sh`

See Add a project-specific skill.

Will my custom skills survive `--upgrade`?

Yes. Only files listed in .kit-manifest are kit-managed. Your custom skills and project-specific files are untouched.

Open a PR adding it under .claude/skills/. The bar for upstream skills is "useful in 10+ projects" — too project-specific and it pollutes everyone else's kit.

Performance & cost

Won't all this context blow up my token budget?

The kit's tiered session boot loads context in three tiers, only loading deeper tiers when relevant. A typical session reads ~3-5 files at start, not 30. The lessons.md "Top Rules" section is just 15 lines for the always-loaded path.

You can measure with scripts/statusline.sh which shows context usage in real time.

Can I disable parts of the kit to save tokens?

Yes:

Delete agent_docs/ files you don't need (the kit only requires workflow.md and conventions.md)
Comment out hooks you don't want in .claude/settings.json
Use --profile minimal at install for hooks-only setup

Code review of human commits — that's a separate workflow, run separately.
Project management — tasks/todo.md is a session-scoped scratchpad, not Linear / Notion.
Knowledge management — see the optional Knowledge Wiki (--wiki flag) for that, based on Karpathy's pattern.
Runtime memory across sessions — the kit is statically defined; for runtime memory see Lemma, which complements the kit.

Why is this not on Anthropic's official recommendations?

It's a community project. Open-source, MIT-licensed, no affiliation with Anthropic.

Still stuck?

Open an issue with what you tried, what happened, and what you expected. Include ./scripts/doctor.sh output if relevant.

Edit this page on GitHub

FAQ