Promptkit

Promptkit writes image generation prompts for you. You give it a picture, and a vision model turns it into a ready-to-paste prompt for each image model you use: Stable Diffusion XL, Flux, Pony, or whatever else you add.

Why

I'm not good at writing image generation prompts. I know the picture I want, but a prompt that actually produces it has to name the subject, the lighting, the lens, the composition and the style, in terms the generator was trained on. Guessing at that yields mediocre images.

Starting from a reference picture is easier. So Promptkit takes a reference image and sends it to a vision-capable LLM along with the instructions for one of the image models you've added. The LLM describes what it sees, writes an analysis, and then writes a prompt for that image generation model. It repeats that for every enabled image model, so one upload gives you a set of prompts: tags for SDXL, a sentence for Flux, Danbooru tags for Pony.

During upload you can also give the LLM a note. If the reference picture features a red car, a note saying "car is green" will produce a prompt describing a green car.

From there you can edit and further refine the prompts the LLM wrote (the original is always kept).

Features

• Add images by upload, by URL, or from a watched Discord channel.
• Set up any number of image generators. Each one has its own instructions for how prompts should be written, editable in Settings.
• Generated text and your edits are stored separately, so an edit never loses the original.
• Auto-process can be switched on or off. On, images are processed as soon as they arrive. Off, they wait until you start the queue.
• A note attached to an image is taken into account on the next run.
• The system prompt used for image analysis is editable, as is the one used for chat.
• Chat against the same generators and save any reply into the library.
• Search the library by filename, image description or prompt text, and filter by generator or status.
• Works with any OpenAI-compatible vision model, self-hosted or cloud.

Running it

Everything runs in containers, storage included. You need Docker and an OpenAI-compatible endpoint serving a vision model: a local llama.cpp or Ollama server works, so does a hosted provider.

cp .env.example .env

Then edit .env:

• LLM_BASE_URL, LLM_API_KEY, LLM_MODEL are required. Nothing gets processed without them.
• Replace BETTER_AUTH_SECRET and INGEST_API_KEY. The values shipped in .env.example are public, so treat them as known. Generate new ones with openssl rand -base64 32.
• POSTGRES_PASSWORD and S3_SECRET_KEY are fine as they are while the stack stays on your machine. Change them if anything is reachable from elsewhere.
• BETTER_AUTH_URL has to match the URL you actually open in the browser. If you reach the app over your LAN, put that address here, not localhost, or sign-in will fail.
• Leave DATABASE_URL, REDIS_URL and S3_ENDPOINT commented out. Compose resolves those itself.

docker compose up -d --build

Open http://localhost:3000 and sign in as admin / changeme. Change the password in Settings.

Stable Diffusion XL, Flux and Pony are configured out of the box. Add or edit generators in Settings.

Everyday commands:

docker compose logs -f web worker    # follow the app
docker compose down                  # stop, keep data
docker compose down -v               # stop and wipe the volumes

Discord

Promptkit uses a bot, not a webhook. The bot watches one channel and sends new images to the app, so nothing has to be reachable from the internet and it works fine locally.

1. Create a bot in the Discord developer portal and turn on Message Content Intent.
2. Invite it to your server and set DISCORD_TOKEN and DISCORD_CHANNEL_ID in .env.
3. docker compose --profile discord up -d

Captions are optional. To attach a note to the image, start the caption with note:. Any other caption text is ignored.

Stack

• TypeScript, in a pnpm workspace with Turborepo
• Next.js 15 (App Router) and React 19, with Tailwind 4 and Radix
• Postgres, accessed through Prisma
• BullMQ on Redis for the processing queue, consumed by a standalone Node worker
• S3-compatible object storage, with MinIO in the default stack
• better-auth for username/password sign-in and sessions
• discord.js for the optional Discord bridge

Development

Backing services in Docker, the apps on the host so they hot-reload. Needs Node 24+ and pnpm 9, plus the same vision endpoint as above.

cp .env.example .env

Edit .env the same way as for Docker, with one addition specific to this mode: uncomment DATABASE_URL, REDIS_URL and S3_ENDPOINT. They point at localhost, which is how apps on the host reach the containers. In Docker mode they stay commented out, because Compose resolves the service names instead.

docker compose up -d postgres redis minio minio-init   # backing services only
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm db:seed                     # admin user, settings, 3 generators
ln -s ../../.env apps/web/.env   # next dev reads its own .env, not the root one
pnpm dev

Open http://localhost:3000 and sign in as admin / changeme.

The worker and bridge read the root .env directly, via --env-file-if-exists. next dev does not, which is what the symlink above is for.

pnpm dev --filter @promptkit/web    # one app at a time
pnpm lint
pnpm type-check                     # tsc --noEmit across the workspace
pnpm db:studio

To run the Discord bridge in this mode, set DISCORD_TOKEN and DISCORD_CHANNEL_ID, then docker compose --profile discord up -d discord-bridge.

By default images are streamed through the app, which works with a private bucket. To serve them straight from public storage, set S3_DELIVERY_MODE to presigned or public and set S3_PUBLIC_URL. Sign-in is still checked first.

Roadmap

Two features exist as schema and nothing else. See ROADMAP.md.

License

MIT.