Troubleshooting

Run belay 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:

belay setup

If you are using Claude Code and have the Belay Claude Code plugin installed, Belay 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:

belay setup

Or start it directly:

belay daemon status

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

Confirm your Node version is 20 or later:

node --version

If Node is too old, update it first, then reinstall:

npm install -g @oz-lunara/belay

If the belay 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 belay pending to see what is waiting. Then either approve it:

belay approve

Or reject it:

belay approve --decision reject

If you have multiple items pending, belay 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:

belay channels test

This sends a test message and confirms that Belay 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 Belay is running. Belay 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, Belay switches to out-of-band approval mode. In this mode, the local belay 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:

belay approval mode cli

Validate the configuration:

belay 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:

belay config rollback

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

Run the offline verification command:

belay 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.