Connectors

Your epics and stories live in your project folder as markdown files. That's perfect for you and your agents, and invisible to everyone else. Connectors mirror that work into a tool your team already opens every day: a Notion workspace, an Obsidian vault, or a Linear team.

This page walks you through connecting each one, click by click. No prior experience with API tokens required. Every step says exactly where to go and what to copy.

Everything here is per project. A connector is configured for the project in the current window. Open a different project and you'll set up its connector separately. That's deliberate: two projects can sync to two different places.

Which connector should I pick?

You can only have one connector active per project, so pick the tool your team actually checks.

Two things worth knowing before you choose:

• Documents (your PRD, architecture, brief) sync to Notion and Obsidian only. Linear receives epics and stories, not documents.
• Edits made in the other tool flow back to your stories for Obsidian and Notion. Linear is push-only: treat it as a display window, not a place to edit.

The five steps: the same for every connector

Whichever connector you pick, the flow in the app is identical. Only step 3 differs, because that's where you paste that service's details.

1. Open Settings, File → Settings, or Cmd + , (Ctrl + , on Windows). It opens in its own window, so don't be surprised when it's not part of the main one. Go to Integrations → Sync Providers.
2. Choose your provider from the dropdown. The fields for that provider appear right below it.
3. Fill in the fields: the per-connector sections below tell you exactly where to find each value.
4. Click Save & Configure. You should see "Saved!" appear. Nothing else works until this succeeds. This is the step that stores your details.
5. Click Setup Remote, and wait for "Remote setup complete!". This is the step that actually creates the databases, folders, or labels on the other side.

Once you've saved, four buttons appear (Push, Pull from Remote, Full Sync, and Test Connection) plus a status bar showing when you last synced and how many items are mirrored. Click Test Connection to confirm your details reach the service.

The buttons name your provider. "Push" actually reads "Push to Notion", "Push to Linear", and so on. Same button, just labelled with wherever you're syncing.

Those four buttons only exist after Save & Configure. Until that first save succeeds, the panel shows just the fields, Save & Configure, and Setup Remote, so if you're hunting for Test Connection and can't find it, you haven't saved yet.

Click "Setup Remote" once. For Notion and Linear, every click creates a brand-new set of databases or a new project. Click it twice and you'll have duplicate, empty containers, and Dybs.it will point at the newest one. (Obsidian is safe to re-run. It reuses the folders already there.)

Obsidian only: test before Setup Remote. Do it in this order, Save & Configure, then Test Connection, then Setup Remote. Setup creates the vault folder if it's missing, so a typo in the path silently creates a new folder in the wrong place and everything looks fine afterwards. Testing in between catches the typo with a "Vault not found".

Obsidian: the two-minute one

What you need: the folder path of your Obsidian vault. No account, no token, and Obsidian doesn't even need to be running.

Find your vault path: in Obsidian, click the vault name in the bottom-left corner → Manage vaults, and copy the path shown under your vault. Or just find the folder in Finder / File Explorer and copy its full path.

Fill in:

Then: Save & Configure → Test Connection (you want "Vault exists at …") → Setup Remote. Testing in the middle matters here: Setup Remote creates the folder, so it would happily create a typo'd path and look successful.

What you get, a folder per project inside your vault:

MyVault/
└── MyProject/
    ├── epics/       one file per epic
    ├── stories/     one file per story
    └── documents/   your PRD, architecture, and other artifacts

