Documentation

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.