GH Agent Images Hoster

Upload immutable images for GitHub pull requests with agent attribution.

This app is built with:

• Next.js (web UI + API routes, Vercel-hosted)
• Convex (database + file storage)
• Clerk (authentication)

What it does

• Upload images from disk via CLI.
• Require an agentName for each upload.
• Return Markdown ready for PR comments/descriptions.
• Serve images publicly from non-guessable URLs (/i/<uuid>).
• Never replace images in-place (each upload is a new immutable record).
• Send long-lived cache headers (public, max-age=31536000, immutable).

Local Setup

1. Install dependencies:

   pnpm install

2. Configure environment variables (.env.local):

   NEXT_PUBLIC_CONVEX_URL= NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY= CLERK_SECRET_KEY= CLERK_JWT_ISSUER_DOMAIN=

3. Connect Convex once (interactive):

   pnpm exec convex dev

4. Start development servers:

   pnpm dev

Web UI

After sign-in, the home page provides:

• Uploaded image gallery with copyable Markdown snippets.
• CLI token management.
• A copyable setup command for CLI auth.

CLI

The CLI is now a dedicated package at packages/cli:

• Package name: @24letters/agent-images
• Binary name: agent-images

Install from npm (after publish):

pnpm add -g @24letters/agent-images

Run locally from this repo:

pnpm cli -- --help

One-time auth setup

agent-images auth login --api <service-origin> --token <cli-token> --agent <default-agent-name>

Example:

agent-images auth login --api https://gh-images.example.com --token ghimg_xxx --agent codex-agent

Upload command

agent-images upload <path-to-image> --agent <agent-name> [--alt "alt text"]

Example:

agent-images upload ./screenshots/ui.png --agent codex-agent --alt "New dashboard"

Output example:

![New dashboard](https://gh-images.example.com/i/6f0f2f3e-b9cc-4d8f-97d3-0c254e7fba4e)

Publish command from repo root:

pnpm publish:cli

Install skill via CLI

agent-images install-skill

This command delegates to skills.sh and installs gh-agent-images-upload from this GitHub repository.

Deployment

Clerk

• Create development and production Clerk applications.
• Enable a JWT template with application ID convex.

Convex

• Configure CLERK_JWT_ISSUER_DOMAIN in Convex deployment settings.

• Deploy backend:

  pnpm exec convex deploy

Vercel

• Create/import Vercel project.

• Add env vars from local setup section.

• Deploy:

  vercel --prod

Agent Skill

A reusable skill for other agents exists at:

• skills/gh-agent-images-upload/SKILL.md