ima2-gen 1.1.14 → 1.1.17

package/README.md

@@ -10,11 +10,13 @@
 
 > 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/)
 >
+> 📖 **Developer docs**: [Documentation site](https://lidge-jun.github.io/ima2-gen/docs) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/docs)
+>
 > **Read in other languages**: [한국어](docs/README.ko.md) · [日本語](docs/README.ja.md) · [简体中文](docs/README.zh-CN.md)
 
 `ima2-gen` is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
 
-Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation is also supported when configured.
+Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation and bundled Grok generation are also supported when configured.
 
 ![ima2-gen classic generation screen with prompt composer, generated image, compact model label, and result metadata.](assets/screenshots/classic-generate-light.png)
 
@@ -53,7 +55,7 @@ persists, reboot and run the update before starting ima2 again.
 - **Node mode**: branch a good image into multiple directions without losing the original.
 - **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
 - **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
-- **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions.
+- **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
 - **Reference images**: drag, drop, paste, and attach up to 5 references; large images are compressed before upload.
 - **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
 - **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
@@ -61,13 +63,17 @@ persists, reboot and run the update before starting ima2 again.
 
 ## Provider Paths
 
-Image generation can run through either the local Codex/ChatGPT OAuth path or a configured OpenAI API key.
+Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, or the bundled Grok provider.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
+- `provider: "grok"` starts bundled `progrok` on `127.0.0.1:18645`, runs mandatory xAI Web Search plus a `grok-4.3` planner pass, then calls xAI Images API through the local proxy.
 - API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
+- Grok generation supports Classic, Node, and Agent flows. If a Classic reference, Node parent image, or Agent current image is present, ima2 switches the final Grok call to xAI image edit so image-to-image context is preserved.
+
+If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options. Grok defaults to `grok-imagine-image`; `quality: "high"` promotes the final image call to `grok-imagine-image-quality`.
 
-If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options.
+Grok video generation (T2V/I2V) is not shipped in `1.1.15`. The video files in `docs/grok-video-i2v-plan.md` and `docs/grok-video-i2v-research.md` are implementation planning and research notes only; the published runtime remains image-only.
 
 ![Settings workspace showing OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
 
@@ -197,14 +203,22 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback image model |
+| `IMA2_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh` |
 | `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |
-| `IMA2_LOG_LEVEL` | `warn` | Normal serve defaults to `warn`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | Recent terminal job retention for debug views |
+| `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | Recent terminal job retention for debug views |
 | `OPENAI_API_KEY` | — | API key for the `provider: "api"` Responses API image path and auxiliary API-key features |
 | `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Default image model for `provider: "api"` |
 | `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |
 | `IMA2_API_ALLOW_WEB_SEARCH` | `true` | Toggle web search for `provider: "api"` |
+| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | Host for the bundled progrok proxy |
+| `IMA2_GROK_PROXY_PORT` | `18645` | Port for the bundled progrok proxy |
+| `IMA2_NO_GROK_PROXY` | — | Set `1` to disable automatic progrok startup |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model before the final Images API call |
+| `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` | Timeout for Grok search and planner calls |
+| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | Default final Grok image model |
+| `IMA2_GROK_GENERATION_TIMEOUT_MS` | `120000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
 
 ### Logging modes
@@ -219,6 +233,7 @@ The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay fo
 
 Useful references:
 
+- [Developer documentation site](https://lidge-jun.github.io/ima2-gen/docs) — Overview, Quickstart, Architecture, Modes, Providers, CLI, Config, and Server API
 - [CLI Reference](docs/CLI.md)
 - [API Reference](docs/API.md)
 - [Prompt Studio manual](docs/PROMPT_STUDIO.md)

package/bin/commands/capabilities.js

@@ -62,9 +62,14 @@ function printText(capabilities) {
     out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
     out(`  api model: ${capabilities.defaults?.api?.model}`);
     out(`  api reasoning: ${capabilities.defaults?.api?.reasoningEffort}`);
+    out(`  grok model: ${capabilities.defaults?.grok?.model}`);
+    out(`  grok planner: ${capabilities.defaults?.grok?.plannerModel}`);
     out("");
     out("valid:");
     out(`  models: ${capabilities.valid?.imageModels?.supported?.join(", ")}`);
+    if (capabilities.valid?.imageModels?.grokSupported?.length) {
+        out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
+    }
     out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
     out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
     out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/capabilities.ts

@@ -66,9 +66,14 @@ function printText(capabilities: any): void {
   out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
   out(`  api model: ${capabilities.defaults?.api?.model}`);
   out(`  api reasoning: ${capabilities.defaults?.api?.reasoningEffort}`);
+  out(`  grok model: ${capabilities.defaults?.grok?.model}`);
+  out(`  grok planner: ${capabilities.defaults?.grok?.plannerModel}`);
   out("");
   out("valid:");
   out(`  models: ${capabilities.valid?.imageModels?.supported?.join(", ")}`);
+  if (capabilities.valid?.imageModels?.grokSupported?.length) {
+    out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
+  }
   out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
   out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
   out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/doctor.js

@@ -30,7 +30,7 @@ function loadConfig() {
     return {};
 }
 function missingRuntimeDeps() {
-    const deps = ["express", "better-sqlite3", "openai", "openai-oauth"];
+    const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json"];
     return deps.filter((dep) => {
         try {
             requireFromRoot.resolve(dep);
@@ -39,7 +39,7 @@ function missingRuntimeDeps() {
         catch {
             return true;
         }
-    });
+    }).map((dep) => dep === "progrok/package.json" ? "progrok" : dep);
 }
 function valueAfter(args, name) {
     const index = args.indexOf(name);

package/bin/commands/doctor.ts

@@ -30,7 +30,7 @@ function loadConfig() {
 }
 
 function missingRuntimeDeps() {
-  const deps = ["express", "better-sqlite3", "openai", "openai-oauth"];
+  const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json"];
   return deps.filter((dep) => {
     try {
       requireFromRoot.resolve(dep);
@@ -38,7 +38,7 @@ function missingRuntimeDeps() {
     } catch {
       return true;
     }
-  });
+  }).map((dep) => dep === "progrok/package.json" ? "progrok" : dep);
 }
 
 function valueAfter(args: string[], name: string) {

package/bin/commands/edit.js

@@ -7,8 +7,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 const SPEC = {
     flags: {
         prompt: { short: "p", type: "string" },
@@ -40,8 +40,8 @@ const HELP = `
     -s, --size <WxH>
     -o, --out <file>
         --json
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled
@@ -64,10 +64,10 @@ export default async function editCmd(argv) {
     if (!VALID_MODERATION.has(String(args.moderation)))
         die(2, "--moderation must be one of: auto, low");
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
     }
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/edit.ts

@@ -8,8 +8,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 
 const SPEC = {
   flags: {
@@ -43,8 +43,8 @@ const HELP = `
     -s, --size <WxH>
     -o, --out <file>
         --json
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled
@@ -61,10 +61,10 @@ export default async function editCmd(argv: string[]) {
   if (!VALID_MODES.has(String(args.mode))) die(2, "--mode must be one of: auto, direct");
   if (!VALID_MODERATION.has(String(args.moderation))) die(2, "--moderation must be one of: auto, low");
   if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-    die(2, "--provider must be one of: auto, oauth, api");
+    die(2, "--provider must be one of: auto, oauth, api, grok");
   }
   if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
   }
   const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
   if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/gen.js

@@ -7,8 +7,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 const SPEC = {
     flags: {
         quality: { short: "q", type: "string", default: "low" },
@@ -51,8 +51,8 @@ const HELP = `
         --stdin                              Read prompt from stdin
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>         Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>    Provider for this request; grok uses progrok proxy
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled
@@ -88,10 +88,10 @@ export default async function genCmd(argv) {
     if (!VALID_MODERATION.has(String(args.moderation)))
         die(2, "--moderation must be one of: auto, low");
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
     }
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/gen.ts

@@ -8,8 +8,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 
 const SPEC = {
   flags: {
@@ -54,8 +54,8 @@ const HELP = `
         --stdin                              Read prompt from stdin
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>         Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>    Provider for this request; grok uses progrok proxy
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled
@@ -86,10 +86,10 @@ export default async function genCmd(argv: string[]) {
   if (!VALID_MODES.has(String(args.mode))) die(2, "--mode must be one of: auto, direct");
   if (!VALID_MODERATION.has(String(args.moderation))) die(2, "--moderation must be one of: auto, low");
   if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-    die(2, "--provider must be one of: auto, oauth, api");
+    die(2, "--provider must be one of: auto, oauth, api, grok");
   }
   if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
   }
   const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
   if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/grok.js

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { dirname, join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { color, die, out } from "../lib/output.js";
+import { isWin } from "../lib/platform.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+const HELP = `
+  ima2 grok <subcommand> [options]
+
+  Manage the bundled progrok runtime used by the Grok image provider.
+  No separate progrok install is required.
+
+  Subcommands:
+    login [--device-code]  Log in to xAI OAuth for the bundled proxy
+    logout                 Remove stored xAI credentials
+    status                 Show bundled progrok authentication status
+    models                 List available Grok models
+    proxy [options]        Start the bundled proxy directly
+
+  Notes:
+    ima2 serve auto-starts the bundled proxy on 127.0.0.1:18645 by default.
+    Use IMA2_NO_GROK_PROXY=1 to disable automatic proxy startup.
+`;
+function localBinPath() {
+    return join(ROOT, "node_modules", ".bin");
+}
+function spawnProgrok(argv, env) {
+    return new Promise((resolve, reject) => {
+        const progrokBin = join(localBinPath(), isWin ? "progrok.cmd" : "progrok");
+        const child = isWin
+            ? spawn(progrokBin, argv, {
+                cwd: ROOT,
+                env,
+                stdio: "inherit",
+                shell: true,
+                windowsHide: true,
+            })
+            : spawn(progrokBin, argv, {
+                cwd: ROOT,
+                env,
+                stdio: "inherit",
+                windowsHide: true,
+            });
+        child.on("error", (err) => reject(err));
+        child.on("close", resolve);
+    });
+}
+export default async function grokCmd(argv) {
+    const sub = argv[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        out(HELP);
+        return;
+    }
+    const env = {
+        ...process.env,
+        PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
+    };
+    try {
+        const code = await spawnProgrok(argv, env);
+        if (code && code !== 0) {
+            // Auto-fallback: if login (without --device-code) failed, retry with device-code
+            if (sub === "login" && !argv.includes("--device-code")) {
+                out(color.yellow("⚠ ") + "Browser login failed. Retrying with device-code flow...\n");
+                const fallbackCode = await spawnProgrok(["login", "--device-code"], env);
+                if (fallbackCode && fallbackCode !== 0) {
+                    die(fallbackCode, "bundled progrok device-code login also failed");
+                }
+            }
+            else {
+                die(code, `bundled progrok exited with code ${code}`);
+            }
+        }
+    }
+    catch (err) {
+        die(1, `bundled progrok failed to start: ${err.message}`);
+    }
+    if (sub === "login") {
+        out(color.green("✓ ") + "Grok OAuth is ready for ima2 serve");
+    }
+}

package/bin/commands/grok.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+import { dirname, join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { color, die, out } from "../lib/output.js";
+import { isWin } from "../lib/platform.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+const HELP = `
+  ima2 grok <subcommand> [options]
+
+  Manage the bundled progrok runtime used by the Grok image provider.
+  No separate progrok install is required.
+
+  Subcommands:
+    login [--device-code]  Log in to xAI OAuth for the bundled proxy
+    logout                 Remove stored xAI credentials
+    status                 Show bundled progrok authentication status
+    models                 List available Grok models
+    proxy [options]        Start the bundled proxy directly
+
+  Notes:
+    ima2 serve auto-starts the bundled proxy on 127.0.0.1:18645 by default.
+    Use IMA2_NO_GROK_PROXY=1 to disable automatic proxy startup.
+`;
+
+function localBinPath() {
+  return join(ROOT, "node_modules", ".bin");
+}
+
+function spawnProgrok(argv: string[], env: NodeJS.ProcessEnv): Promise<number | null> {
+  return new Promise((resolve, reject) => {
+    const progrokBin = join(localBinPath(), isWin ? "progrok.cmd" : "progrok");
+    const child = isWin
+      ? spawn(progrokBin, argv, {
+          cwd: ROOT,
+          env,
+          stdio: "inherit",
+          shell: true,
+          windowsHide: true,
+        })
+      : spawn(progrokBin, argv, {
+          cwd: ROOT,
+          env,
+          stdio: "inherit",
+          windowsHide: true,
+        });
+    child.on("error", (err) => reject(err));
+    child.on("close", resolve);
+  });
+}
+
+export default async function grokCmd(argv: string[]) {
+  const sub = argv[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    out(HELP);
+    return;
+  }
+
+  const env = {
+    ...process.env,
+    PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
+  };
+
+  try {
+    const code = await spawnProgrok(argv, env);
+    if (code && code !== 0) {
+      // Auto-fallback: if login (without --device-code) failed, retry with device-code
+      if (sub === "login" && !argv.includes("--device-code")) {
+        out(color.yellow("⚠ ") + "Browser login failed. Retrying with device-code flow...\n");
+        const fallbackCode = await spawnProgrok(["login", "--device-code"], env);
+        if (fallbackCode && fallbackCode !== 0) {
+          die(fallbackCode, "bundled progrok device-code login also failed");
+        }
+      } else {
+        die(code, `bundled progrok exited with code ${code}`);
+      }
+    }
+  } catch (err: any) {
+    die(1, `bundled progrok failed to start: ${err.message}`);
+  }
+
+  if (sub === "login") {
+    out(color.green("✓ ") + "Grok OAuth is ready for ima2 serve");
+  }
+}

package/bin/commands/multimode.js

@@ -41,7 +41,7 @@ const HELP = `
     -d, --out-dir <dir>                 Output dir for multiple images
         --json
         --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>     Provider for this request; api requires a configured API key
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>            Prompt handling mode. Default: auto
         --ref <file>                    Attach reference image (repeatable, max 5)
         --reasoning-effort <none|low|medium|high|xhigh>
@@ -60,11 +60,11 @@ export default async function multimodeCmd(argv) {
     const prompt = args.positional.join(" ");
     if (!prompt)
         die(2, "prompt required");
-    const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
+    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
     const VALID_MODES = new Set(["auto", "direct"]);
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (!VALID_MODES.has(String(args.mode)))
         die(2, "--mode must be one of: auto, direct");

package/bin/commands/multimode.ts

@@ -43,7 +43,7 @@ const HELP = `
     -d, --out-dir <dir>                 Output dir for multiple images
         --json
         --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>     Provider for this request; api requires a configured API key
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>            Prompt handling mode. Default: auto
         --ref <file>                    Attach reference image (repeatable, max 5)
         --reasoning-effort <none|low|medium|high|xhigh>
@@ -60,11 +60,11 @@ export default async function multimodeCmd(argv: string[]) {
   const prompt = args.positional.join(" ");
   if (!prompt) die(2, "prompt required");
 
-  const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
+  const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
   const VALID_MODES = new Set(["auto", "direct"]);
   const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
   if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-    die(2, "--provider must be one of: auto, oauth, api");
+    die(2, "--provider must be one of: auto, oauth, api, grok");
   }
   if (!VALID_MODES.has(String(args.mode))) die(2, "--mode must be one of: auto, direct");
   if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/node.js

@@ -8,11 +8,11 @@ const HELP = `
   ima2 node <subcommand> [options]
 
   Subcommands:
-    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api>] [--no-stream] [...gen-style flags]
+    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api|grok>] [--no-stream] [...gen-style flags]
     show <nodeId> [--json]
 
   Generate options:
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
 `;
 const GEN_FLAGS = {
     quality: { short: "q", type: "string", default: "low" },
@@ -58,10 +58,10 @@ async function generateSub(argv) {
     if (!prompt)
         die(2, "prompt required");
     const refs = (Array.isArray(args.ref) ? args.ref : []);
-    const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
+    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {
         die(2, "--reasoning-effort must be one of: none, low, medium, high, xhigh");

package/bin/commands/node.ts

@@ -9,11 +9,11 @@ const HELP = `
   ima2 node <subcommand> [options]
 
   Subcommands:
-    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api>] [--no-stream] [...gen-style flags]
+    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api|grok>] [--no-stream] [...gen-style flags]
     show <nodeId> [--json]
 
   Generate options:
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
 `;
 
 const GEN_FLAGS = {
@@ -54,10 +54,10 @@ async function generateSub(argv: string[]) {
   const prompt = args.positional.join(" ");
   if (!prompt) die(2, "prompt required");
   const refs = (Array.isArray(args.ref) ? args.ref : []) as string[];
-  const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
+  const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
   const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
   if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-    die(2, "--provider must be one of: auto, oauth, api");
+    die(2, "--provider must be one of: auto, oauth, api, grok");
   }
   if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {
     die(2, "--reasoning-effort must be one of: none, low, medium, high, xhigh");

package/bin/ima2.js

@@ -231,6 +231,7 @@ function showHelp() {
     billing        API usage / quota
     providers      Configured providers
     oauth <sub>    OAuth proxy status              (ima2 oauth --help)
+    grok <sub>     Bundled progrok login/status     (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)
@@ -270,7 +271,7 @@ if (args.includes("-v") || args.includes("--version")) {
     process.exit(0);
 }
 if ((!command || args.includes("-h") || args.includes("--help"))
-    && !["doctor", "gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
+    && !["doctor", "gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
     showHelp();
     process.exit(command ? 0 : 1);
 }
@@ -332,6 +333,7 @@ switch (command) {
     case "defaults":
     case "capabilities":
     case "skill":
+    case "grok":
     case "ping": {
         const { setCliVersion } = await import("./lib/client.js");
         setCliVersion(pkg.version);

package/bin/ima2.ts

@@ -252,6 +252,7 @@ function showHelp() {
     billing        API usage / quota
     providers      Configured providers
     oauth <sub>    OAuth proxy status              (ima2 oauth --help)
+    grok <sub>     Bundled progrok login/status     (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)
@@ -294,7 +295,7 @@ if (args.includes("-v") || args.includes("--version")) {
 }
 
 if ((!command || args.includes("-h") || args.includes("--help"))
-    && !["doctor", "gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
+    && !["doctor", "gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
   showHelp();
   process.exit(command ? 0 : 1);
 }
@@ -355,6 +356,7 @@ switch (command) {
   case "defaults":
   case "capabilities":
   case "skill":
+  case "grok":
   case "ping": {
     const { setCliVersion } = await import("./lib/client.js");
     setCliVersion(pkg.version);