kokkify

Registry-driven cloud agent dispatch for GitHub issues. Repo-specific values (command file paths, prompt headers, assignee) come from environment variables — see src/config.ts. The supported flows and dispatchable statuses derive from the shared route matrix in @kokki/contracts/orchestration (DISPATCH_ROUTE_MATRIX) and are not env-configurable.

Kokki is the first consumer: .github/workflows/kokki-dispatch.yml runs bunx kokkify@<version> with repository secrets wired to the provider registry.

Install and run

Requires Bun >=1.1.0.

# CLI (GitHub Actions, local smoke)
bunx [email protected]

# Programmatic API
bun add [email protected]

import { runKokkifyDispatch } from "kokkify";

const { exitCode } = await runKokkifyDispatch({
  env: {
    GITHUB_REPOSITORY: "owner/repo",
    ISSUE_NUMBER: "42",
    GITHUB_TOKEN: "...",
    KOKKIFY_ASSIGNEE: "arjhun-personal",
    // provider secrets (CURSOR_API_KEY, KOKKI_*_ROUTINE_*)
  },
});

Required environment

| Variable | Purpose | |----------|---------| | GITHUB_REPOSITORY | owner/repo — derives command file prefix | | ISSUE_NUMBER | Issue to evaluate and maybe dispatch | | GITHUB_TOKEN | Issues write (comments, labels) + live issue fetch | | KOKKIFY_ASSIGNEE | Dispatch assignee login | | Provider secrets | Per src/registry.ts (CURSOR_API_KEY, KOKKI_*_ROUTINE_*, KOKKI_DISPATCH_URL) |

Supported flows and dispatchable status-* labels are not env vars — they derive from the shared route matrix in @kokki/contracts/orchestration (DISPATCH_ROUTE_MATRIX).

Providers

| Label | Provider id | Display name | Routes | Required env | |-------|-------------|--------------|--------|--------------| | agent-Cursor | cursor | Cursor Cloud Agent | plan, implementation | CURSOR_API_KEY | | agent-Claude | claude | Claude Code Routine | plan, implementation | KOKKI_{,BUG_,TECH_,CHORE_,PLAN_}ROUTINE_FIRE_{URL,TOKEN} | | agent-Kokki | kokki | Kokki Dispatch (Pi on E2B) | plan, implementation | KOKKI_DISPATCH_URL (OIDC token auto-injected by GitHub Actions when permissions: id-token: write is set on the workflow job) |

Releases (semantic-release)

Merges to main trigger .github/workflows/release.yml:

1. bun test + typecheck
2. semantic-release reads conventional commits since the last git tag
3. Publishes to npm and creates GitHub tag vX.Y.Z + Release

See CONTRIBUTING.md for commit message rules (fix: → patch, feat: → minor).

Secrets on this repo: NPM_TOKEN (granular, kokkify package, read-write, bypass 2FA). GITHUB_TOKEN is the default Actions token with contents: write.

Do not hand-bump package.json version on main; semantic-release owns it.

Consumer upgrades (Renovate)

Repos that pin bunx [email protected] should enable the Renovate GitHub App and add a renovate.json (see kokki). Patch bumps can automerge; minor/major need review + dispatch smoke test.

NPM_TOKEN setup (one-time)

npm no longer offers Classic tokens in the UI (granular only). Create the CI token from the CLI so --bypass-2fa and --packages-all are applied reliably — the web form often cannot select kokkify before it exists, and the bypass checkbox has been flaky.

1. Log in once (browser or CLI; you may need your 2FA app OTP this one time):

npm login

2. Create a granular publish token (read-write, bypass 2FA for automation).

If you have no packages on npm yet, --packages-all alone fails with:

You must have at least one package / scope or organization added to this token

Unscoped package kokkify: a token scoped only to @your-user cannot publish it (npm returns 403 even with bypass_2fa: true). Name the package explicitly:

npm token create \
  --name=github-actions-kokkify \
  --packages=kokkify \
  --packages-and-scopes-permission=read-write \
  --bypass-2fa

(kokkify does not need to exist on npm yet for this flag.)

If that fails with “must have at least one package / scope”, add your user scope as well:

npm token create \
  --name=github-actions-kokkify \
  --packages=kokkify \
  --scopes="$(npm whoami)" \
  --packages-and-scopes-permission=read-write \
  --bypass-2fa

npm prints the token once (starts with npm_). Copy it with no extra spaces or newlines.

3. GitHub secret — Arjhun-dev/kokki → Settings → Secrets → Actions → update NPM_TOKEN.

4. Sanity-check locally before re-running CI:

export NODE_AUTH_TOKEN='npm_...'
npm whoami
cd /path/to/kokkify && npm publish --access public --dry-run

whoami must succeed; dry-run must not prompt for OTP.

| Granular setting | First publish of kokkify | |------------------|---------------------------| | Packages | All packages (--packages-all) | | Permission | Read and write | | Bypass 2FA | --bypass-2fa on CLI (do not rely on UI alone) |

Write tokens are limited to a 90-day max lifetime on npm; renew NPM_TOKEN before expiry.

Development

bun test
bun run typecheck
npm pack --dry-run   # inspect tarball contents before publish