Skip to main content

Updating your AGENTS.md/CLAUDE.md

Add Imgwire guidance to AGENTS.md or CLAUDE.md when you want coding agents to make consistent choices around image uploads, generated assets, static content images, transformations, optimization, and CDN delivery in your project.

These files work best when they are concrete. Tell the agent when to use Imgwire, which SDKs belong in which runtime, where secrets are allowed, and what to do with local or AI-generated image assets.

Before you update agent instructions​

Complete the setup guide first so the project has an Imgwire account, organization, and Environment.

Then decide which agent tooling your team uses:

  • Install the Imgwire Agent Skill when you want Codex or Claude Code to understand Imgwire SDK selection, uploads, transformations, and image workflow rules.
  • Add the Imgwire MCP Server when agents should upload images, generate CDN URLs, inspect image records, or create publishable client tokens through OAuth-linked Imgwire access.
  • Install the Imgwire CLI when agents need repeatable terminal commands for local files, CI jobs, generated assets, or static-site workflows.

What to tell agents​

A good Imgwire instruction block should answer four questions:

  • When should Imgwire be used? Use it for user uploads, generated images, transformed image delivery, responsive image variants, CDN-hosted content images, and static assets that benefit from image management.
  • When should Imgwire not be used? Keep tiny bundled icons, favicons, framework-managed assets, and files that do not need Imgwire hosting or transformation inside the app bundle.
  • Which SDK or tool should be used? Frontend apps use client SDKs, backend apps use server SDKs, MCP is preferred for OAuth-linked agent workflows, and the CLI works well for shell or CI workflows.
  • Where can secrets live? Client Keys can ship to browser or mobile apps. Server API Keys must stay in trusted backend, local, or CI environments.

Base Imgwire instruction block​

Start with this block in AGENTS.md or CLAUDE.md, then add one of the repo-specific sections below.

## Imgwire

Use Imgwire for image uploads, generated images, transformed CDN URLs, responsive image variants, and static content images that benefit from hosting, optimization, reuse, or image management.

Prefer first-party Imgwire SDKs before hand-built HTTP calls or manual CDN URL string assembly:

- Browser JavaScript: `@imgwire/js`
- React: `@imgwire/react` plus `@imgwire/js`
- React Native or Expo: `@imgwire/react-native`
- Node.js backend: `@imgwire/node`
- Python backend: `imgwire`
- Ruby backend: `imgwire`
- Go backend: `github.com/Blackhawk-Software/imgwire-go`

Use Client Keys only in browser, mobile, and public client code. Keep Server API Keys in trusted backend, local, or CI environments only. Never put a Server API Key in frontend code, React Native bundles, public static output, or generated examples.

For frontend uploads that should depend on application authentication or permissions, add a backend upload-token endpoint that returns `{ "uploadToken": "..." }` and have the frontend request a token before uploading.

For generated images, docs screenshots, marketing images, or local static assets that should be delivered publicly, upload the image to Imgwire and use the returned CDN URL instead of committing large runtime images to the app. Prefer the Imgwire MCP server when available; otherwise use the Imgwire CLI.

Use presets such as `@thumbnail`, `@small`, `@medium`, and `@large` for common sizes. Use `format=auto` and `quality=auto` for most public image delivery unless the app has a specific output-format requirement.

Frontend app repo​

Use this section when the repository is primarily a browser, React, React Native, or Expo app.

## Imgwire frontend guidance

This is a frontend application. Use Imgwire for browser or mobile image uploads, transformed image rendering, responsive images, and user-facing static content images that should be served from the Imgwire CDN.

Use a publishable Client Key in the app's public environment variable system:

- Next.js: `NEXT_PUBLIC_...`
- Vite: `VITE_...`
- Expo: `EXPO_PUBLIC_...`

Do not add a Server API Key to this repository unless there is a trusted backend runtime in the same repo. Do not use `sk_...` keys in browser code, React Native bundles, static exports, or tests that snapshot public config.

For uploads:

- Use `@imgwire/js` for framework-neutral browser code.
- Use `@imgwire/react` plus `@imgwire/js` for React web apps.
- Use `@imgwire/react-native` for React Native or Expo apps.
- If unsigned uploads are enabled on the Client Key, keep upload limits and allowed image types aligned with the UI.
- If signed uploads are required, call the backend upload-token endpoint. Do not implement upload-token issuance in frontend-only code.

For rendering:

- Prefer Imgwire SDK URL helpers or React components over hand-built CDN URLs.
- Use responsive image patterns for layout-sensitive images.
- Use `format=auto`, `quality=auto`, and Imgwire presets for common display sizes.

For static app images:

- Upload documentation, marketing, generated, or large content images to Imgwire when they need CDN delivery or transformations.
- Keep tiny UI icons, favicons, and framework-managed assets in the app bundle when Imgwire would not add value.

