Minimal 24/7 AI assistant with pluggable channels.

graph LR
  M[Matrix] --> CM[channel-matrix]
  D[Discord] -.-> CD[channel-discord*]
  T[Telegram] -.-> CT[channel-telegram*]
  CM --> Core[core/engine]
  CD -.-> Core
  CT -.-> Core
  Core --> SDK[Claude Agent SDK]

Loading

*: Discord/Telegram is planned, but Matrix is functional.

Bare-bones setup

nix build && cd result/bin
kclaw config set matrix.homeserver https://matrix.org       # your matrix homeserver.
kclaw config set matrix.accessToken "syt_..."               # your access token. see troubleshooting for help.
kclaw config set matrix.allowedUsers '["@you:matrix.org"]'  # who should the bot respond to?
kclaw start

CLI Commands

In the spirit of minimalism, kclaw has just 3 CLI commands,

kclaw start                              Start the gateway
kclaw config set <key> <value>           Set a config value
kclaw config get <key>                   Get a config value

Config options include,

Key	Type	Example	Description
matrix.homeserver	string	https://matrix.org	Matrix server URL
matrix.accessToken	string	"syt_..."	Bot auth token
matrix.allowedUsers	string[]	'["@you:matrix.org"]'	Allowed Matrix user IDs
tools.cli	Record<string, string>	'{"gh":"GitHub CLI","jq":"JSON processor"}'	CLI tools the agent can use via Bash

Troubleshooting

M_UNKNOWN_TOKEN / "Token is not active" / How to obtain an access token Tokens from Element (mat_...) expire. Get a non-expiring token via the login API:

curl -s -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "identifier": { "type": "m.id.user", "user": "@YOUR_BOT:matrix.org" },
    "password": "YOUR_PASSWORD",
    "initial_device_display_name": "kclaw-bot"
  }' | jq .access_token

Note: user must be the full Matrix ID (e.g. @mybot:matrix.org), not just the username.

Then kclaw config set matrix.accessToken "<token>". Tokens prefixed mct_ do not expire.

M_LIMIT_EXCEEDED / "Too Many Requests" Progress edits hit Matrix rate limits. This is handled automatically with debounce + retry. If persistent, increase MIN_EDIT_INTERVAL_MS in packages/channel-matrix/src/progress.ts.

One time key already exists Stale crypto state. Delete ~/.config/kclaw/matrix-crypto/ and ~/.config/kclaw/matrix-store.json, then restart.

Bot not responding to messages

• Ensure the room is not encrypted (E2E not supported yet)
• Check the bot joined the room (invite it after starting kclaw start)
• Send a new message — old messages before startup are skipped
• Check tail -f ~/.config/kclaw/kclaw.log for errors

Kill a stuck query Send STOP in the Matrix room to abort the running Claude process.

Rotate password and access token

You can reset your bot's password via the Element web client. Log into your bot account. Then visit Settings > Account > Manage account > Account password.

Find your old token with kclaw config get matrix.accessToken.

Use the logout API to invalidate the old token:

curl -X POST "https://matrix.org/_matrix/client/v3/logout" \
  -H "Authorization: Bearer YOUR_OLD_TOKEN"

Then log in again to get a new one:

curl -X POST https://matrix.org/_matrix/client/v3/login \
    -H "Content-Type: application/json" \
    -d '{
      "type": "m.login.password",
      "identifier": { "type": "m.id.user", "user": "@YOUR_BOT:matrix.org" },
      "password": "YOUR_PASSWORD"
    }'

Update the config, kclaw config set matrix.accessToken "<new_token>".

Then delete ~/.config/kclaw/matrix-store.json.

Restart with kclaw start. The initial sync might fail with EPIPE: broken pipe, send if the sync state was refreshed. Just restart kclaw start and it should work.

Uninstall

To uninstall, it is sufficient to remove the binary, wherever you installed it, and supporting configuration files in ~/.config/kclaw.