TL;DR

FolderTether is an Obsidian plugin that creates a bidirectional link between a note and any directory on your filesystem. From Obsidian, a single click opens the linked folder in Finder. From Finder, a .url file sitting in the folder opens the note directly in Obsidian. The vault stops being a walled garden and becomes a navigational index over your entire digital workspace.

A colleague and I were talking about Markdown files and how they've become the default format for working in AI environments. Naturally the conversation drifted to Obsidian because I am a big fan. He mentioned something that stuck with me: he couldn't get comfortable with the vault concept, Obsidian's way of containing everything in a single managed folder, and it was holding him back from the tool entirely. He'd dabbled with this great note-taking system, but his actual work didn't live in it. His code was somewhere else. His documents were somewhere else. His Obsidian notes were somewhere else. Three separate places, no connection between them.

This is a problem almost every Obsidian user runs into, and most people just accept it. I had become so used to working in the Obsidian environment that I had become blind to this disconnect. Now that it was visible again, I didn't want to accept it.

The Real Problem

Here's the scenario: you have a project called Alpha. Code lives in ~/Projects/Alpha. Client documents live in ~/Dropbox/Clients/Alpha. Notes live in Obsidian. You create a project note and paste the directory path into it as a reminder. Three months later, you've reorganized the folder. The path is wrong. You rename the note. Nothing else updates. You search for "Alpha" across three applications and find half of what you need.

You may be thinking, why use Obsidian at all? It turns out that Obsidian is actually an excellent application for several reasons, and the most relevant one to this audience is that it works seamlessly with AI.

Enterprise tools like Confluence, Jira, and SharePoint solve this with "link to external resource" features. But for individual Obsidian users working locally, the vault boundary is hard. Obsidian knows everything inside the vault and nothing outside it.

FolderTether is my attempt to fix this without breaking what makes Obsidian good.

What FolderTether Does

The plugin creates a tether: a persistent, bidirectional link between an Obsidian note and a directory anywhere on your filesystem. Not a sync, not a copy, not a mirror. Just a connection that works from both ends.

From Obsidian outward (the plugin):

Open the command palette and run "FolderTether: Link note to directory." A native macOS folder picker opens. You select the directory. Two things happen:

1. The plugin writes linked_dir to the note's frontmatter as a clickable file:// URI — it renders as a clickable link in Obsidian's Properties panel. Click it, Finder opens to that directory.

2. The plugin writes a [Note Name].url file into the directory — a standard Internet Shortcut file containing an obsidian:// URI. Double-click it from Finder and it opens the note directly.

From Finder inward (the Quick Action):

Right-click any folder in Finder → "FolderTether" from the Quick Actions menu. Enter a note name when prompted. The same two things happen in reverse: a .url file gets written into the folder, and Obsidian opens with a new note already created and linked_dir pre-populated.

Both paths produce the same end state: a note and a folder that know about each other.

The .url File Is the Key Insight

"Wait, I can navigate to my Obsidian note from Finder?" Yes — from any Finder window, any Terminal session, any app that can open files. The note is no longer locked inside the vault. It has a presence in your actual file system via the .url file. This requires zero installation on the directory side, no special software, no background service. Double-click it in Finder and it opens an obsidian:// link that takes you directly to the note.

The Philosophy Behind It

Obsidian's core design principle is that connections matter more than location. Your notes don't need to live in a folder hierarchy that mirrors reality. Physical location is secondary. This approach is liberating but requires some retraining after years of using folders on your local drive.

FolderTether extends this principle of connections further. The note doesn't need to be in a vault subfolder that mirrors your project directories. It can live at the vault root or wherever it makes conceptual sense. The tether is the relationship — not the folder it's stored in.

This is increasingly relevant for AI agents. When Claude Code queries your vault, it can discover notes about your projects and follow the linked_dir link to find the actual project directory — without you having to tell it where things are. The vault becomes an index over your entire digital workspace, not just the Markdown files inside it.

Current State

The plugin is available on GitHub: https://github.com/pablooliva/foldertether

It's in active development. The core workflow for linking a note to a directory and creating a note from Finder is functional. If you run into anything or have feature requests, open an issue.

FolderTether is one piece of a larger system for managing knowledge across tools, vaults, and local files. The next posts in this series will cover how all of it fits together.