imagen/AGENTS.md

AGENTS.md

Bun + TypeScript single-file server that exposes an OpenAI-compatible image generation endpoint and serves a small vanilla HTML/JS playground.

Runtime

• Bun, not Node. See CLAUDE.md for the full Bun-vs-Node cheatsheet (prefer Bun.serve, Bun.file, bun:test, Bun.sql, etc.). Do not add dotenv — Bun loads .env automatically.
• Bun version baseline: 1.3.13 (per README.md).

Commands

• Install: bun install
• Dev (HMR): bun run dev → bun --hot ./index.ts
• Start: bun run start → bun ./index.ts
• Typecheck: no script defined. Use bunx tsc --noEmit (tsconfig already sets noEmit: true, so plain bunx tsc works too).
• Tests / lint / formatter: none configured. If adding tests, use bun test.

The server binds 0.0.0.0 (see index.ts:6), so it is reachable from other hosts on the network when running locally — be mindful when entering API keys.

Architecture

• index.ts — the entire backend. One Bun.serve instance with:
  • / serves index.html via Bun's HTML import (import index from "./index.html").
  • POST /api/generate accepts { baseURL, apiKey, model, prompt, size }, builds an OpenAI-compatible provider with @ai-sdk/openai-compatible, and calls generateImage from ai. Images come back as base64 and are returned as data: URLs in { images: string[] }.
• index.html — self-contained UI: inline CSS, plain DOM JS, no build step. Settings (baseURL, apiKey, model, size, prompt) persist in localStorage under the aip:<field> prefix. There is no React code despite react / react-dom / @types/react* being in package.json — treat those deps as latent. Do not invent a React frontend unless asked.
• No router, no DB, no auth. API key is supplied per-request by the browser and never stored server-side.

TypeScript conventions

tsconfig.json is strict with bundler-mode resolution:

• strict, noUncheckedIndexedAccess, noImplicitOverride, noFallthroughCasesInSwitch are on — array/object index access is T | undefined and must be narrowed.
• verbatimModuleSyntax + moduleDetection: "force" — use import type for type-only imports; every file is a module.
• allowImportingTsExtensions is on; .ts extensions in imports are fine.
• jsx: "react-jsx" is set but unused (see frontend note above).

When extending the API

• Add new routes inside the routes object in index.ts; keep the { POST: async (req) => … } shape used by /api/generate.
• Return JSON with Response.json(...). Validate the request body shape explicitly — the existing handler asserts required fields and returns 400 before calling the model.
• The AI SDK image type is loose; the current handler casts to { mediaType?: string; base64?: string }. Mirror that pattern rather than trusting field presence.