Linkwise

The official Obsidian integration for Linkwise. Effortlessly sync your saved links, AI-generated summaries, key questions, live highlights, and curated collections directly into your vault as clean, native Markdown notes.

Key Features

• One-Way Incremental Sync: Seamlessly pulls updates from Linkwise into Obsidian without slowing down your vault.
• Local-First & Non-Destructive: Linkwise keeps your summaries and highlights perfectly up to date, but anything you write in a note is completely safe and never overwritten.
• Color-Coded Highlights: Preserves your Linkwise highlight colors using clean CSS styling, mapped directly to frontmatter for easy filtering.
• Smart Updates: Notes are tracked via a unique identifier, allowing you to safely rename or reorganize files without creating accidental duplicates.
• Distinct Collection Maps: Each collection gets a Map of Content hub note (🗺️ <Collection>) that stands apart from the links it indexes — a 🗺️ map marker in its name, a summary callout with a live link count, and a #linkwise/moc tag.
• One-Click Graph Colors: A Set up graph colors command paints your collection maps a distinct color in Obsidian's graph, so hubs pop out from the notes around them — without disturbing any graph settings you've already made.
• Clean Notes: Notes start straight at the summary — no source banner cluttering the top.
• Cover Images: The article's cover image is shown at the top of each note (when Linkwise has one), styled to fit. Toggle it off if you prefer text-only notes.

📝 Note: This plugin requires an active Linkwise Pro subscription.

Installation

Method 1: Via Community Plugins (Recommended)

1. Open Obsidian and navigate to Settings → Community plugins.
2. If you haven't enabled third-party plugins yet, click Turn on community plugins.
3. Click Browse, search for Linkwise, and click Install.
4. Once installed, click Enable to activate the plugin.

Method 2: Manual Installation

1. Download the latest main.js, manifest.json, and styles.css from the GitHub Releases page.
2. Inside your Obsidian vault, navigate to .obsidian/plugins/ and create a new folder named linkwise.
3. Move the three downloaded files into that folder.
4. Reload Obsidian, go to Settings → Community plugins, click the Refresh icon, and toggle Linkwise on.
5. Click the gear icon to begin configuration.

Connecting to Linkwise

Setting up the sync connection is quick and secure. Choose one of the two options below to pair your vault.

Option A: Scan QR Code (Recommended)

1. In Obsidian, go to Settings → Linkwise. Under the Connection section, click Show QR Code.
2. Open the Linkwise app on your phone.
3. Navigate to Settings → Integrations → Linkwise for Obsidian and tap Scan to connect.
4. Point your camera at the QR code on your screen. The plugin will auto-configure and trigger its initial sync. Note: QR codes expire after 5 minutes for security. Click New QR Code if it times out.

Option B: Manual Token Entry

1. Open the Linkwise mobile app.
2. Go to Settings → Integrations → Linkwise for Obsidian and select Generate Token.
3. Tap Copy to save the token (it begins with lw_pat_…).

   ⚠️ Important: This token is only displayed once. Store it securely or regenerate a new one if lost.

4. In Obsidian, go to Settings → Linkwise → Advanced, and paste it into the Personal Access Token field.

How Sync Works

You can trigger a manual synchronization at any time using three different methods:

• Clicking the circular-arrows icon in the ribbon menu on the left.
• Opening the Command Palette (Cmd/Ctrl + P) and running "Linkwise: Sync now".
• Clicking the Sync Now button inside the plugin settings panel.

Upon completion, a native notification will display your sync summary (e.g., "Linkwise: sync complete — 24 new, 3 updated"). If you prefer a hands-off approach, you can configure an Auto-sync interval in the settings to pull updates in the background.

Vault Structure & Note Anatomy

Directory Layout

The plugin preserves your Linkwise organization by mapping your collections directly to vault folders. Unfiled links are neatly placed into an Unsorted directory.

Linkwise/
 ├── Research/
 │    ├── 🗺️ Research.md               # Map of Content — hub linking every link in the collection
 │    ├── Agent Harness Engineering.md
 │    └── Attention Is All You Need.md
 └── Unsorted/                         # For links not yet assigned to a collection
      ├── 🗺️ Unsorted.md               # Map of Content for unfiled links
      └── ...

ℹ️ Upgrading from an earlier version? Legacy index notes (a plain MOC, <Collection> (MOC), the collection name itself, or the old _MOC) are renamed to 🗺️ <Collection> automatically on the next sync — no duplicates, nothing lost.

