Idra Photo
by bbrainfuckk
README.md
# Idra Photo
**One entry point for art direction, image production and visual critique.**
Start with **`idra-photo`**. Give it a reference or a short brief; it prepares the job, brings in the relevant direction and critique, saves the images, and remembers where the batch stopped.
| Module | Its job | Availability |
|---|---|---|
| **[idra-photo](skills/idra-photo/SKILL.md)** | The production entry point: brief, reference roles, finite image jobs, saved outputs, consistency and continuation. | Included skill + local MCP. |
| **[idra-taste](https://github.com/bbrainfuckk/idra-taste)** | Art direction: connect the subject to a visual language, medium, movement, palette, type and composition. | Separate skill; Photo reads it when installed and the direction needs choosing. |
| **[idra-anti](skills/idra-photo/references/idra-anti.md)** | Visual critique: check hierarchy, identity and purposeful minute details, including construction, attachments, material behavior, spacing and relationships. | Bundled critique module; used before the creative prompt and when reviewing the result. |
**The workflow:** invoke `idra-photo` → apply `idra-taste` where needed and available → generate with the host's image tool → inspect with `idra-anti` → correct visible failures and deliver. You do not need three separate prompts. Accepted camera, cast, symbols and proportions remain constraints throughout.
The portable skill + MCP works with Codex and Claude Code. Start with “Use Idra Photo: make 2 skincare photos.” Codex can use its built-in image tool when available; Claude needs a connected image-generation tool. Idra coordinates and reviews the work. See [Claude setup](docs/claude.md) and [real results with rejected attempts](docs/results/README.md).
## Give your agent this repo
```text
Use https://github.com/bbrainfuckk/idra-photo for this task: <what I want>.
Read AGENTS.md first and follow the path for my request.
Set up only missing prerequisites. Use idra-photo as the entry point,
idra-taste for direction when available, and bundled idra-anti for critique.
Preserve my constraints and inspect the actual outputs before delivery.
```
**Agents start at [AGENTS.md](AGENTS.md).** It routes installation, image work, critique, batch continuation and repository development. The [production skill](skills/idra-photo/SKILL.md) contains the operating workflow. [CLAUDE.md](CLAUDE.md) imports the same entry point for Claude Code. A URL-reading agent can fetch those linked files; a local checkout supplies the tools and scripts.
## Install
Use a permanent checkout; the client will run the server from it. Reuse an existing checkout rather than cloning over it. From the chosen parent folder:
```sh
git clone https://github.com/bbrainfuckk/idra-photo.git
cd idra-photo
```
The server is prebuilt in `idra-photo.mjs`. **No `npm install` is needed to use it.** Node.js 22.13+ is required; the Windows launcher can also find Codex's bundled Node.
Choose the command for the actual client:
**Codex on Windows — PowerShell**
```powershell
.\idra-photo.cmd install-codex
.\idra-photo.cmd doctor
```
**Codex on macOS or Linux — terminal**
```sh
sh ./idra-photo.sh install-codex
sh ./idra-photo.sh doctor
```
**Claude Code — from this checkout, with your real design-project path**
```sh
node ./idra-photo.mjs install-claude --project "/absolute/path/to/design-project"
node ./idra-photo.mjs doctor
```
On Windows, the project path can be `"C:\Designs"`. Open Claude Code in that project. Use either the project installer or the [Claude plugin setup](docs/claude.md#claude-code-plugin); no need to install both.
The installers register the local `idra_photo` MCP and copy the `idra-photo` skill with its bundled `idra-anti` resource. They preserve other MCP settings and back up changed files. Images default to `Idra Photo/outputs/` in your home folder; `--workspace "<absolute folder>"` chooses another location. Pass the same `--workspace` to `doctor` when checking a custom location. `idra-taste` is a separate optional skill: follow [its own setup](https://github.com/bbrainfuckk/idra-taste#install) when needed.
**Ready means:** `doctor` reports no failures, the client has restarted/reconnected, and the current chat can discover `idra_design_brief`, `idra_create_batch`, `idra_step` and `idra_inspect_image` (possibly with a server prefix). The current host also needs an image generator and a pixel viewer. Codex can use its built-in image tool when available; Claude needs a connected generator that saves a local PNG/JPEG/WebP. An agent can still prepare a brief or critique while a generation capability is missing.
For Claude Desktop, plugin installation or web-only client limits, see [client setup](docs/claude.md). To remove only the MCP entry, use the same launcher with `uninstall-codex`, or `node idra-photo.mjs uninstall-claude --project "<project>"`. Saved images and installed skill files remain.
## Use it
Attach your photo in Codex or Claude Code and write something like:
> Use Idra Photo. Make 20 photos in the exact same style as this image: a woman holding our vitamin C serum in a sunny garden. 4:5.
The agent creates the batch, then loops: get a job, generate the image, inspect and report it, handle the next returned job. Images land in:
```
Idra Photo/outputs/<batch-name>/
001-a-woman-holding-our-vitamin-c-serum.png
002-a-woman-holding-our-vitamin-c-serum.png
manifest.json
```
More things you can say:
| You say | What happens |
|---|---|
| "Idra status" / "how far is my batch?" | Counts and where it stopped |
| "Pause the batch" | No new images start. One already generating can still finish. |
| "Resume it" | Makes the remaining jobs available again. The agent continues. |
| "Cancel it" | Stops new work. Saved images stay. |
| "Retry the failed ones" | Re-queues failures that are safe to retry. Safety refusals are never retried or reworded. |
| "Make 10 more" | Adds jobs 21-30 with the same style, references, and rules. |
| "Make 5 different concepts: beach, café, gym, office, night" | Diversified mode: one concept per image. |
| "Use these exact prompts: ..." | Explicit mode: your prompts, unchanged. |
### Keeping things the same
For a matching campaign, image series, or UI concept set, ask:
> Use Idra Photo with strict consistency. Make 6 product images using this reference. Keep the cream-and-charcoal palette, soft left window light, matte texture, and typography fixed. Only change the product angle and props. Review every image and correct drift before accepting it. 4:5.
Idra saves a named design contract and repeats its rules in every prompt. It requires a visual review of every rule against the actual generated file. The first reviewed image becomes an additional style reference. Missing reviews block acceptance; failed reviews reject the file and use the bounded retry budget. Recovery and “make more” retain the same contract. See [Strict consistency](docs/consistency.md), [examples](examples/consistency), and the [consolidated design library](design-library).
Existing batches without a consistency contract retain the original behavior:
The agent passes these as rules on every image. They are prompt requirements, not pixel locks. Check the results yourself.
- **Style**: match the reference's color grading, light, lens look, and mood.
- **Product**: keep the packaging, label, logo, colors, and proportions.
- **Identity**: keep a person recognizable.
- **Text**: render given words exactly.
- **Composition**: keep framing and placement.
Each can be `off`, `high`, or `strict`. A valid image file is not proof the product or face was preserved. Idra records whether a visual review was actually done.
### When something goes wrong
- **Codex closed mid-batch.** Say "resume my Idra batch". The agent checks status and reconciles any unreported file. Strict batches require visual review before adoption; uncertain attempts are resolved before another generation starts.
- **Usage limit or tool unavailable.** The batch pauses. Idra never guesses when limits reset and never switches providers. Resume later.
- **Codex stops after one image.** Some hosts end the turn after each image. Say "continue" to go on; Idra keeps the place.
## Watch the trailer
[](docs/trailer/idra-photo-trailer.mp4)
[Watch or download the trailer](https://github.com/bbrainfuckk/idra-photo/raw/refs/heads/main/docs/trailer/idra-photo-trailer.mp4) · [Scene, credits, and render details](docs/trailer/README.md)
## Visual examples
**Crown kingdom rework** — retain the angle and scene identity; make the supporting forms and small details specific to their function and construction.
| First uploaded reference | Final approved rework |
|---|---|
|  |  |
[Both original uploads, actual correction prompts, and design notes](docs/results/crown-kingdom/README.md). The two uploaded JPEGs contain identical bytes; both are preserved. The accepted image retains simplified distant detail. The lesson is coherent individuality at the scale that reads, not an assertion that every feature is perfect.
**Low Tide Radio** — a 1500 × 1500 cover for nine coastal instrumentals by IDRA.
<img src="docs/results/low-tide-radio/cover.png" width="420" alt="Low Tide Radio cover with blue serif type and nine tidal bands on mint stock">
[Cover, source, and design notes](docs/results/low-tide-radio/README.md). This cover was drawn in HTML/SVG through `idra-taste`, with a two-ink Risograph treatment; it is not an image-generation result.
**Claude Code + idra-taste gallery** — four existing design examples, drawn in code and rendered to images.
| Biyahe — jeepney signboard centrefold | Low Tide Radio — Riso sleeve |
|---|---|
|  |  |
| Compline — four-shade pixel cover | Night Market of Small Lights — poster |
|---|---|
|  |  |
[Claude gallery, source attribution and file hashes](docs/results/claude-gallery/README.md). These are imported `idra-taste` design examples; their source records describe Claude Code rendering code with `shot.mjs`. They are separate from the IDRA Photo queue tests below.
**Product photos** — “Make 2 square skincare product photos.”
| Front view | Matching angle variation |
|---|---|
|  |  |
**UI concepts** — “Make a matching dashboard and settings screen, square.”
| Dashboard | Matching settings screen |
|---|---|
|  |  |
The product and UI sets are real generated examples reviewed through the queue by a manual Codex host. They demonstrate the short-brief and correction workflow; they are not an autonomous Claude image benchmark.
- Idra itself needs no image API key or extra image service. Claude's connected generator may have its own setup and costs.
- Everything Idra stores stays on your computer.
- Idra itself never generates images and never makes network requests. Codex still uses its own image service and your own Codex plan.
> Status: v0.2.1 adds a short-prompt skill, Claude Code setup, and image inspection to the strict consistency workflow. Automated tests cover acceptance and recovery; [real product/UI examples](docs/results/README.md) show four accepted images and two rejected attempts. Claude Code connected to the MCP and discovered the skill; model-backed Claude generation remains untested. Evidence: [Compatibility](docs/compatibility.md).
## Privacy and limits
- Idra only reads your workspace folder and the folders listed with `--allow-import`, which by default are Downloads, Desktop, Pictures, temp, and Codex's generated-images folder. It only accepts PNG, JPEG, and WebP images from them, and copies references into the workspace.
- It never reads Codex login files and never asks for passwords, tokens, or API keys.
- No telemetry. Idra makes no network requests at runtime.
- Generation uses the connected image provider's plan and limits.
## For developers
Read [AGENTS.md](AGENTS.md#source-map-and-maintenance) and [CONTRIBUTING.md](CONTRIBUTING.md). Install development dependencies, then run the tests:
```sh
npm ci
```
```bash
npm test
```
`npm run bundle` rebuilds `idra-photo.mjs` from `src/`. Commit it with your change; CI fails if it is stale.
## Learn more
- [How it works](docs/architecture.md)
- [Compatibility and evidence](docs/compatibility.md)
- [Testing, including the real smoke test](docs/testing.md)
- [Measured overhead](docs/overhead.md)
- [Build status](BUILD_STATUS.md)
MIT licensed. See [LICENSE](LICENSE). Bundled open-source packages and their licenses are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues