Super Productivity provider — Obsidian plugin

An Obsidian community plugin that runs a lightweight local HTTP server inside Obsidian, allowing Super Productivity to read and write your vault files for two-way task sync.

This is the Obsidian-side companion for the sp-obsidian SP plugin.

---

What it does

• Starts an HTTP server on localhost:27124 when Obsidian opens
• Exposes a small REST API that lets Super Productivity:
  • Search vault files by text
  • Read and write individual note files
  • List files in a vault folder (sorted by last-modified, newest first)
• Protects every endpoint with a Bearer token API key (auto-generated on first install)
• Requires no internet connection — everything is local

---

Installation

The plugin is not yet listed in the Obsidian community plugin registry. Install it manually:

Option A: Copy pre-built files (easiest)

1. Download main.js and manifest.json from the latest release

2. In your file system, create the folder:

   <your-vault>/.obsidian/plugins/super-productivity-provider/
   

   Replace <your-vault> with the path to your vault root.

3. Copy main.js and manifest.json into that folder

4. Open Obsidian → Settings → Community Plugins

   • If prompted, click Turn on community plugins to disable Safe Mode

5. Find Super Productivity provider in the list and toggle it on

Option B: Clone and build from source

git clone https://codeberg.org/sinenomine/obsidian-sp-provider.git
cd obsidian-sp-provider
npm install
npm run build

Then copy main.js and manifest.json into your vault's plugins folder as above, or use a symlink for development:

ln -s /path/to/obsidian-sp-provider \
  "/path/to/vault/.obsidian/plugins/super-productivity-provider"

---

Setup

1. Get your API key

1. In Obsidian → Settings → Super Productivity provider
2. Copy the API Key shown (it is auto-generated on first load)
3. Note the Port (default 27124) and Base URL shown: http://127.0.0.1:27124

2. Connect Super Productivity

1. In SP → Settings → Issue Providers → Add Provider → Obsidian
2. Fill in:
   • Base URL: http://127.0.0.1:27124
   • API Key: paste the key from step 1
   • Configure the other fields (Issue source, Vault folder, etc.) — see the sp-obsidian README for details
3. Click Test Connection — it should succeed immediately if Obsidian is open

---

Plugin settings

Setting	Default	Description
Port	27124	The local HTTP port. Change this only if 27124 is already in use. A port change takes effect after an Obsidian restart.
API Key	auto-generated	A random secret used to authenticate SP requests. Click Regenerate to create a new one (you will need to update it in SP too).

---

API reference

All endpoints require the header:

Authorization: Bearer <apiKey>

Method	Path	Description
GET	/	Health check — returns 200 OK with {"status":"ok"}
GET	/vault/{path}	Read a file. Returns JSON {"content": "…", "mtime": 1234567890}
PUT	/vault/{path}	Write/overwrite a file. Body: JSON {"content":"…"} (or plain text as fallback). Creates the file if it doesn't exist.
GET	/vault/{folder}/	List Markdown files in a folder. Returns {"files": [{"name": "…", "mtime": 1234567890}, …]} sorted newest-first.
POST	/search/simple/?query={term}&contextLength={n}	Full-text search across the vault. Returns {"results": [{"filename": "…", "matches": […]}, …]}

All mtime values are Unix millisecond timestamps (JavaScript Date.now() format).

---

Troubleshooting

SP shows "Connection failed"

• Make sure Obsidian is open and the plugin is enabled
• Check that the port in your SP Base URL matches the plugin settings (default 27124)
• On macOS, a firewall prompt may appear the first time — allow the connection
• Try opening http://127.0.0.1:27124/ in a browser while Obsidian is open; you should see {"status":"ok"}

Port already in use

• Another application is using port 27124
• Change the port in the plugin settings, restart Obsidian, then update the Base URL in SP

API key rejected (401 Unauthorized)

• The API key in SP doesn't match what the plugin shows
• Copy the key again from Obsidian → Settings → Super Productivity provider and paste it into the SP provider settings

---

Development

npm install
npm run build        # compile src/main.ts → main.js
npm run build:watch  # watch mode (recompiles on save)
npm run typecheck    # TypeScript type check without emitting

The plugin uses the Obsidian Plugin API and Node's built-in http module (available in the Obsidian desktop app via Electron). No external HTTP library is needed.

---

License

MIT