Link the repo instructions to the Frontend Quickstart so future agents know where to verify setup details.

Backend app repo​

Use this section when the repository is a server, API, worker, job system, or backend service.

## Imgwire backend guidance

This is a backend application. Use Imgwire server SDKs for server-side uploads, upload-token issuance, remote URL ingestion, image management, metrics, CORS origins, custom domains, and transformed CDN URL generation.

Keep the Server API Key in a server-only environment variable such as `IMGWIRE_API_KEY`. Never return the Server API Key to clients, write it into frontend bundles, commit it to the repository, or paste it into examples.

Choose the SDK that matches the backend runtime:

- Node.js: `@imgwire/node`
- Python: `imgwire`
- Ruby: `imgwire`
- Go: `github.com/Blackhawk-Software/imgwire-go`

For server-side uploads:

- Upload files from trusted server storage when the backend already has the image bytes.
- Use URL uploads when an image already exists at a temporary or public asset URL, such as an AI image-generation result.
- Store the Imgwire image ID when future transformations, deletion, metadata lookup, or management may be needed.
- Return CDN URLs or image IDs to the frontend according to the app's data model.

For signed frontend uploads:

- Add an authenticated backend endpoint that creates an Imgwire upload token.
- Return `{ "uploadToken": "..." }` to the frontend.
- Validate the current user, permissions, upload purpose, and application-specific constraints before issuing a token.

For generated or static assets:

- Prefer Imgwire MCP tools for agent-driven uploads when available.
- Use `@imgwire/cli` in local scripts or CI jobs when MCP is not available.

Link the repo instructions to the Backend Quickstart and the Next.js upload token tutorial when the backend issues signed upload tokens.

Full-stack app repo​

Use this section when the repository contains both frontend and backend code.

## Imgwire full-stack guidance

This is a full-stack application. Split Imgwire responsibilities by runtime:

- Frontend code uses a publishable Client Key and Imgwire client SDKs.
- Backend code owns the Server API Key and issues upload tokens for signed uploads.
- Local, CI, and agent workflows may use the Imgwire MCP server or `@imgwire/cli` to upload generated/static assets and generate CDN URLs.

Authentication rules:

- Client Keys can be used in browser, mobile, and public client code.
- Server API Keys must stay in server-only environment variables.
- Frontend code must never import, receive, log, or render a Server API Key.

Upload flow:

- Use unsigned uploads only when the Client Key is intentionally configured for that flow and the dashboard limits match the UI.
- Use signed uploads when uploads should depend on app authentication, user permissions, or backend validation.
- For signed uploads, add a backend endpoint that returns `{ "uploadToken": "..." }` and configure the frontend uploader to call it.

Rendering flow:

- Use Imgwire SDK helpers or components to render transformed CDN URLs.
- Use presets such as `@thumbnail`, `@small`, `@medium`, and `@large` for standard sizes.
- Use `format=auto` and `quality=auto` for most public image delivery.
- Store image IDs in app data when future transformations or management are likely.

Static and generated assets:

- Use Imgwire for generated images, documentation images, marketing images, and content images that need CDN delivery or transformations.
- Keep tiny icons, favicons, and framework-managed assets in the bundle when they do not need Imgwire management.

Link full-stack repos to both the Frontend Quickstart and Backend Quickstart.

Add agent tooling notes​

If your project uses the Imgwire Agent Skill, MCP server, or CLI, make that visible in the instruction file so agents can use the right workflow.

## Imgwire agent tools

Use `$imgwire-skill` when changing Imgwire integration code, docs, upload flows, transformed URLs, or image rendering.

Prefer the Imgwire MCP server for agent-driven image workflows when it is available. Use MCP to upload generated images, upload local files through presigned URLs, import temporary image URLs, retrieve image records, create publishable client tokens, and generate transformed CDN URLs.

Use the Imgwire CLI for shell or CI workflows:

- `imgwire images upload ./hero.png`
- `imgwire images upload-via-url https://assets.example.com/generated.png --purpose "generated asset"`
- `imgwire images url img_123 --preset medium`
- `imgwire images create-upload-token`

Do not ask users to paste Server API Keys into chat. If a Server API Key is needed, ask the user to configure it in the backend, local shell, CI secret store, or CLI credential store.

Keep the instructions current​

Review AGENTS.md and CLAUDE.md whenever the image workflow changes. Update the file when you add a new upload flow, switch between signed and unsigned uploads, move from local assets to Imgwire CDN URLs, add MCP, add the CLI, or change which runtime owns the Server API Key.

Good instruction files should be short enough for agents to follow and specific enough to prevent unsafe defaults. Keep project-specific details, such as environment variable names and upload-token route paths, in the repo instruction file rather than relying on the agent to infer them.

Last updated at: May 9, 2026