@bytetrue/pi-image-gen

Generate and edit images from Pi without carrying a permanent Agent tool.

Forked from @amaster.ai/pi-image-gen. Redistribution details are preserved in NOTICE.

The package deliberately has two surfaces:

• /image-gen gives people a complete TUI setup flow.
• The pi-image-gen Skill and bundled CLI load only when the Agent needs to create or edit an image.

No permanent image_generate tool schema is added to every request.

Install

pi install npm:@bytetrue/pi-image-gen

Restart Pi and run:

/image-gen

Choose a built-in or custom provider, select a model, configure credentials, and set an output directory. Normal setup never requires editing JSON by hand.

Generate from Pi

Ask normally:

Generate a cinematic 16:9 image of a lunar research station.

For an edit or a consistent character/style, attach a local reference image or mention a previously generated path. The Skill invokes the bundled CLI and returns generated files as inline Markdown.

The configured defaultModel is always used; the CLI does not accept a model override.

Providers

Custom providers select one of these wire protocols and supply their own endpoint and model id.

Configuration

/image-gen writes a dedicated package config file — <config dir>/pi-image-gen/settings.json (by default ~/.pi/agent/pi-image-gen/settings.json); it never touches Pi's settings.json.

Credential choices include:

• the provider's standard environment variable;
• another $ENV_VAR reference;
• a literal key entered in a masked field; or
• no key for a local or keyless endpoint.

Writes use an atomic 0600 path and refuse to overwrite malformed settings. Selecting No API key writes apiKey: "", blocking lower-layer and standard-environment credentials. Selecting No extra headers writes headers: {}, blocking inherited headers.

Relative output directories resolve from the Pi session working directory. The default is .pi/images.

{
  "defaultModel": "my-sd/sd-3-large",
  "outputDir": ".pi/images",
  "providers": {
    "openai": {
      "baseUrl": "https://proxy.example.com/v1",
      "apiKey": "$OPENAI_API_KEY"
    }
  },
  "customProviders": {
    "my-sd": {
      "api": "openai",
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "$SD_KEY",
      "models": [{ "id": "sd-3-large", "alias": "sd3" }]
    }
  }
}

Skill CLI

The bundled Skill sends one JSON object to skills/pi-image-gen/scripts/image-gen.mjs:

{
  "prompt": "A watercolor lighthouse in a winter storm",
  "image": ["/optional/reference.png"],
  "n": 1,
  "size": "1024x1024",
  "filename": "winter-lighthouse"
}

prompt is required. image, n (1–8), size, filename, and outputDir are optional. Image inputs may be local paths or HTTP(S) URLs. The CLI never prints configured credentials.

[!NOTE] The CLI resolves PI_CODING_AGENT_DIR / PI_AGENT_HOME the same way Pi does, so a redirected Pi config dir carries the image-gen config with it.

Development

This package builds dist because the extension and Skill CLI share one production core:

npm --workspace @bytetrue/pi-image-gen test
npm --workspace @bytetrue/pi-image-gen run typecheck
node packages/pi-image-gen/scripts/pack-smoke.mjs