Maps of Content

Each collection folder contains a Map of Content — a fully managed 🗺️ <Collection> note that wikilinks every link in the collection. The 🗺️ marker in its name makes it pop in the graph and file explorer, and its title comes straight from the filename (no redundant heading):

---
linkwise_moc: true
collection: "Research"
tags: [linkwise/moc]
---

> [!info] Map of Content
> Index of the **Research** collection : 12 links.

- [[Agent Harness Engineering]]
- [[Attention Is All You Need]]

Run Linkwise: Set up graph colors (Command Palette, or the button in settings) to color these hubs distinctly in the graph view. See Graph Colors below.

Note Blueprint

Every synced note features rich properties (frontmatter) and a clean sections layout. When Linkwise has a cover image for the article, it's shown at the top (toggle: Show cover image, on by default). Notes start straight at the summary:

---
linkwise_id: "cf2cf531-..."
title: "Agent Harness Engineering"
url: "https://addyosmani.com/blog/agent-harness-engineering/"
source: "addyosmani.com"
collection: "Research"
tags: [ai, agents]
highlight_colors: [yellow, purple]
saved: 2026-06-16
cover: "https://..."
---

<img class="linkwise-cover" src="https://addyosmani.com/assets/images/agent-harness.jpg" alt="Cover image" referrerpolicy="no-referrer">

## Summary
The AI-generated summary text appears here...

## Key Questions
**A core question the article answers**
The AI-generated answer detailing the concepts...

## Highlights
<blockquote class="linkwise-highlight" data-color="yellow" style="border-left: 4px solid #FEF08A;">
A sample passage you highlighted while reading inside Linkwise.
</blockquote>

*Your personal annotation or thought attached to this specific highlight.*

## My Notes
Write anything you want here! Your thoughts, permanent links, and deeply structural outlines belong down here. This section completely survives all future syncs.

🛑 The Golden Rule of Editing

To keep your data intact while allowing for seamless updates, the plugin uses a strict boundary rule:

• Everything ABOVE ## My Notes is managed by Linkwise and will be refreshed during synchronization.
• Everything BELOW ## My Notes belongs entirely to you. The sync engine will never overwrite or alter anything in this section. Do not modify or delete the ## My Notes header itself.

Graph Colors

Collections form little hub-and-spoke clusters in Obsidian's graph: the 🗺️ <Collection> Map of Content hub in the center, its links around it. By default every node is the same color, so the hub blends in. The Set up graph colors command fixes that.

Run it from the Command Palette (Linkwise: Set up graph colors) or the Graph colors button in settings. It adds two color groups to your graph configuration:

• Collection maps (tag:#linkwise/moc) — violet, so hubs pop out.
• Linkwise notes (path:"<your vault folder>") — muted slate.

The command is non-destructive: it only adds groups whose query you don't already have, and never edits or removes color groups you set up yourself. After running it, close and reopen the graph view to see the new colors. Prefer different colors? Adjust them any time under Settings → Graph view → Groups.

Settings Reference

Troubleshooting

Privacy & Security

• Zero Telemetry: The plugin does not bundle trackers, analytics engines, or external data catchers. It communicates strictly with the core Linkwise Sync API.
• Secure Storage: Your access token is stored safely within your vault's internal .obsidian/plugins/linkwise/data.json file. If your vault is hosted on a shared sync network, treat it with the same caution as a password. You can revoke it instantly inside the mobile app.
• Multi-Device Vault Layouts: If you use Obsidian Sync or an external provider across multiple devices, we recommend triggering the Linkwise synchronization loop from one primary device to eliminate file-write race conditions.

Development Workflow

Get the local developer environment up and running with standard npm operations:

# Install package dependencies
npm install

# Run the project in development/watch mode
npm run dev

# Run type-checking and generate production-ready bundle
npm run build

# Run code linter
npm run lint

Project Architecture

The codebase is structured modularly within the src/ directory:

• main.ts: Handles the main lifecycle events and initialization hooks of the Obsidian plugin.
• settings.ts: Implements the UI configurations panel and settings parsing logic.
• api.ts: Manages network requests and data framing with the Linkwise data endpoints.
• sync.ts: Core processing engine responsible for handling differential pulls and local document writes.
• markdown.ts: Parser tasked with parsing boundaries to merge upstream changes into your custom files cleanly.

License

This project is licensed under the terms of the MIT License. See LICENSE for details.