# imagethis

[![CI](https://github.com/dbbuilder-org/imagethis/actions/workflows/ci.yml/badge.svg)](https://github.com/dbbuilder-org/imagethis/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

One-step AI **image generation** for Claude Code. Type `imagethis: <prompt>` and
it generates the image and loads it into the conversation — no clicks, no
back-and-forth. Ships as an **MCP server** (primary), a **CLI** (fallback), and a
**skill** (the `imagethis:` trigger), the same shape as
[pipethis](https://github.com/dbbuilder-org/pipethis).

Routes across backends by model, so one tool covers many providers:

| Model (`model`) | Backend | Best for |
|---|---|---|
| `flux-1.1-pro` *(default)* | Replicate | Photoreal, prompt adherence, in-image text |
| `flux-schnell` | Replicate | Fast / cheap drafts |
| `sdxl` | Replicate | Stylized art, LoRA/ControlNet breadth |
| `ideogram-v3` | Replicate | **Text in images** — logos, posters, signs |
| `recraft-v3` | Replicate | Brand art, vector-style |
| `gpt-image-2` | OpenAI | Reasoning, precise editing |

A backend activates only when its API key is set — you run just what you have.

---

## Quick start (one clone)

```bash
git clone https://github.com/dbbuilder-org/imagethis.git
cd imagethis

# pass whatever keys you have inline — they never touch the script or git
# macOS / Linux
REPLICATE_API_TOKEN=r8_... OPENAI_API_KEY=sk-... ./install.sh

# Windows (PowerShell)
$env:REPLICATE_API_TOKEN="r8_..."; $env:OPENAI_API_KEY="sk-..."
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

Then **restart Claude Code** and type:

```
imagethis: a golden retriever astronaut on the moon, cinematic lighting
```

**Keys:** `REPLICATE_API_TOKEN` (replicate.com — unlocks FLUX/SDXL/Ideogram/Recraft)
and/or `OPENAI_API_KEY` (unlocks `gpt-image-2`). At least one is required to
generate. **Prerequisites:** Node.js ≥ 18 and the `claude` CLI.

Verify: `claude mcp list` → `imagethis … ✔ Connected`.

---

## Usage

- `imagethis: <prompt>` — generate with the default model.
- Steer the model in plain language: *"imagethis: a poster that says GRAND OPENING"*
  → the skill picks `ideogram-v3` (best in-image text). Or pass it explicitly by
  asking for a model / aspect ratio.
- Directly: ask Claude to run **`generate_image`** `{ prompt, model?, aspectRatio? }`
  or **`list_image_models`** to see what's configured.

`aspectRatio`: `1:1` (default), `16:9`, `9:16`, `3:2`, `2:3`.

### CLI (fallback)

```bash
node cli.mjs --prompt "a neon jellyfish" --model flux-schnell --aspect 16:9
node cli.mjs --list            # show models + which backends are configured
```
Prints JSON with `images[].path` (saved PNGs) and `images[].url`.

## Not available yet: Meta Muse Image

Meta **Muse Image** (Superintelligence Labs, launched Jul 2026) is currently
**consumer-only with no developer API** — it can't be integrated here (or via
Glif, whose own API is deprecated). It's on the watch-list; when Meta ships an
API we add it to the registry as another `model`.

## Behavior

- Images are saved to `~/.imagethis/<timestamp>/` and returned as inline image
  blocks; Replicate results also include the source URL.
- Missing key → a plain-text `backend_not_configured` message (not an error);
  `list_image_models` shows what's usable.
- Provider content filters / errors surface as `api_error` with the provider's
  message.

## Uninstall

```bash
./uninstall.sh     # macOS / Linux
```
Windows: `claude mcp remove --scope user imagethis` and delete
`%USERPROFILE%\.claude\skills\imagethis`.

## Develop

```bash
node --test        # unit (mock fetch, no keys) + stdio MCP integration
```
One core (`lib.mjs`: model registry + `generateImage` routing); `server.mjs` and
`cli.mjs` are thin wrappers. `fetch` is injectable, so routing and request/response
handling are fully tested without hitting a paid API.