Troubleshooting
Common Issues
Kalami doesn't seem to be learning
Symptoms: Multiple sessions, but no new rules appear.
Causes and fixes:
- Too few messages: Kalami needs 10+ user messages per session to analyze. Quick Q&A sessions are skipped.
- No corrections: If you never correct Claude, there's nothing to learn. The highest-quality signal is you saying "no, do it this way."
- State file missing: Check if
.kalami/state.jsonexists. If not, reinstall:npx kalami --force
Hooks are not firing
Symptoms: No session banner, no report card at session end.
Causes and fixes:
- Hook files missing: Check
.claude/hooks/— should contain 6kalami-*.shfiles. Reinstall if missing:npx kalami --force - Settings not registered: Check
.claude/settings.jsonfor hook entries. Should havehooksobject withSessionStart,PreCompact,UserPromptSubmit,PostToolUse,PreToolUse, andStopentries. - Permission denied: Make hook scripts executable:
chmod +x .claude/hooks/kalami-*.sh
Rules not being delivered to Claude
Symptoms: Rules exist in npx kalami lessons but Claude ignores them.
Causes and fixes:
- Budget exceeded: Run
npx kalami context— if rules token usage is at 100%, lower-ranked rules are excluded. - Rules contradicted: Check if rules were marked as contradicted. Run
npx kalami lessonsto see only active rules. - Rule file empty: Check
.claude/rules/kalami-rules.md— this file is regenerated each session. If empty, the loop may have failed.
npx kalami install does nothing
Symptoms: Command runs but no files created.
Causes and fixes:
- Already installed: Kalami is idempotent. Use
npx kalami --forceto reinstall. - Not a git repo: Kalami requires git. Initialize with
git initfirst. - Wrong directory: Kalami installs in the current directory. Make sure you're in the project root.
CLAUDE.md conflicts
Symptoms: Your existing CLAUDE.md was changed unexpectedly.
Causes and fixes:
- Backup exists: Your original is saved at
.kalami/backup/CLAUDE.md. Restore it manually if needed. - Skip refactoring: Use
npx kalami --no-refactorto install hooks and rules without touching CLAUDE.md. - Preview first: Use
npx kalami --dry-runto see what would change before committing.
Verify chain blocks everything
Symptoms: Can't commit or push because verify chain keeps failing.
Causes and fixes:
- Tests actually failing: Fix the tests. The verify chain is doing its job.
- Wrong commands detected: Check
.kalami/config.json— theverifyobject shows which commands are being run. If they're wrong, fix them in config.json or reinstall with--force. - Slow tests: The verify chain runs all detected checks. If your test suite is slow, consider splitting into fast (pre-commit) and slow (pre-push) suites in your project config.
State corruption
Symptoms: npx kalami status shows errors or unexpected values.
Causes and fixes:
- Run doctor:
npx kalami doctor --fixauto-fixes common issues. - Reset state: Delete
.kalami/state.jsonand run a new session — it will be regenerated. - Full reset:
npx kalami --uninstallthennpx kalamito start fresh. Your learned rules in.kalami/index.mdare preserved across reinstalls.
Doctor Issue Types
npx kalami doctor detects 11 types of issues. Here's what each means and how to fix it:
| Issue | What it means | Severity | Auto-fixable |
|---|---|---|---|
| orphan | Files in .kalami/ that aren't referenced by any config | Low | Yes |
| conflict | Two rules that contradict each other | Medium | No |
| buried | .kalami/ directory is too deeply nested | Low | No |
| zombie | Session data from sessions that never completed | Low | No |
| stale | Rules with no recent activity (may be outdated) | Low | No |
| duplicate | Two identical rules | Low | No |
| permission-hole | Expected deny patterns are missing | High | Yes |
| bloated | CLAUDE.md exceeds 500 lines (warning) or 1000 lines (error) | Medium | No |
| overloaded | User instructions exceed 80 (recommended: 15-60) | Medium | No |
| scope-creep | A rules file starts with "You are" — belongs in .claude/agents/ instead | Medium | Yes |
| empty | .kalami/ directory exists but has no rules | High | Yes |
Auto-fixing
npx kalami doctor --fix
Fixes: orphan, permission-hole, scope-creep, empty. Other issues require manual intervention or are informational.
Health score
Doctor returns a score from 0 to 100. Above 80 is healthy. Below 60 means multiple issues need attention.
Getting Help
npx kalami debug # Print diagnostic info for bug reports
Include the debug output when reporting issues at github.com/0xmariowu/kalami/issues.