Troubleshooting

Most Kimaki issues are transient and caused by the underlying OpenCode server getting into a bad state. The single most effective fix is restarting the OpenCode server.

`/restart-opencode-server`

This is the first thing to try when something goes wrong. Run it in any channel or thread.

What it fixes:

Sessions not responding or stuck
New sessions failing to start
Auth state not refreshing after /login
Slash commands not appearing or missing new agents
Plugins not loading after config changes
OpenCode server crashes or hangs

What it does:

Aborts any in-progress sessions in the current channel
Restarts the shared OpenCode server process
Re-registers all Discord slash commands (built-in, user commands, agents)

Other channels reconnect automatically through the listener backoff loop once the server comes back up.

Note

This restarts the OpenCode server, not the Kimaki bot itself. Your bot stays connected to Discord the entire time. Only the backend that runs AI sessions is restarted.

`/upgrade-and-restart`

If /restart-opencode-server does not fix the issue, the problem is likely in Kimaki itself rather than the OpenCode server. Run /upgrade-and-restart to update Kimaki to the latest npm release and restart the bot process entirely. This replaces the running code with the newest version, fixing bugs in message handling, Discord event routing, session lifecycle, command registration, and anything else in the bot layer.

What it fixes (on top of /restart-opencode-server):

Bot crashes or unhandled exceptions
Discord event handling bugs (messages not being picked up, interactions failing)
Session lifecycle issues (threads not created, footers stuck, typing indicator stuck)
Command registration failures
Memory leaks or degraded performance over long runs
Any bug that was fixed in a newer Kimaki release

You can also upgrade from the terminal:

1kimaki upgrade

Common symptoms and fixes

Symptom	Fix
Session stuck, bot not responding	`/restart-opencode-server`
"Failed to create session" errors	`/restart-opencode-server`
Model change not taking effect	`/restart-opencode-server`
Missing slash commands after config change	`/restart-opencode-server`
Auth expired or provider errors after `/login`	`/restart-opencode-server`
Bot crashes or throws unhandled errors	`/upgrade-and-restart`
Threads not being created or messages ignored	`/upgrade-and-restart`
Typing indicator stuck, footers missing	`/upgrade-and-restart`
Issue persists after `/restart-opencode-server`	`/upgrade-and-restart`
Bot completely offline	Check the terminal where `kimaki` is running
Messages stop arriving when lid is closed	Disable sleep globally

MacBook sleeping with lid closed

If you run Kimaki on a MacBook and close the lid, macOS puts the machine to sleep by default. This means Discord messages stop arriving and sessions go unresponsive.

caffeinate only prevents idle sleep; it does not block the hardware sleep triggered by closing the lid.

Fix: disable sleep globally

1sudo pmset -a disablesleep 1

This prevents sleep entirely, including on lid close. To re-enable later:

1sudo pmset -a disablesleep 0

Fix: System Settings (power adapter only)

Go to System Settings > Battery > Options and enable "Prevent automatic sleeping on power adapter when the display is off". This only works when plugged in and may not be enough on its own for lid-close scenarios.

Fix: Amphetamine (GUI alternative)

Amphetamine is a free Mac App Store app with an explicit "Allow system sleep when display is closed" toggle. Disable that toggle to keep the Mac awake with the lid shut.

Warning

Running a MacBook with the lid closed traps heat. Keep it on a flat surface with good airflow; never put it in a bag while awake.

Debugging with logs

If the issue persists after a restart, check the log file:

12# default location
cat ~/.kimaki/kimaki.log

The log file is reset on every bot startup, so it only contains logs from the current run. Look for error lines near the bottom for the most recent failures.

Restarting the bot process

In rare cases where the bot itself is unresponsive (not just OpenCode), you can restart the entire process:

From the terminal:

12345# find the process
ps aux | grep kimaki

# send restart signal
kill -SIGUSR2 <PID>

The bot waits 1 second and restarts with the same arguments. Your Discord connection is briefly interrupted but reconnects automatically.