Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/remorses/kimaki/llms.txt

Use this file to discover all available pages before exploring further.

Kimaki can be triggered programmatically from CI pipelines, cron jobs, or any automation. The send command creates a Discord thread, and the running bot on your machine picks it up.

​
Getting Started

​
Environment Variables

For CI automation, you need to set the Discord bot token as an environment variable:
VariableRequiredDescription
KIMAKI_BOT_TOKENYes (in CI)Discord bot token
Store your bot token as a secret in your CI environment. Never commit it to your repository.

​
CLI Send Command

The send command is the main way to start sessions programmatically: 
npx -y kimaki send \
  --channel <channel-id>  # Required: Discord channel ID
  --prompt <prompt>       # Required: Message content
  --name <name>           # Optional: Thread name (defaults to prompt preview)
  --app-id <app-id>       # Optional: Bot application ID for validation
  --notify-only           # Optional: Create notification thread without starting AI session
  --worktree <name>       # Optional: Create git worktree for isolated session
  --thread <thread-id>    # Optional: Send prompt to existing thread (no new thread)
  --session <session-id>  # Optional: Resolve thread from session and send prompt
Use either --channel/--project (create new thread) or --thread/--session (send to existing thread), not both.

​
GitHub Actions Integration

​
Example: Investigate New Issues

This workflow starts a Kimaki session whenever a new issue is opened: 
# .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 send \
            --channel "1234567890123456789" \
            --prompt "Investigate issue ${{ github.event.issue.html_url }} using gh cli. Try fixing it in a new worktree ./${{ github.event.issue.number }}" \
            --name "Issue #${{ github.event.issue.number }}"
Setup:
1

Add bot token to secrets

Add KIMAKI_BOT_TOKEN to your repository secrets (Settings → Secrets → Actions)
2

Get your channel ID

Replace 1234567890123456789 with your Discord channel ID (right-click channel → Copy Channel ID)
3

Ensure bot is running

Make sure the Kimaki bot is running on your machine

​
How It Works

1

CI runs send command

Creates a Discord thread with your prompt
2

Running bot detects thread

Automatically starts a session
3

Bot starts OpenCode session

Uses the prompt from the thread
4

AI investigates

Runs on your machine with full codebase access

​
Notification-Only Mode

Use --notify-only for notifications that don’t need immediate AI response (e.g., subscription events). Reply to the thread later to start a session with the notification as context. 
- name: Notify subscription event
  env:
    KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
  run: |
    npx -y kimaki send \
      --channel "1234567890123456789" \
      --prompt "User cancelled subscription: ${{ github.event.sender.login }}" \
      --notify-only

​
More GitHub Actions Examples

​
On Pull Request

name: Review Pull Requests

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: AI Code Review
        env:
          KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
        run: |
          npx -y kimaki send \
            --channel "1234567890123456789" \
            --prompt "Review PR ${{ github.event.pull_request.html_url }}. Check for security issues, code quality, and test coverage." \
            --name "PR #${{ github.event.pull_request.number }} Review"

​
On Failed Tests

name: Investigate Test Failures

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  investigate:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - name: Start Investigation
        env:
          KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
        run: |
          npx -y kimaki send \
            --channel "1234567890123456789" \
            --prompt "CI failed in run ${{ github.event.workflow_run.html_url }}. Investigate the failures and suggest fixes." \
            --name "CI Failure Investigation"

​
On Deployment

name: Post-Deployment Check

on:
  deployment_status:

jobs:
  check:
    if: ${{ github.event.deployment_status.state == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Verify Deployment
        env:
          KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
        run: |
          npx -y kimaki send \
            --channel "1234567890123456789" \
            --prompt "Deployment to ${{ github.event.deployment.environment }} completed. Run smoke tests and verify critical paths." \
            --name "Deployment Verification"

​
Scheduled Tasks

Add --send-at to any kimaki send command to schedule it for later. Supports one-time ISO dates (must be UTC ending with Z) and recurring cron expressions (runs in your local timezone): 
kimaki send --channel <channel-id> --prompt "Review open PRs" \
  --send-at "2026-03-01T09:00:00Z"
All other send flags (--notify-only, --worktree, --agent, --model, --user) work with --send-at. The only exception is --wait, which is incompatible since the task runs in the future. Manage scheduled tasks: 
# List all scheduled tasks
kimaki task list

# Delete a scheduled task
kimaki task delete <id>

​
Continuing Existing Sessions

You can continue an existing thread or session from CI: 
npx -y kimaki send --thread <thread-id> --prompt "follow-up prompt"
This is useful for multi-step workflows where one CI job creates a session and another follows up.

​
Adding Projects from CI

Create Discord channels for a project directory without starting a session. Useful for automation and scripting. 
# Add current directory as a project
npx -y kimaki project add

# Add a specific directory
npx -y kimaki project add /path/to/project

# Specify guild when bot is in multiple servers
npx -y kimaki project add ./myproject --guild 123456789

# In CI with env var for bot token
KIMAKI_BOT_TOKEN=xxx npx -y kimaki project add --app-id 987654321

​
Options

OptionDescription
[directory]Project directory path (defaults to current directory)
-g, --guild <guildId>Discord guild/server ID (auto-detects if bot is in only one server)
-a, --app-id <appId>Bot application ID (reads from database if available)

​
File Upload from CI

Upload files to a Discord thread from CI: 
npx -y kimaki upload-to-discord --session <session-id> <file1> [file2...]
This is useful for:
  • Uploading test results or coverage reports
  • Sending screenshots of UI changes
  • Providing log files for debugging

​
Best Practices for CI Integration

Set meaningful --name values so you can easily find sessions in Discord.
Reference issue numbers, PR links, commit SHAs, and other relevant context in your prompts.
Add --worktree <name> to create an isolated git worktree for experimental changes.
Ensure your Kimaki bot is running and accessible from CI. Consider using process managers like systemd or PM2.
CI workflows should continue even if the Kimaki command fails. Use || true or set continue-on-error: true in GitHub Actions.

Build docs developers (and LLMs) love

Get started for freeTalk to us