How it works
One bridge. Three mechanisms. No guessing.
TaskBridge is an execution layer between team tracking and personal planning. It is not a task manager and not an automation platform: it mirrors your assigned Linear issues into Todoist, brokers completion back under rules you chose, and shows its work.
Source of truth
Linear
- Issues assigned to you
- Workflow states, teams, labels
- Never edited, renamed, or deleted
The bridge
TaskBridge
- Rereads both systems
- Plans explicit operations
- Applies through a durable outbox
Your day
Todoist
- One task per mirrored issue
- Your dates, priorities, order
- Personal fields never read
01 · Anatomy
What a bridge is.
A bridge joins one Linear connection to one Todoist project, with a teams-first scope and exactly one lifecycle policy per Linear team.
| Part | Meaning |
|---|---|
| Connection | An OAuth grant to one provider, owned by you. The hosted beta permits one Linear and one Todoist connection per account. Disconnecting deletes the stored token ciphertext immediately. |
| Scope | The Linear teams you selected. Within them, open issues assigned to you. |
| Destination | The Todoist project where mirrors are created. |
| Lifecycle policy | Per team: the state “done” moves an issue to, and where “not done” returns it — its recorded prior state. |
| Task link | The durable record joining one Linear issue to one Todoist task, with state history and cursors. Deleting a bridge removes configuration and history only — never tasks or issues. |
02 · The lifecycle of a change
How a change travels.
Four everyday situations, exactly as the system handles them. Webhook payloads never become writes; they only wake reconciliation.
Forward
You’re assigned an issue.
- Linear delivers a webhook to TaskBridge. The signature is verified against the exact raw body; the per-issue cursor advances.
- Reconciliation wakes, rereads Linear and Todoist, and plans one operation: create a mirror.
- The mirror appears in your chosen Todoist project — title, identifier, and source link from Linear; due date, priority, and order untouched, because they are yours.
Held trueNothing in Linear changed. If the webhook had been lost, the periodic pass (every 5 minutes) would have created the same mirror.
Back across
You check it off in Todoist.
- Todoist’s webhook wakes reconciliation, which rereads both providers — the payload itself is never trusted as state.
- TaskBridge verifies the issue is still eligible: not deleted, unassigned, canceled, or archived, and still in the state observed during planning.
- The issue moves to the one state you chose for that team — say, Shipped — and the prior state is recorded as the only reopening target.
Held trueUn-completing the task returns the issue to exactly the recorded state. No other field in Linear is touched.
Authority
Your team moves the issue.
- Someone reopens the issue in Linear. Reconciliation reopens your Todoist task to match.
- Someone completes the issue in Linear. Your mirror is completed in Todoist.
- If Linear remains completed and TaskBridge never owned that completion, Linear is authoritative: a reopened Todoist task is re-closed rather than guessed into a Linear state.
Held trueLinear stays authoritative for engineering workflow. TaskBridge does not map every Linear status into Todoist — only active and completed.
Failure
A provider says no.
- A write fails or is rate-limited. The operation stays in the durable outbox with an exact next-attempt time.
- Each apply pass drains up to 25 due entries. Before retrying, TaskBridge re-verifies the link, rereads the providers, and discards the write if the world moved on.
- The bridge reports the held state with real counts — pending, retrying, failed, blocked — instead of a spinner.
Held true“Todoist didn’t accept the update (HTTP 429). Retrying at 14:32. Nothing was changed in Linear.”
03 · Deliberately not built
What TaskBridge refuses to do.
The product is opinionated about authority. These are decisions, not roadmap gaps.
Don’t
- No generic field mapping. No workflow builder, no per-status mirroring of every Linear state.
- No editing Linear titles or deadlines — and no deleting anything, anywhere, ever.
- No Todoist-to-Linear issue creation. The bridge is not a capture tool.
- No reading your planning fields. Dates, priorities, comments, and subtasks are never read for decisions.
- No writes driven by webhook payloads. Events may wake work; only reconciliation writes.
Instead
- Two questions per team. What “done” means, and where “not done” returns the issue.
- Mirrors, one way. Source-owned text flows from Linear; your planning stays yours.
- Active / completed only. The one lifecycle both systems truly share.
- Reconciliation as the writer. Both systems reread, explicit operations, durable outbox.
- A personal tool, for now. No organizations, sharing, or team accounts.
Ready to see your own preview?
The wizard shows the exact import before anything is written. The documentation covers setup, security, and the full webhook and reconciliation model.