Immich Journal

An Obsidian plugin that inserts photos from your self-hosted Immich server into your daily notes — resized, captioned, and linked back to Immich.

Status: early development. Not yet released as a Community Plugin. Install via BRAT (see below) to try it now.

Features

• One command opens a picker with all photos taken on the current daily note's date
• Date is detected from the note title (configurable format) or a frontmatter field — and when neither resolves, the picker simply opens on the most recent day that has photos
• Multi-select in the grid, then insert all chosen photos below each other at the cursor position (end of file if no editor is active)
• Photos are saved as resized local copies — the longest edge is scaled down to a configurable maximum (default 800 px), never upscaled, JPEG quality 0.85 — so your vault stays small and the original never leaves Immich
• Optional caption line rendered from a template using Immich metadata ({{description}}, {{time}}, {{city}}, {{country}}, {{camera}}, {{people}}, {{filename}}, …); an empty rendered caption is omitted entirely, no dangling formatting
• Each inserted photo links back to the original asset in your Immich web UI
• Works on desktop and mobile — including setups where Immich is only reachable through a VPN such as Tailscale
• Localized UI: English, German, Spanish, French, Japanese, Chinese

Requirements

• A self-hosted Immich server you can reach from the device running Obsidian
• An Immich API key with at least the asset.read and asset.view permissions

Setup

1. In Immich, go to Account Settings → API Keys and create a new key. Grant it asset.read and asset.view. A key that is scoped too narrowly will authenticate fine but fail with 403 Forbidden as soon as the plugin tries to load a thumbnail — the built-in "Test connection" button in the plugin settings checks a real thumbnail fetch, not just a lightweight ping, specifically to catch this.
2. In Obsidian, open Settings → Immich Journal and fill in:
   • Server URL — e.g. https://immich.example.com (no trailing slash)
   • API key — the key from step 1
3. Click Test connection. You should see a success message; if not, see Troubleshooting below.
4. Run the "Insert photos from Immich for this day" command from a daily note (or via the ribbon icon), select photos, and insert.

Troubleshooting

Settings reference

Works great with Tailscale / VPN

The most common self-hosted Immich setup is a server reachable only inside a private network or VPN (Tailscale, WireGuard, etc.), not on the public internet. Immich Journal works well with this:

• All requests go through Obsidian's requestUrl() API, so there is no CORS configuration to worry about on the Immich side, on desktop or mobile.
• On iPhone/iPad, make sure your VPN (e.g. the Tailscale app) is connected before using the plugin. Without it, the server is simply unreachable.
• If the server can't be reached, the plugin shows a clear error instead of hanging — check your VPN connection first.

Installation

Not yet available in the Community Plugins directory. Until it passes community review, install it via BRAT (Beta Reviewer's Auto-update Tool):

1. Install the BRAT plugin from Community Plugins.
2. In BRAT's settings, add this repository: https://github.com/fcandi/obsidian-immich-journal
3. Enable Immich Journal in your installed plugins list.

Immich version compatibility

Immich Journal deliberately uses only three stable, long-standing Immich API endpoints, to stay resilient against the fast pace of Immich's development:

• POST /api/search/metadata — find photos taken on a given day
• GET /api/assets/{id}/thumbnail?size=thumbnail|preview — load grid thumbnails and the higher-resolution image used for the resized insert
• The web UI deep link pattern {server}/photos/{assetId} — no API call, just a URL

If a future Immich release changes these, please open an issue with your server version.

Development

• npm run dev — esbuild in watch mode, emits main.js into the repo root on every change.

• One-time setup: symlink this repo into your test vault's plugins folder, e.g.:

  ln -s ~/DEV/obsidian-immich-journal "<vault>/.obsidian/plugins/immich-journal"
  

  Enable the plugin in Obsidian, then reload Obsidian (or use a hot-reload plugin) after each change to pick up the new main.js.

• npm run build — production build.

• npx tsc --noEmit — type-check without emitting.

• npx vitest run — run the unit test suite.

License

MIT