sp-obsidian

Obsidian issue provider plugin for Super Productivity

Provides two-way sync between Super Productivity (SP) tasks and your Obsidian vault. Checkbox tasks (- [ ] …) and/or whole notes appear as SP "issues". Changes sync both ways: completing a task in SP checks the box in Obsidian, and vice versa.

---

How it works

Communication goes through obsidian-sp-provider, a small HTTP server plugin that runs inside Obsidian. SP polls it every 10 seconds and pushes changes as they happen.

---

Features

• Checkbox tasks (- [ ] … / - [x] …) inside any note become SP issues
• Notes/pages themselves can also be treated as issues (with the full note body synced as SP task notes)
• Bidirectional sync for done state and title; note body syncs from Obsidian → SP only
• Backlog import: pull all open tasks/notes from a vault folder into the SP backlog
• Create from SP: new tasks created in SP are appended to a configurable default note
• Recent issues on open: opening the SP add-task bar (in search mode) shows the 10 most recently modified items from your vault — no typing required
• Offline queue: if Obsidian is unreachable when you make a change in SP, the update is queued and applied automatically when the connection is restored

---

Prerequisites

1. Super Productivity (desktop app) installed
2. Obsidian installed with a vault
3. obsidian-sp-provider installed inside Obsidian

---

Installation

Step 1 — Install obsidian-sp-provider

1. Download main.js and manifest.json from the obsidian-sp-provider releases
2. Create the folder <vault>/.obsidian/plugins/super-productivity-provider/
3. Copy both files into that folder
4. In Obsidian → Settings → Community Plugins → disable Safe Mode if prompted → enable Super Productivity provider
5. Open the plugin settings to note your API Key and Port (default: 27124)

Step 2 — Install the SP plugin

1. Download obsidian-issue-provider.zip from Releases
2. In Super Productivity → Settings → Plugins → Install from ZIP
3. Select the zip file and confirm

Step 3 — Add a provider instance in SP

1. In SP → Settings → Issue Providers → Add Provider → choose Obsidian
2. Fill in the form:

Field	Value
Base URL	http://localhost:27124
API Key	Paste the key from the obsidian-sp-provider settings
Issue source	Checkbox tasks & notes, Checkbox tasks only, or Notes only
Vault folder	Optional subfolder to limit scope (e.g. Projects or Work/Tasks)
Default note	(Advanced) Path where newly created SP tasks are appended (e.g. Inbox.md)

3. Click Test Connection — it should return a success message
4. Click Save

---

Usage

Searching for issues

• Click the magnifying glass icon in the SP add-task bar to enter search/issue mode
• Leave the input empty to see the 10 most recently modified notes/tasks from your vault
• Type to filter by title

Adding a task from an Obsidian item

1. Open the SP add-task bar (keyboard shortcut or + button)
2. Enable search mode (magnifying glass icon)
3. Type part of the note or task title, or leave empty to browse recent items
4. Select the item from the dropdown — SP creates a linked task

Importing the backlog

1. In SP → Settings → Issue Providers → find your Obsidian provider → Import backlog
2. All uncompleted checkbox tasks (or notes, depending on your Issue source setting) in the configured Vault folder are added to the SP backlog

Creating a task in SP that writes back to Obsidian

1. In the add-task bar (in search mode), type a new task title and press Enter
2. SP creates the task and appends - [ ] <title> to the Default note you configured

Two-way sync in action

Action	Effect
Mark SP task done	Obsidian checkbox becomes [x]
Unmark SP task	Obsidian checkbox becomes [ ]
Rename task title in SP	Task text in the Obsidian note is updated in-place
Check a box in Obsidian	SP task is marked done on the next poll cycle
Uncheck a box in Obsidian	SP task is marked undone on the next poll cycle

Changes you make in SP push to Obsidian immediately (or are queued and flushed automatically if Obsidian is temporarily unreachable). Changes in Obsidian are picked up on the next poll (every 10 s).

---

Issue ID format

IDs are stable across line-number changes and title renames:

Source	ID format	Example
Checkbox task	task::{notePath}::sp-{8hexChars}	task::Projects/Work.md::sp-a1b2c3d4
Note	note::{notePath}	note::Projects/Work.md

Task IDs are based on an invisible marker embedded in the task line using Obsidian's comment syntax:

- [ ] Fix login bug %%sp-id:a1b2c3d4%%

The %%...%% block is hidden in Obsidian's reading/preview mode. The 8-character hex token is the stable identifier — renaming a task in SP or in Obsidian does not break the link. Markers are embedded automatically the first time a task appears in search results or is created.

Legacy text-based IDs (task::{notePath}::{taskText}) are still supported for backwards compatibility. Tasks created before the marker system was introduced will continue to work but will not survive a title rename until their marker is embedded.

---

Field sync reference

SP field	Obsidian field	Sync direction
isDone	Checkbox state ([ ] / [x]) or completed: frontmatter for notes	Both ways
title	Task text in note / note filename	Both ways
notes	Full note body (Markdown)	Pull only (Obsidian → SP)

---

Troubleshooting

Test Connection fails

• Make sure the Obsidian app is open and obsidian-sp-provider is enabled
• Check that the Base URL port matches the plugin settings (default: 27124)

Issues don't appear in the search bar

• Make sure you've clicked the magnifying glass icon to enable search/issue mode in the add-task bar
• Verify the Vault folder setting points to an existing folder in your vault (leave empty to search the whole vault)

Changes in Obsidian aren't syncing to SP

• Check the Poll interval — changes are picked up on the next poll cycle (default 10 s)
• The note file must have been saved in Obsidian before the poll runs

New tasks aren't appended to Obsidian

• Make sure the Default note path exists in your vault (e.g. Inbox.md)
• The path is relative to the vault root

---

Development

npm install
npm run build        # compile src/plugin.ts → plugin/plugin.js
npm run build:watch  # watch mode for development
npm run typecheck    # TypeScript type check only
npm run zip          # package plugin/ into obsidian-issue-provider.zip

To test against a live SP instance, load the zip via SP → Settings → Plugins → Install from ZIP.

---

License

MIT