Troubleshooting

Start with the status of the bot. It shows if the bot runs, if it is connected to OpenCode, and the Discord servers it sees.

1kimaki status

1234running: pid 4312, up 5400s, mode "gateway"
opencode: {"connected":true,"url":"http://127.0.0.1:4096","version":"2.0.19"}
guilds: [{"id":"123...","name":"My server"}]
data dir: "/Users/me/.kimaki"

If it prints not running, start the bot with kimaki in a terminal.

Ask AI about this page

Kimaki and OpenCode

Kimaki does not run its own OpenCode server. It uses your OpenCode 2 background service, the same one the OpenCode TUI uses. Sessions live in OpenCode, so they keep running when the bot restarts.

  Discord ──> kimaki bot ──HTTP + event stream──> OpenCode 2 service (shared with your TUI)

When no service runs, Kimaki starts one with opencode serve --service. It looks for the binary in this order:

OPENCODE_PATH, if set
opencode
~/.opencode/bin/opencode
opencode2, only if present (rare)

When no OpenCode is installed, Kimaki installs OpenCode 2 with the official script. In a terminal it asks first.

1curl -fsSL https://opencode.ai/v2/install | bash

Kimaki never replaces an existing OpenCode. If it finds OpenCode 1 or an OpenCode 2 that is too old, it stops and shows how to install or upgrade.

Common symptoms and fixes

Symptom	Fix
Bot completely offline	Run `kimaki status`. If it is not running, start `kimaki` and read the terminal output
`Kimaki now requires OpenCode 2` at start	Install OpenCode 2 with the command above, then run `kimaki` again
`OpenCode ... is older than the minimum`	Run `opencode upgrade`, then run `kimaki` again
`opencode` is not connected in `kimaki status`	Restart the OpenCode service
Session stuck, no reply	`/abort` in the thread, then send the message again
Plugins or config changes not loaded	`opencode reload`
Threads not created, messages ignored	Check that you can use Kimaki. See Access Control
Bot misbehaves after a long run	`kimaki restart`
`port is in use` at start	Another Kimaki runs. See Running multiple instances
Messages stop arriving when the lid is closed	Keep the Mac awake

Restart the OpenCode service

Use the OpenCode CLI. Kimaki reconnects by itself when the service comes back.

12opencode service status
opencode service restart

If opencode on your machine is still OpenCode 1, install OpenCode 2 with the command above.

A service restart also stops the sessions of your OpenCode TUI. opencode reload reloads the configuration without a restart, but it cancels pending questions and permission requests.

Restart the bot

1kimaki restart

The kimaki command supervises the bot process. kimaki restart stops the bot and starts it again with the code on disk. Sessions keep running in OpenCode, and the bot shows their output again after the restart.

This works only when the bot was started with the kimaki command.

Update Kimaki

Kimaki does not update itself. Install the new version, then restart the bot:

12npm i -g kimaki@latest
kimaki restart

kimaki restart starts the same script path again. If you started the bot with npx, stop it and run npx -y kimaki@latest instead.

MacBook sleeping with lid closed

If you run Kimaki on a MacBook and close the lid, macOS can put the machine to sleep. Then Discord messages stop arriving.

While the bot runs, Kimaki starts caffeinate -s. This keeps the Mac awake only on the power adapter. On battery, a closed lid still puts the Mac to sleep.

Fix: disable sleep globally

1sudo pmset -a disablesleep 1

This prevents sleep entirely, including on lid close. To enable sleep again:

1sudo pmset -a disablesleep 0

Fix: Amphetamine (GUI alternative)

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

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

12345# print the log file path
kimaki logs

# print the log and follow new lines
kimaki logs --follow

The log file is ~/.kimaki/kimaki.log by default, or <dataDir>/kimaki.log with --data-dir. It resets on every bot start, so it only has the current run. Look for error lines near the bottom.

To debug one session, print the events Kimaki recorded for its thread:

12kimaki session events <sessionId|threadId> > ./tmp/events.jsonl
jq -r .event.type ./tmp/events.jsonl | sort | uniq -c

To file a GitHub issue with session events, logs, and the model id, follow Debug sessions and report bugs.

CPU and heap profiles

To see where the running bot spends CPU time:

12345# record for 20 seconds (default), Ctrl+C stops early
kimaki profile cpu

# record for 1 minute
kimaki profile cpu --duration 1m

Kimaki writes a Chrome DevTools .cpuprofile file to <dataDir>/profiles/ and prints its path.

12# top functions by self-time
bunx profano ~/.kimaki/profiles/*.cpuprofile

For memory problems, write a heap snapshot. Open the printed .heapsnapshot file in Chrome DevTools, Memory tab.

1kimaki profile heap

Neither command restarts the bot.