Edit a file under stories/ in Obsidian, click Pull from Remote in Dybs.it, and the change comes back into your project. (Edits to epics/ and documents/ don't travel back, see how syncing actually works.)

Pull needs Setup Remote to have run. It only reads the project folder that Setup created, so on a vault you've never set up, Pull finds nothing to read.

Notion: for a shared team workspace

What you need: an integration token and a page to put things under. Notion calls its API tokens "integrations", and (this trips up almost everyone the first time) creating the token isn't enough. You must also share your page with it.

Step 1: create the integration (your token).

1. Go to notion.so/my-integrations.
2. Click New integration, give it a name like Dybs.it, pick your workspace, and create it.
3. Copy the Internal Integration Token. It starts with ntn_ or secret_.

Step 2: pick a page and share it with the integration. Create a normal Notion page to hold everything (call it e.g. Project Hub). Open it, click the ••• menu in the top-right → Connections → Connect to → pick the integration you just made.

Don't skip this. A Notion token can only see pages it has been explicitly connected to. Skip it and Setup Remote fails with a permission error, even though your token is perfectly valid.

Step 3: copy the page ID. With that page open, copy its URL. The ID is the long jumble of letters and numbers at the end, after the page title and before any ?:

https://www.notion.so/My-Workspace/Project-Hub-23e9a1b4c5d6478e90f1a2b3c4d5e6f7
                                               └────── this part is the ID ─────┘

Fill in:

A successful Test Connection says "Connected as …". Setup Remote then creates an Epics database, a Stories database, and a Documents page under your chosen page.

Click Setup Remote exactly once. Every click builds a fresh set of databases, so a second click leaves you with duplicate empty ones and Dybs.it pointing at the newest. This is the connector where that mistake is easiest to make.

Notion limits how fast apps may talk to it, so Dybs.it paces itself deliberately. The first push of a big project takes a minute or two. It hasn't frozen.

Linear: for a team already in Linear

What you need: a personal API key and your team's ID. Epics become labels (Epic: …) and stories become issues.

Step 1: create an API key. In Linear: Settings → Security & access → Personal API keys → New API key. Copy it, it starts with lin_api_.

Step 2: get the Team ID. This one is genuinely fiddly. Dybs.it needs the team's long UUID, not the short key you see in issue numbers like ENG-42. With your team open, press Cmd + K (Ctrl + K on Windows), search for Copy model UUID, and run it. Paste that.

Why this matters: Test Connection only checks that your API key works, it never validates the Team ID. So a wrong team ID looks completely fine right up until Setup Remote or Push fails. If you pasted ENG, go back and get the UUID.

Fill in:

Linear is push-only. Editing an issue in Linear and clicking Pull changes nothing locally, Linear labels issues with its own identifiers, so Dybs.it can't tell which story an issue came from. Use Linear to show your work to the team; make edits that need to stick on the Dybs.it side.

How syncing actually works

Sync is not a mirror. Work flows outward freely and comes back through a much narrower channel. Knowing the shape of it saves a lot of confusion later.

Read the arrow weights. The thick arrows are push: everything travels out. There is exactly one dotted arrow coming back, and it is narrow in three separate ways. It carries only stories, only their body and status, and only for items Dybs.it created itself.

Notice what has no return arrow at all: epics and documents. Edit a synced document in Notion, or rename an epic's label in Linear, and that change stays there. It is never copied back into your project.

What each button does

What travels, per connector

Why Full Sync rarely reports a conflict

Full Sync is not "push and pull at the same time". It runs them in order, and that order decides who wins:

So Full Sync is local-first: your copy wins by default, and conflicts mostly never surface. If you actually want to review changes someone made in the other tool, click Pull on its own instead.

Limitations, stated plainly

These are the things that surprise people. None of them are bugs you should report. They are how it currently works.

1. Nothing new comes in. A brand-new issue, page or file created in the other tool never becomes a story in Dybs.it. Sync only updates items it created itself. Your team cannot file work into your board from Notion or Linear.

2. Pull only brings back stories. Not epics, not documents. Their edits are silently discarded on the way back.

3. Push before your first Pull. Pull matches remote items to stories using records written during a push. On a fresh setup there are none, so Pull appears to do nothing until you've pushed at least once.

4. Linear is push-only. Linear labels issues with its own identifiers, so Dybs.it can't tell which story an issue came from. Nothing returns, not text, not status.

5. Status-only moves may not push. Moving a story between statuses without editing its text can leave the remote copy showing the old status. Edit the body too, or change the status in the other tool.

6. A status that can't be written is now reported. Pull writes a returning status into sprint-status.yaml. If that write fails (no sprint file, or the story isn't listed in it) the sync result says so instead of quietly skipping it. (This used to fail silently for every project, because the writer looked in the wrong folders.)

7. One connector per project, and switching starts over. Configuring a second connector replaces the first, including its saved credentials, and it also clears Dybs.it's record of what was synced where, because an issue number means nothing to Notion. The next push to the new tool creates everything fresh. Whatever you'd already pushed to the old tool stays there; Dybs.it just stops tracking it.

8. Don't sync the same project from two places at once. Clicking two sync buttons in the app is safe. They queue. But syncing from the app and from an MCP client (Claude Desktop, Cursor) at the same moment can create duplicates, because those are separate programs that can't see each other's work.

9. Re-pushing is cheap and safe. Unchanged items are detected and skipped, so pressing Push again costs almost nothing.

When both sides changed the same story

If a story changed in both places since the last sync, Dybs.it keeps the most recently modified version and tells you it did so (e.g. "Conflicts: 2"). As shown above, Full Sync's push-first order means this usually resolves in your local copy's favour before the pull phase even looks.

Keep your token out of git

Your connector settings (including your API token in plain text) are saved inside your project at:

<your project>/.dybs/sync-state.json

Dybs.it hides the token in the interface, but the file itself is not encrypted.

Add .dybs/ to your .gitignore before you commit anything. If you've already committed a token, treat it as leaked: revoke it in the service and generate a new one.

Something not working?

Still stuck? Open an issue on the Dybs.it repository with the connector name and what you tried. That's the fastest route to a fix.