Skip to content

DR-007: Obsidian launch URL format in chat output

Status

Accepted — 2026-04-14 · Rick-confirmed after terminal rendering test

Context

Rick's previous workflow for opening a vault markdown file from chat output required: leaving the chat → navigating to the file in Finder → opening with a third-party markdown viewer called "One Markdown" → manually refreshing when the file changed. Four clicks and a context switch for every file reference.

The problem was two layers: 1. Finder navigation broke his flow because chat doesn't render absolute paths as clickable 2. Third-party viewer was needed because he wanted Obsidian-quality rendering, but Obsidian wasn't easily launch-able from chat references

Rick had previously adopted a workflow of generating parallel HTML versions of markdown files (via Tailwind) to get good rendering without needing a separate tool. That workflow produced duplicate documents — .md + .html — with drift problems and extra maintenance.

Decision

Use the obsidian:// URL scheme to reference vault files in chat output. Format:

obsidian://open?vault=Claude&file=PATH_RELATIVE_TO_VAULT_ROOT

Where the path is URL-encoded (forward slashes → %2F, .md extension optional — Obsidian adds it if missing). The vault name Claude is confirmed (matches the folder name at /Users/rhartley/Claude/).

Format as inline code (single backticks), NOT as markdown link [text](url). Rick's terminal (Termius, tested 2026-04-14) does not render markdown link syntax as clickable for custom URL schemes — most terminals only auto-link http(s) URLs, and wrapping in markdown [text](url) actually suppresses auto-detection.

Example:

**Monday.com stub:**
`obsidian://open?vault=Claude&file=knowledge%2Ftools%2Fmonday-com`

Rick triple-clicks the line, Cmd+C copies it, pastes into browser or Spotlight, macOS routes the custom URL scheme to Obsidian, file opens in Obsidian's live preview.

Distinction from in-vault references: inside vault markdown files, use Obsidian [[wikilinks]] (not obsidian:// URIs). Wikilinks are native to Obsidian, create graph edges, enable backlink tracking, and are what Dataview queries depend on.

For files outside the vault (memory files, Downloads folder, production paths), use plain absolute paths — they're not Obsidian-accessible.

For external URLs (Tailscale dashboards, vendor docs), use regular https:// links.

Alternatives considered

Option A — Absolute file paths

e.g., /Users/rhartley/Claude/knowledge/tools/monday-com.md

Rejected. Rick's terminal doesn't auto-link these for click-to-open. He'd still need to navigate in Finder or manually copy the path to a viewer.

e.g., [monday-com](obsidian://open?vault=Claude&file=knowledge%2Ftools%2Fmonday-com)

Rejected after testing. Rick confirmed his Termius terminal renders markdown link syntax as colored text but NOT as clickable — and wrapping the URL in markdown syntax actually suppresses auto-detection of the custom URL scheme.

Option C — Inline code format with obsidian:// URL (this decision)

Accepted. Visually distinct, copy-paste friendly (triple-click to select whole line), Cmd+C works cleanly, Safari/Chrome routes the paste to Obsidian via macOS URL scheme handler.

Deferred. iTerm2 would make the links natively clickable in the terminal, skipping the copy-paste step. But Rick uses Termius for the iPad workflow and installing iTerm2 just for Mac creates a split tool story. Better long-term answer: VS Code's integrated terminal (evaluated in parallel, documented in /knowledge/playbooks/vscode-claude-obsidian-setup.md), which supports clickable obsidian:// URLs natively without configuration.

Consequences

What becomes easier: - Rick can launch any vault file from chat output with 3 clicks (triple-click + Cmd+C + paste) - No need to maintain parallel .md + .html versions of documents - Obsidian becomes the single canonical reading environment - Future team members with Obsidian installed get the same link format automatically

What becomes harder: - Rick's current Termius workflow requires copy-paste (not one-click) — VS Code migration is the long-term fix - Chat output is slightly longer (URL-encoded paths are verbose) - Browser popup appears on first paste per-session ("Do you want to open Obsidian?") — Chrome has "Always allow" checkbox, Safari does not

Trade-off accepted: Verbose URL format + copy-paste friction in exchange for universal launch capability without a separate viewer.

  • [[CLAUDE]] — vault governance constitution
  • [[obsidian]] — tool page
  • [[/knowledge/playbooks/vscode-claude-obsidian-setup]] — the long-term fix (clickable in VS Code integrated terminal)
  • Chief.staff memory feedback_obsidian_launch_links.md — the feedback memory capturing this rule

Date: 2026-04-14 · Author: chief.staff · Stakeholders: ceo, chief.staff