Get started with Ketoy

Install the CLI

The npm package is ketoy-dev (the bare ketoy name is blocked by npm's similarity heuristic). The installed binary is still ketoy.

$ npm i -g ketoy-dev
$ ketoy version

Requires Node.js 20 or newer. Every command runs in the current working directory - there's nothing global to maintain beyond the API-key store at ~/.ketoy-cli/.

Run ketoy init in your project

From the root of your Android project (the directory containing settings.gradle.kts and app/build.gradle.kts), run ketoy init. The CLI inspects your project, plans every change, and asks before applying.

$ ketoy init                        # interactive, asks before each edit
$ ketoy init -y                     # accept defaults, no prompts
$ ketoy init --dry-run              # show the plan, write nothing
$ ketoy init --hilt                 # opt into Hilt wiring
$ ketoy init --no-install-screen    # skip the MainActivity wrap

A typical interactive plan looks like this:

Detected: namespace=com.example.myapp, applicationId=com.example.myapp,
          minSdk=26, Hilt=no, Application=none, MainActivity=present

Plan (6 edits, 4 new files):
  edit  app/build.gradle.kts        + Ketoy plugin, dependencies, ketoy {} block
  edit  app/src/main/AndroidManifest.xml   + android:name=".MyApplication"
  edit  app/src/main/.../MainActivity.kt   wrap setContent { … } with KetoyScreen
  edit  gradle/libs.versions.toml          pin Kotlin 2.0.21, AGP 8.13.2, Compose BOM
  edit  .gitignore                         + **/keys/*-private.key
  new   app/src/main/.../MyApplication.kt
  new   app/src/main/.../ketoyscreens/HelloKetoyScreen.kt
  new   app/ketoy-capabilities.json
  new   .ketoy/state.json

Apply? [y/N]

What it does

1. Detects your namespace, applicationId, minSdk, Hilt usage, existing Application class, and existing MainActivity.
2. Pins versions in gradle/libs.versions.toml to the alpha-matched combination (Kotlin 2.0.21, AGP 8.13.2, Compose BOM 2024.10.00).
3. Edits app/build.gradle.kts - inserts the dev.ketoy.compiler plugin, appends the BOM + runtime + annotations + capabilities + Material3 adapters dependencies, and appends the ketoy { } configuration block.
4. Edits AndroidManifest.xml - sets android:name=".MyApplication" on <application> when no Application class exists.
5. Creates MyApplication.kt with the full bootstrap - KetoyConfig, CapabilityRegistry, KetoyRuntime, generated-adapter / constructor registration, KetoyBundleLoader.
6. Wraps MainActivity's setContent with CompositionLocalProvider(LocalKetoyRuntime, LocalKetoyBundleLoader) and a KetoyScreen entry point (use --no-install-screen to skip).
7. Creates HelloKetoyScreen.kt - a sample @KetoyEntryPoint @KetoyComposable to confirm the pipeline works.
8. Creates app/ketoy-capabilities.json (empty registry) and appends **/keys/*-private.key to .gitignore.
9. Saves project state to .ketoy/state.json so future commands know your layout.

Pick a model provider - optional

This step is skippable. If you don't connect an AI provider, ketoy init, build, and analyze still work - they're plain tooling. You just won't have access to the AI features: ketoy chat, ketoy migrate, and ketoy doctor all require a configured provider.

Ketoy is powered by the Vercel AI SDK, so you bring your own key from any major provider. Source code never leaves your machine except as part of the prompts you explicitly send to the provider you chose. No telemetry, no remote logging.

$ ketoy auth anthropic         # Anthropic Claude
$ ketoy auth openai            # OpenAI
$ ketoy auth google            # Google Gemini
$ ketoy auth mistral           # Mistral
$ ketoy auth groq              # Groq
$ ketoy auth xai               # xAI
$ ketoy auth openrouter        # 200+ models via one key
$ ketoy auth ollama            # local - no API key, just a base URL

$ ketoy auth --list            # see what's configured (redacted)

Then pin a default model (or override per-command with --model):

# Set a default model used by every command.
$ ketoy config set model anthropic:claude-sonnet-4-5
$ ketoy config set model openai:gpt-4o
$ ketoy config set model google:gemini-2.0-flash-exp
$ ketoy config set model openrouter:meta-llama/llama-3.1-405b-instruct

# Or override per-command.
$ ketoy chat --model anthropic:claude-sonnet-4-5

Build and run

After ketoy init finishes, the project is ready to build. The compiler plugin attaches to compileReleaseKotlin and emits a signed .ktx into app/src/main/assets/ketoy/main.ktx.

$ ketoy build

Launch the app - the KBC version of HelloKetoyScreen renders. Delete the .ktx, change the entry point to "DoesNotExist", or toggle airplane mode - the native fallback renders identically. That's the production contract.

What else the CLI does

Once initialized, the agent stays useful for the day-to-day work - writing screens, migrating existing Compose UI, diagnosing build failures, and inspecting bundles.

$ ketoy chat
> add a settings screen with a dark-mode switch and version row

$ ketoy chat "convert app/src/main/.../HomeScreen.kt to a KetoyComposable"

$ ketoy migrate app/src/main/.../HomeScreen.kt app/src/main/.../ProfileScreen.kt

$ ketoy doctor                # runs default build, diagnoses failures
$ ketoy doctor :app:ketoyBundle

$ ketoy analyze app/src/main/assets/ketoy/main.ktx --manifest --strings

Safety & privacy

The agent runs in your terminal, against your files, with your keys. The boring safety guarantees that make that workable:

• No file is rewritten in full. Edits to build.gradle.kts, AndroidManifest.xml, MainActivity.kt, and your Application class are surgical - single-line additions or block appends at well-identified anchors. Existing dependencies, signing configs, themes, and ProGuard rules are never touched.
• Diff-and-confirm on every edit touching a high-risk file. The agent's edit_file tool always shows a unified diff and prompts before applying.
• Idempotent. Re-running ketoy init on an already-configured project is a no-op.
• Allowlisted bash with hard refusal of compound commands for auto-approval. cat && rm -rf / looks like cat to a naive checker; the CLI refuses to auto-approve any command containing shell metacharacters (;, &&, ||, |, backticks, $(…), redirects).
• No telemetry. No analytics, no usage reporting, no remote logging. The CLI talks directly to the provider you configured.

What ships next - cloud delivery

What you just built is the local-asset path: the .ktx ships inside the APK at compile time, and updates roll out through the Play Store like any other asset.

Cloud delivery - pushing a new .ktx to a CDN where connected devices fetch updates at the next process start (Ed25519-verified, ETag-cached, rolled back on minAppVersion mismatch) - uses KetoyBundleSource.Remote(url). The wire format, signature verification, ETag cache, and runtime activation order are already implemented. The hosted infrastructure (signing pipeline, signed-URL distribution, telemetry) is under active development and ships shortly.