codex-image-to-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:

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:

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

Stdio MCP mode:

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:

[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:

# 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:

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.