Troubleshooting

Enable Debug Mode

Before investigating any issue, enable debug mode to see detailed hook output:

export CRAFTSMAN_DEBUG=1
claude

With debug mode on, every hook execution prints:

• Which rules were checked
• Which files triggered validation
• Severity decisions (block/warn/ignore)
• Execution time for each level

Disable with unset CRAFTSMAN_DEBUG.

---

Common Issues

Plugin not loading

Symptom: Hooks don’t run, no validation output.

Check:

/plugin
# "Installed" tab: the craftsman plugin should appear
# "Errors" tab: check here if skills do not appear

Fix:

claude plugin update craftsman@ai-craftsman-superpowers   # Force update

# If still not working, clear the cache and reinstall
rm -rf ~/.claude/plugins/cache/ai-craftsman-superpowers
claude plugin install craftsman@ai-craftsman-superpowers

# Restart Claude Code
exit
claude

---

“Config not found” error

Symptom: Error: ~/.claude/.craft-config.yml not found

Fix: Run the setup wizard:

/craftsman:setup

Or create a minimal config manually:

# ~/.claude/.craft-config.yml
version: "1.0"
packs:
  core: true

---

Rules not applying to my files

Symptom: PHP/TypeScript rules aren’t triggering.

Checks:

1. Verify your pack is enabled:

   # ~/.claude/.craft-config.yml
   packs:
     symfony: true   # For PHP rules
     react: true     # For TypeScript rules

2. Check for a .craft-rules.yml in the directory that disables the rule:

   find . -name ".craft-rules.yml" -exec cat {} \;

3. Verify the file extension is recognized:
   • PHP: .php
   • TypeScript: .ts, .tsx

---

Level 2 validation skipped (PHPStan/ESLint not running)

Symptom: Only Level 1 (regex) runs, no static analysis.

Check: Are the tools installed?

which phpstan  # Should return a path
which eslint   # Should return a path

Fix: Install the tools:

# PHPStan
composer global require phpstan/phpstan

# ESLint
npm install -g eslint

---

Hooks blocking valid code

Symptom: Your code is correct but a hook blocks it.

Options:

1. Inline disable (one line):

   // craftsman-ignore-next-line PHP001
   class LegacyAdapter implements ThirdPartyInterface {}

2. Directory disable (whole directory):

   # src/Legacy/.craft-rules.yml
   rules:
     php:
       final_classes: ignore

3. Project disable (whole project):

   # .craft-config.yml
   rules:
     php:
       final_classes: false

---

Agent hooks making sessions expensive

Symptom: Unexpected API costs from agent hooks.

Check: the metrics database holds no model, token or cost column, so the plugin cannot report your spend. Use Claude Code’s own command:

/usage

Options:

1. Disable agent hooks entirely (validation-only mode):

   agent_hooks:
     enabled: false

2. Keep validation but disable session-end agent:

   agent_hooks:
     enabled: true
     triggers:
       session_end: false  # Skip Final Reviewer

---

SQLite metrics database locked

Symptom: Error: database is locked in hook output.

Cause: Multiple concurrent Claude sessions writing to the same database.

Fix:

# Check for lingering locks
lsof ~/.claude/craftsman-metrics.db

# Force close if stuck
fuser -k ~/.claude/craftsman-metrics.db 2>/dev/null || true

---

Pack not loading

Symptom: Pack agents/commands not available after enabling in config.

Cause: pack symlinks are created by pack-loader.sh on SessionStart. If that hook did not run, the symlinks are missing.

Fix: restart the session so the loader runs again.

exit
claude

Check pack path for external packs:

packs:
  external:
    - path: "~/my-pack"  # Must be absolute or ~ path

ls ~/my-pack/pack.yml  # Must exist
claude plugin validate ~/my-pack  # Validate pack structure

---

FAQ

Q: Can I use the plugin without internet access?

Yes. All validation (Levels 1-3) runs locally. Agent hooks require Claude API access, but you can disable them with agent_hooks.enabled: false.

---

Q: Does the plugin work with monorepos?

Yes. Place .craft-config.yml at the monorepo root to apply rules globally. Use directory-level .craft-rules.yml files in each package for package-specific overrides.

---

Q: Can multiple team members use different configs?

Yes. The ~/.claude/.craft-config.yml is personal (not committed). The project .craft-config.yml is shared (committed). Team members can have different profiles in their global config while sharing the same project rules.

---

Q: How do I add Craftsman to an existing project without breaking CI?

Start with all rules as "warn" instead of true:

rules:
  php:
    final_classes: "warn"
    strict_types: "warn"

This lets you see violations without blocking anything. Gradually move rules to true as you fix existing violations.

---

Q: The correction rate in metrics is very low - is something wrong?

A low correction rate (below 40%) usually means:

1. Rules are triggering on code you intentionally write that way (consider "warn" severity)
2. Claude is fixing violations in a different session (corrections are session-scoped)
3. The SQLite file is being reset between sessions

---

Q: Can I export metrics to a team dashboard?

# Export to JSON
sqlite3 -json ~/.claude/craftsman-metrics.db \
  "SELECT * FROM violations ORDER BY timestamp DESC LIMIT 100" \
  > metrics-export.json

Then push to your preferred analytics tool.

---

Q: How do I update the plugin?

claude plugin update craftsman@ai-craftsman-superpowers

Then restart Claude Code (exit, then claude): the new version’s configuration is loaded on SessionStart.