Eagle Integration

Eagle Integration

Paste images into Obsidian notes and they're automatically uploaded to Eagle — your dedicated media manager. Keep your vault lean, your Eagle library rich, and your images searchable.

Why Eagle Integration?

Your Obsidian vault is for text. Eagle is for images. This plugin bridges them seamlessly:

• Paste once, organize with Eagle — paste screenshots, clips, or photos; they auto-upload to Eagle and render in your notes via local cache
• Keep your vault small — stop bloating your vault with embedded image files; store everything in Eagle instead
• Search-friendly — search your Eagle library without leaving Obsidian; insert images with a single search
• Works offline — cached thumbnails render even if Eagle isn't running

Features

• ⚡ Instant paste upload — paste or drag images directly into notes; auto-upload to Eagle
• 🎨 Canvas support — upload images in Obsidian Canvas views
• 🔍 Smart deduplication — same image pasted twice? Reused from Eagle instead of re-uploading
• 📂 Folder mapping — route uploads to different Eagle folders based on your note location
• 🖼️ Visual search — browse your entire Eagle library with thumbnail previews and instant insert
• 💾 Offline rendering — images cached locally in your vault; work without Eagle running
• ⚙️ Naming templates — customize how images are named in Eagle (e.g., {uuid}_{noteName})
• 🔄 Cache sync — missing cache files auto-restore on startup and tab switch
• 🗑️ Smart cleanup — delete an image in Eagle and the cache copy evicts automatically
• 🔙 Backward compatible — old-format Eagle links still render; migration command available

Requirements

• Eagle 3.0+ installed and running (https://eagle.cool/)
• Desktop only — Obsidian on Mac, Windows, or Linux (uses Electron APIs)
• Eagle's local API enabled (default: localhost:41595)

Installation

Community Plugins (Recommended)

1. Open Settings > Community plugins
2. Search for Eagle Integration
3. Click Install and then Enable

Manual Installation

cd <your-vault>/.obsidian/plugins
git clone https://github.com/GoBeromsu/obsidian-eagle-plugin eagle-plugin
cd eagle-plugin
pnpm install && pnpm build

Restart Obsidian and enable the plugin under Settings > Community plugins.

Quick Start

1. Make sure Eagle is running
2. Open any note in Obsidian
3. Paste or drag an image into the editor

That's it. The plugin uploads to Eagle, caches the image in eagle-cache/, and inserts a wikilink:

![[eagle-cache/LXXXXXXXXXXXXXXX.jpg]]

The image renders immediately — no folders to manage, no file paths to remember.

Commands

Right-click a local image to access Upload to Eagle from the context menu.

Configuration

Basic Settings

Folder Mapping

Route uploads to different Eagle folders based on your note's location. Add rules under Settings > Eagle Plugin Settings > Folder Mapping. The longest matching prefix wins.

Example:

A note at Projects/Design/wireframe.md uploads to the Design Eagle folder. A note at Projects/research.md uploads to Projects. Everything else goes to Misc.

Cache Management

All embedded images are stored as wikilinks pointing to your local cache:

![[eagle-cache/LXXXXXXXXXXXXXXX.jpg]]

On startup and tab switch, missing cache files are backfilled from Eagle. If you delete an image in Eagle, its cache copy evicts on the next sync.

To rename the cache folder:

1. Update Cache Folder in settings
2. Confirm the prompt — the plugin moves all cached files and updates wikilinks automatically

Migrating from Old Format

Versions prior to 2.0 used this format:

![eagle:LXXXXXXXXXXXXXXX](https://raw.githubusercontent.com/goberomsu/obsidian-eagle-plugin/HEAD/file:///absolute/path/to/image.jpg)

Run Eagle: Migrate all images to eagle-cache to convert all old-format links to wikilinks. Old-format links continue to render for backward compatibility.

Architecture

obsidian-eagle-plugin/
├── src/
│   ├── main.ts                  # Plugin entry point
│   ├── Canvas.ts                # Canvas paste handler
│   ├── domain/settings.ts       # Configuration schema
│   ├── domain/folder-mapping.ts # Folder routing logic
│   ├── ui/
│   │   ├── EagleCacheManager.ts         # Cache operations
│   │   ├── EagleHashStore.ts            # Dedup store
│   │   ├── EagleUploader.ts             # Eagle REST client
│   │   ├── EaglePluginSettingsTab.ts    # Settings UI
│   │   ├── EagleSearchPickerModal.ts    # Search modal
│   │   └── ImageUploadBlockingModal.ts  # Upload progress
│   ├── utils/
│   │   ├── file-url.ts          # file:// ↔ OS path
│   │   ├── folder-mapping.ts    # Route resolution
│   │   ├── markdown-image.ts    # Markdown parsing
│   │   └── item-naming.ts       # Naming templates
│   └── types/
├── test/                        # Unit + e2e tests
├── scripts/                     # Build & release
└── manifest.json

Development

pnpm install
pnpm dev          # Watch mode + hot reload
pnpm build        # Production build
pnpm test         # Unit tests
pnpm lint         # ESLint
pnpm run ci       # Build + lint + test (pre-release check)
pnpm e2e          # WebdriverIO end-to-end tests

scripts/, .github/workflows/, and src/shared/ are repo-local helpers in this plugin. Keep them aligned with shared harness expectations when relevant, but treat implementation details here as the source of truth.

See DEVELOPMENT.md for detailed setup instructions.

FAQ

Q: Is my data secure? A: All images remain on your machine in Eagle's local library. No data is sent to external servers.

Q: Can I undo an accidental upload? A: Yes — delete it from Eagle directly. On the next tab switch, the plugin detects the deletion and removes the cache file.

Q: Do images render if Eagle is offline? A: Yes — images are cached in your vault as standard Obsidian wikilinks and render regardless of Eagle's status.

Q: Can I upload videos? A: Currently the plugin focuses on image uploads. Video support may come in future releases.

Q: Can I bulk-upload my existing vault images to Eagle? A: Not yet. You can migrate individual images using the Upload to Eagle command, or use Eagle's built-in import features.

Known Limitations

• Animated GIFs pasted from clipboard are captured as static images by the OS. Use drag-and-drop for animated GIFs.
• Eagle must be running for uploads and cache sync; rendering always works via local cache.

Credits

• Originally forked from gavvvr/obsidian-imgur-plugin
• Adapted for Eagle integration and expanded with folder mapping, thumbnail search, and cache management

Contributing

Contributions welcome. Please open an issue or discussion before starting work on large changes.

For questions or suggestions, use GitHub Discussions.

License

MIT

---

If this plugin saves you time, consider giving it a star on GitHub. Made with care for Obsidian users who care about their media library.