codex-image-to-eagle git:20260911.fcee81bB

Immutable. This exact content is served forever at /api/v1/blob/c37d18319e3f2319.

---
name: codex-image-to-eagle
description: Archive Codex-generated images from the current user's Codex generated_images directory into Eagle with the prompt saved as annotation. Use when the user asks to save, archive, import, or sync Codex generated images to Eagle with prompts, tags, and folders.
allowed-tools: Bash(node *)
metadata:
  vsc-category: "图片归档"
  vsc-deliverables: "archive"
  vsc-distinction: "将已有 Codex 生成图片连同原始提示词导入 Eagle；依赖实际图片来源与 Eagle，不负责生图，也不泛化为任意素材库迁移。"
---

# Codex Image to Eagle

Archive images generated by Codex into Eagle and preserve the prompt as searchable metadata.

## Default behavior

- Image source: `CODEX_GENERATED_IMAGES_DIR` if set, otherwise `<current user home>/.codex/generated_images`
- Eagle connection: local Eagle MCP server on `http://127.0.0.1:41596` by default. Prefer the IPv4 loopback address over `localhost` to avoid IPv6/hostname resolution issues.
- Stdio mode: the script reads the current user's `~/.codex/config.toml`, prefers `[mcp_servers.eagle]`, and can auto-detect other Eagle-like stdio MCP entries. Use `--transport http` to force the legacy HTTP path.
- Import method: Eagle MCP `item_add`
- Prompt storage: Eagle item `annotation`
- Default tags: `Codex`, `AI生成`, `Prompt`
- Default folder: use the folder requested by the user as the root; if none is specified, create or reuse `Codex 生成图`
- Default organization: put each image into a local-date subfolder under the root, e.g. `Codex 生成图/2026-4-26`
- Folder safety: resolve folders by exact parent-child path, not by name alone. Folder creation is guarded by a local lock to avoid duplicate date folders when several automation jobs run at the same time.

## Script

Use the bundled script:

```bash
node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT"
```

The bundled script defaults to `http://127.0.0.1:41596`. If needed, override it explicitly:

```bash
EAGLE_SERVER_URL=http://127.0.0.1:41596 node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT"
```

Stdio MCP mode:

```bash
node scripts/archive-codex-image-to-eagle.js --transport stdio --latest --prompt "PROMPT_TEXT"
node scripts/archive-codex-image-to-eagle.js --transport stdio --check-connection
```

Example Codex config:

```toml
[mcp_servers.eagle]
command = "node"
args = ["/your/Eagle/Plugins/mcp-server/modules/mcp-proxy.js"]
env = { EAGLE_SERVER_URL = "http://127.0.0.1:41596" }
```

Important: the script can read `~/.codex/config.toml`, but it cannot automatically reuse MCP tools already connected to Codex. If the script is launched inside a network-restricted automation shell, a child stdio proxy may still inherit that sandbox. The strongest automation path is to call the configured Eagle MCP tool directly from Codex instead of shelling out to this script.

When using Eagle MCP tools directly, folder handling must follow this exact rule:

1. Resolve the root folder first.
   - Prefer `EAGLE_CODEX_ROOT_FOLDER_ID` or a user-provided root folder ID.
   - Otherwise call `folder_get` with `getAllHierarchy: true, fullDetails: true` and find the root folder whose `name` is exactly `Codex 生成图` or the requested root name and whose `parent`/`parentId` is empty.
2. Resolve the date folder only under that root folder.
   - Search children by exact `name` and exact parent ID.
   - Never search by date name globally.
   - Never create a date folder at Eagle root level unless the requested root itself is intentionally the Eagle root.
3. Create a missing date folder with `parentId` set to the resolved root folder ID.
4. If more than one matching date folder already exists under the same root, reuse the oldest existing folder ID and report the duplicate instead of creating another one.
5. For automation concurrency, prefer the bundled script because it has a local lock around folder creation.

Common options:

```bash
# Import the newest Codex-generated image.
node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT"

# Override the Codex generated image directory when needed.
node scripts/archive-codex-image-to-eagle.js --latest --image-dir "~/.codex/generated_images" --prompt "PROMPT_TEXT"

# Import all image files in the newest generated_images session folder.
node scripts/archive-codex-image-to-eagle.js --latest-session --prompt "PROMPT_TEXT"

# Import a specific file.
node scripts/archive-codex-image-to-eagle.js --path "/absolute/path/image.png" --prompt "PROMPT_TEXT"

# Read a long prompt from a file.
node scripts/archive-codex-image-to-eagle.js --latest --prompt-file "/absolute/path/prompt.txt"

# Choose a target Eagle folder by name or ID.
node scripts/archive-codex-image-to-eagle.js --latest --folder-name "Codex 生成图" --prompt "PROMPT_TEXT"
node scripts/archive-codex-image-to-eagle.js --latest --folder-id "FOLDER_ID" --prompt "PROMPT_TEXT"
node scripts/archive-codex-image-to-eagle.js --latest --root-folder-id "ROOT_FOLDER_ID" --prompt "PROMPT_TEXT"

# Automation: fixed folder ID skips folder_get/folder_create permission prompts.
EAGLE_CODEX_FOLDER_ID="FOLDER_ID" node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT"

# Automation: fixed root folder ID still creates/reuses date subfolders under that root.
EAGLE_CODEX_ROOT_FOLDER_ID="ROOT_FOLDER_ID" node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT"

# Disable date subfolders and import into the root folder directly.
node scripts/archive-codex-image-to-eagle.js --latest --no-date-subfolders --prompt "PROMPT_TEXT"

# Preview without modifying Eagle.
node scripts/archive-codex-image-to-eagle.js --latest --prompt "PROMPT_TEXT" --dry-run

# Test MCP connectivity without importing images.
node scripts/archive-codex-image-to-eagle.js --transport stdio --check-connection
```

## Workflow

1. Identify the image path.
   - If the user refers to the latest generated image, use `--latest`.
   - If a generation produced multiple images, use `--latest-session`.
   - If the user provides a path, use `--path`.
2. Capture the final prompt exactly as used to generate the image.
3. Run the script with the prompt.
4. Return the imported Eagle item ID(s) and the folder used.

## Prompt annotation format

The script writes this structure into Eagle `annotation`:

```text
Prompt:
...

Archive:
- source: Codex
- original_path: ...
- archived_at: ...
```

## Safety

- Do not delete or move source files in the Codex generated images directory.
- Use `--dry-run` first when the prompt, folder, or image selection is uncertain.
- If Eagle is not running or the MCP plugin is disabled, ask the user to start Eagle and enable Eagle MCP.