Troubleshooting

"command not found: contextkit"

Make sure you installed globally:

Or use npx: npx @nolrm/contextkit@latest install

"No ContextKit installation found"

You need to run ck install in your project directory first. Then you can add platform integrations.

Download failures during install

ContextKit downloads template files from GitHub. If you're behind a firewall or have network issues, try:

Hooks not running after cloning

For Node.js projects, run npm install — the prepare script sets up hooks automatically. For other projects:

Quality gates blocking push

To skip hooks for a single push:

To disable hooks permanently:

Legacy Husky conflicts

ContextKit automatically cleans up old Husky directories during install. If you still have issues, manually remove:

Cursor not reading rules

Make sure .cursor/rules/ exists. Run ck cursor to regenerate. Cursor reads .mdc files from this directory automatically.

Claude Code not loading standards automatically

ContextKit uses @path imports in CLAUDE.md to auto-load standards. If files aren't loading: (1) re-run ck claude to regenerate CLAUDE.md, (2) check that the first-time approval dialog was accepted (Claude Code prompts you to approve @imports on first use), (3) make sure the referenced .contextkit/standards/ files exist — run /analyze to generate them.

Slash commands not appearing in Claude Code

Run ck claude to install slash commands to .claude/commands/. Restart Claude Code to pick up the new commands. If commands are stale, run ck update to pull the latest versions.

Bridge file was overwritten

ContextKit uses marker comments (<!-- Generated by ContextKit -->) to manage its sections. If you have a custom CLAUDE.md or similar file, ContextKit appends below your content and only replaces its own marked section on updates.

Mixed state — both handoff.md and manifest.md exist

This happens when a single-task run and a batch run overlap in .contextkit/squad/. Run /squad-reset to clear the state, or if you're running /squad with a new task, it will offer to reset inline.

Squad pipeline stuck mid-run

Check the status: field in .contextkit/squad/handoff.md. Run the command that matches the current status — e.g. if status is dev, run /squad-dev. Use /squad-auto to continue automatically from where it left off.

Want to start over completely

Run /squad-reset to delete the entire .contextkit/squad/ folder. It will report what was removed before deleting. If you need to recover, check git history.