Guide
Troubleshooting
Find your symptom, run its check, and apply the fix. Every check is read-only. Start with cumaru doctor when you are unsure.
A different cumaru runs, or brew upgrade seems to do nothing.
- Check:
type -a cumaru - Fix: Keep one installation first on PATH. Remove or reorder the older /usr/local/bin copy or development link yourself.
install, update, bootstrap, migrate, or help domains fails to read the domain.
- Check:
command -v curl, then retry with network access. - Fix: These commands read GitHub main and need cURL. Navigation commands work offline.
install refuses to start.
- Check:
ls -la .cumaru - Fix: Install refuses any existing .cumaru entry. Use cumaru update for an existing tree.
doctor stops before its checks.
- Check:
cumaru doctor - Fix: Fix the reported config, symlink, or workflow problem. A config version below 9 needs cumaru migrate.
doctor reports a configuration drift error for a newer reference version.
- Check:
cumaru version - Fix: Run cumaru upgrade, then cumaru migrate. The installed binary cannot migrate to a version it does not know.
doctor reports unbalanced tags.
- Check:
cumaru tag <file> - Fix: Close or remove the crossing or unclosed tag markers in the named file, then rerun doctor.
A file is missing from cumaru tree.
- Check:
cumaru tree <dir> --deep - Fix: Add a valid summary: (32 to 512 characters) or the missing index.md that --deep reports.
update refuses to apply.
- Check:
git status - Fix: Commit or stash pending changes. A config version boundary needs cumaru migrate.
The agent does not load Cumaru rules.
- Check:
grep -n 'cumaru hooks' .claude/settings.json (or .codex/hooks.json) - Fix: Reopen the agent session. If the entries are missing, run cumaru update agent <agent> --skills, then --apply.
context fails with a model error.
- Check:
cumaru model list - Fix: A damaged enabled package fails on purpose. Run cumaru model release to use the lightweight scorer, or pull again.
coverage fails immediately.
- Check:
git rev-parse --is-inside-work-tree - Fix: coverage needs a Git work tree and the configured specification pillar.
Sources: README, doctor, tree, update, context, coverage, agent adapters.