CI Automation

Automating Kimaki with GitHub Actions, CI pipelines, and scheduled tasks

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:

Variable	Required	Description
KIMAKI_BOT_TOKEN	Yes (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):

One-time

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:

By thread ID

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

Option	Description
[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

Use descriptive thread names

Set meaningful --name values so you can easily find sessions in Discord.

Include context in prompts

Reference issue numbers, PR links, commit SHAs, and other relevant context in your prompts.

Use worktrees for isolated changes

Add --worktree <name> to create an isolated git worktree for experimental changes.

Monitor bot availability

Ensure your Kimaki bot is running and accessible from CI. Consider using process managers like systemd or PM2.

Handle failures gracefully

CI workflows should continue even if the Kimaki command fails. Use || true or set continue-on-error: true in GitHub Actions.