CI & Automation

Start a session from anywhere with one command. Only the bot token is needed; no Kimaki database, no local bot.

123KIMAKI_BOT_TOKEN='...' npx -y kimaki@latest send \
  --channel 1234567890123456789 \
  --prompt 'Run the test suite and fix the failures'

1{"threadId":"1398...","sessionId":"ses_..."}

The Kimaki bot that owns the channel must be running on its machine. It runs the prompt in a new thread and answers with the thread and session IDs.

Ask AI about this page

Getting your bot token

Print the token on the machine that runs the bot:

1kimaki bot token

Store it as a CI secret and pass it as KIMAKI_BOT_TOKEN. The value depends on the mode:

Mode	`KIMAKI_BOT_TOKEN` value
Gateway (`kimaki --gateway`, shared Kimaki bot)	`clientId:clientSecret` pair from onboarding, like `a1b2c3d4-...:7f8e9d...`. It is not a Discord bot token
Self-hosted (your own Discord app)	Your Discord bot token, from the Developer Portal under Bot > Token

kimaki bot token prints the correct value in both modes.

How it works

  CI runner                         Discord channel                    your machine
 ┌──────────────────────┐          ┌──────────────────────┐          ┌──────────────────────┐
 │ kimaki send          │──post───>│ envelope message     │──event──>│ kimaki bot (owner)   │
 │ (no local bot)       │          │ (as the bot user)    │          │ starts the session   │
 │ waits up to 20s      │<──read───│ reply with IDs       │<──reply──│ in a new thread      │
 └──────────────────────┘          └──────────────────────┘          └──────────────────────┘

CI runs send. No bot runs on the CI runner, so the CLI posts an envelope message in the channel with the bot token.
The owning bot reads it. Only the bot whose machine added that channel answers.
It starts the session in a new thread, on your machine with full codebase access.
It replies with the IDs. send prints {"threadId", "sessionId"} and exits.

If no bot answers in 20 seconds, send fails with No Kimaki bot answered this send. Start Kimaki on the machine that owns the channel.

On a machine where the bot runs, send talks to the local bot directly instead.

`kimaki send` options

1234567891011121314npx -y kimaki@latest send \
  --channel <channel-id>      # New thread in this channel
  --thread <thread-id>        # Or: continue this thread (ID or URL)
  --prompt <prompt>           # Required: the message
  --name <name>               # Thread name (default: prompt preview)
  --file <path>               # Attach a local file (repeatable)
  --agent <name>              # Agent for the session
  --model <provider/model>    # Model for the new session
  --user <id>                 # Add this Discord user to the thread
  --worktree [name]           # Run in a new Git worktree (automatic name when omitted)
  --base-branch <ref>         # Starting ref for --worktree
  --cwd <path>                # Existing project subfolder or linked worktree
  --permission <rule>         # Per-session permission rule (repeatable, see below)
  --notify-only               # Post a notification thread, no model turn

Use exactly one target: --channel or --thread.

These need a running bot on the same machine, so they do not work from CI:

Option	What it does
`--session <id>`	Continue a session by session ID
`--project <path>`	Pick the channel by project folder
`--wait`	Wait until the session is idle, then print it as markdown
`--send-at <when>`	Schedule the prompt (see below)

Use --notify-only for notifications that do not need an immediate AI response (for example subscription events). Reply in the thread later to start a session with the notification as context.

Example: GitHub Actions on new issues

This workflow starts a Kimaki session whenever a new issue is opened:

1234567891011121314151617181920# .github/workflows/investigate-issues.yml
name: Investigate New Issues

on:
  issues:
    types: [opened]

jobs:
  investigate:
    runs-on: ubuntu-latest
    steps:
      - name: Start Kimaki Session
        env:
          KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
        run: |
          npx -y kimaki@latest send \
            --channel '1234567890123456789' \
            --prompt 'Investigate issue ${{ github.event.issue.html_url }} using gh cli. Try to fix it.' \
            --name 'Issue #${{ github.event.issue.number }}' \
            --worktree 'issue-${{ github.event.issue.number }}'

Setup:

Add KIMAKI_BOT_TOKEN to your repository secrets (Settings > Secrets > Actions)
Replace 1234567890123456789 with your Discord channel ID (right-click channel > Copy Channel ID)
Keep the Kimaki bot running on the machine that owns the channel

Do not pass untrusted issue text directly in the prompt. Anyone who can open an issue can then write instructions for your agent. Pass the issue URL and let the agent read it.

Other commands that use the token

KIMAKI_BOT_TOKEN also works without a local bot for these commands, which call Discord directly:

12345# Discord users, for mentions
KIMAKI_BOT_TOKEN='...' npx -y kimaki@latest user list --guild <guild-id> --query tommy

# threads of a channel
KIMAKI_BOT_TOKEN='...' npx -y kimaki@latest thread list --channel <channel-id>

To add a project channel, run kimaki project add /path/to/project on the machine that holds the folder. It needs that machine's Kimaki data directory.

Routines

Add --send-at to a kimaki send command to run it later. Use a one-time UTC ISO date or a recurring cron expression (UTC). Run it on the machine where the bot runs:

1234# Recurring: every Monday at 9am UTC
kimaki send --channel <channel-id> \
  --prompt 'Run weekly test suite and summarize failures' \
  --send-at '0 9 * * 1'

For the full scheduling workflow, including --pre-run, kimaki routine list, and /routines, see Routines.

Per-session permissions

When you start a new session with kimaki send, you can restrict tools for that session with --permission. This is useful for CI pipelines, routines, and sandboxed sessions.

Format: tool:action or tool:pattern:action. Actions: allow, deny, ask. The tool names are OpenCode 2 permission names, for example shell and edit.

12345678# No shell commands and no file edits
kimaki send -c 123 -p 'Review this code' \
  --permission 'shell:deny' \
  --permission 'edit:deny'

# Ask before any rm command
kimaki send -c 123 -p 'Clean up the build folder' \
  --permission 'shell:rm *:ask'

--permission works only for new sessions. It does not work with --thread, --session, or --notify-only. It works with --send-at.