Troubleshooting

Run moona doctor. It checks which agent hook files are wired and flags any that are missing or misconfigured.

If your agent integration is missing, re-run setup:

moona setup

If you are using Claude Code and have the Moona Claude Code plugin installed, Moona uses the plugin path instead of writing to the settings file. Doctor will tell you if both paths are active (which would fire every decision twice — also a problem) and give you the exact fix.

Start the daemon by running setup:

moona setup

Or start it directly:

moona daemon status

If the daemon was previously running and stopped, re-running moona setup restarts it cleanly.

Confirm your Node version is 20 or later:

node --version

If Node is too old, update it first, then reinstall using the command from the Installation guide.

If the moona command is not found after a successful install, your npm global bin directory may not be in your shell's PATH. Check with npm bin -g and add that directory to your PATH.

Run moona pending to see what is waiting. Then either approve it:

moona approve

Or reject it:

moona approve --decision reject

If you have multiple items pending, moona approve will ask you to specify one using --id.

Held actions expire after a fixed window and are automatically denied — they never auto-approve. If the window has passed and your agent is still stuck, reject the expired item and retry the operation.

Run the channel health check:

moona channels test

This sends a test message and confirms that Moona can post to your channel and read replies. It reports the exact issue (e.g. an invalid bot token, a missing chat ID, or a permission problem) and tells you how to fix it.

Also confirm that your bot token environment variable is set in the shell where Moona is running. Moona stores the token as an environment variable reference — if the variable is not set, the channel cannot be used.

When Telegram (or another out-of-band channel) is configured, Moona switches to out-of-band approval mode. In this mode, the local moona approve command is disabled by policy — all approvals must come through the connected channel.

Open Telegram and reply to approve or deny the pending action there.

If you want to switch back to local approval mode, run:

moona approval mode cli

Validate the configuration:

moona config validate

This reports every schema issue with a location and description. Fix what is flagged.

If you need to restore the configuration to the state before your last edit:

moona config rollback

Moona backs up the configuration before every change made through its commands.

Run the offline verification command:

moona verify

This checks the integrity of every decision record in your audit log. It exits 0 if the log is intact, 1 if verification fails (with the specific failure), or 2 if the log cannot be read.