This is how I wired the reMarkable into the vault so anything I write in one folder shows up automatically, ready for the assistant to read. No exporting, no copying files around.

If you would rather not build this by hand, skip to the build brief at the end. It is a single block you can paste into your own AI coding agent, and it has enough detail for the agent to build the whole thing without my code.

The idea

The flow goes one direction, reMarkable to Obsidian.

reMarkable "Wiki" folder
      |  (a job checks it on a schedule)
      v
render changed notebooks to page images
      |
      v
write raw/remarkable/<note>.md + page PNGs into the vault
      |  (normal Obsidian Sync)
      v
every device + the assistant, which transcribes the handwriting into a wiki page

A small job runs on a timer. It looks at one folder on my reMarkable, renders any new or changed notebooks to page images, and drops them into the vault as a markdown file plus PNGs. Obsidian Sync carries them everywhere, and the assistant reads the images when it builds wiki pages.

The design choice that took the most thought: the sync job does not transcribe handwriting. It only captures the image. Transcription happens later, when the assistant reads the page. There are two reasons for that split.

The image is the honest record. Handwriting recognition makes mistakes, and my raw/ folder is immutable by contract, so a bad transcription written there would be permanent. Keeping the rendered image as the source of truth means the text is always regenerable: if a transcription reads wrong, I re-run the assistant against the picture, I never edit the source. The second reason is cost. My vault is already maintained by an assistant that can read images, so transcription adds nothing. The picture is the truth, the text is a view.

What you need

• A reMarkable with cloud sync (Connect or the free tier).

• An Obsidian vault that syncs to a machine that stays on. I run mine on a small VPS with the vault synced onto it, but a home server or an always-on desktop is fine.

• Python 3.11 or newer on that machine.

• Code that can read the reMarkable cloud and render .rm files to images. I built on the open-source remarkable-mcp project and the rmscene library, which already handle the cloud API and the ink-to-image rendering. Rendering ink needs libcairo on the box.

The capture, step by step

1. Pick one folder as the inbox

I made a top-level folder called Wiki on the reMarkable. A notebook syncs to Obsidian only if it lives in that folder. Moving a note into Wiki is how I say “this one belongs in my knowledge base,” the same gesture as saving an article to a read-later app. Subfolders under it are included too.

This is deliberate. The alternative, syncing every notebook, would fill an immutable source folder with grocery lists and idle sketches. One folder keeps it intentional.

2. Register a dedicated device token

The job authenticates to the reMarkable cloud as its own device, separate from your tablet and any other integration. Get a one-time code from my.remarkable.com/device/desktop/connect and exchange it for a device token once. Store that token in a file with 0600 permissions on the machine. The job reads it at runtime, so the secret never appears in a command line, a unit file, or a log.

A separate device slot matters: re-pairing one client should not revoke the others.

3. Detect what changed

Each run lists the notebooks in the Wiki folder and compares them against a small state file kept on the machine, outside the vault. The state maps each notebook to a content hash built from its page-blob hashes. From that comparison the job sorts every notebook into one of: new, changed, unchanged, renamed, or dropped from the folder.

Only new and changed notebooks get re-rendered. Unchanged ones are skipped, so a run with nothing new does no work and costs nothing. A rename moves the existing files instead of re-rendering. A notebook you pull out of the folder is left in place in the vault, never deleted automatically, because the source folder is append-only by design.

4. Write the bundle

For each new or changed notebook the job renders every page to a PNG and writes two things into the vault:

• attachments/remarkable/<slug>/page-001.png, one image per page.

• raw/remarkable/<slug>.md, a markdown file with frontmatter and one section per page.

The markdown looks like this:

---
source_type: remarkable
remarkable_id: a6cb520e-2611-41ae-...
title: Sprint Planning - 116 - June 01
remarkable_path: /Wiki/Sprint Planning - 116 - June 01
page_count: 1
content_hash: “sha256:7256edcd...”
synced: “2026-06-01T18:53:37Z”
partial: false
---

## Page 1

![[remarkable/sprint-planning-116-june-01/page-001.png]]

The writes are atomic: images first, then the markdown via a temp file and a rename, so Obsidian Sync never sees a half-written note. If a page fails to render, the bundle is marked partial: true and the next run retries it, rather than writing a gap that looks finished.

5. Run it on a timer

On Linux I use a systemd timer. The service runs a small wrapper that loads the token and config, then calls the sync once. The wrapper keeps the token out of the unit file:

#!/usr/bin/env bash
set -a
REMARKABLE_VAULT_SYNC_TOKEN=”$(cat /path/to/token.json)”
REMARKABLE_VAULT_ROOT=”/path/to/your/vault”
REMARKABLE_VAULT_SYNC_STATE=”/path/to/state.json”
REMARKABLE_SYNC_FOLDER=”Wiki”
set +a
exec /path/to/venv/bin/remarkable-vault-sync “$@”

# remarkable-vault-sync.timer
[Timer]
OnCalendar=hourly
Persistent=true
RandomizedDelaySec=120

[Install]
WantedBy=timers.target

Hourly is plenty for notes. Run it once by hand with a dry-run flag first to confirm it sees the folder before you trust the schedule.

Teaching the assistant to read the bundles

The capture job stops at the image. Turning a page into a wiki entry is the assistant’s job, so I gave it one rule in the vault’s operating document (the file the assistant reads before it works). The rule, in plain terms:

When a file appears in raw/remarkable/, read the page images, transcribe the handwriting, pull in any typed text, and create a source page in wiki/. Record the bundle’s content_hash on that page. If the hash later changes, re-transcribe. The image is the ground truth: fix a bad transcription by re-reading the image, never by editing the source.

That last line is the whole contract. The source folder holds images and stays immutable. The wiki folder holds the assistant’s transcriptions and is fully regenerable.

Using it day to day

1. Write on the reMarkable.

2. When a notebook is worth keeping, move it into the Wiki folder (or start it there).

3. Within the hour it shows up in Obsidian as a page with the image embedded.

4. Ask the assistant to ingest new sources. It transcribes the handwriting and files a linked wiki page.

Edits work too. Add pages to a notebook that already synced, and the next run notices the content changed and refreshes the bundle, which flags the wiki page for re-transcription.

A few decisions worth copying

I store the rendered image, not just text. Diagrams, arrows, and crossed-out ideas survive, and I can always re-transcribe from a higher-fidelity source.

I write straight into the synced vault folder rather than pushing through git or an API. The machine that runs the job already has the vault on disk via Obsidian Sync, so writing a file and letting Sync propagate it is the simplest path. One writer, one propagation mechanism, no merge conflicts.

I keep state outside the vault. The state.json that tracks hashes is machine-local. It is not source material, so it does not belong in the synced folder.

Caveats

Current reMarkable firmware writes a notebook format that open-source readers do not fully parse yet. In practice rendering still produces a usable page image, with an occasional warning. Pure-text extraction from ink is unreliable, which is exactly why I lean on a vision-capable assistant for transcription instead of OCR.

If you mostly write typed notes or annotate PDFs, the text comes through directly and you may not need the assistant step at all.

Build it with your own AI agent

If you have an AI coding agent (Claude Code, Cursor, and the like), paste the block below into it. It is self-contained: the agent can build the tool from this alone, without my code. It will ask you for your vault path and how you want to schedule it, then build it test-first.

Build me a small tool that mirrors handwritten reMarkable notes into my Obsidian
vault. You do not have an existing codebase; build it from this spec. Ask me for
my vault path and anything else you need before you start.

Goal: a capture-only command-line job that, on a schedule, copies notebooks from
ONE reMarkable cloud folder into my Obsidian vault as page images plus a markdown
file. It must NOT transcribe handwriting. A separate AI step reads the images
later. The rendered image is the source of truth; the transcription is a
regenerable view.

Stack and building blocks:
- Python 3.11+. No web framework, no database. State is one small JSON file.
- Render reMarkable .rm pages to PNG with the open-source `rmscene` library
  (https://github.com/ricklupton/rmscene ; needs libcairo on the machine).
- List documents and download a notebook's blob bundle with the reMarkable sync
  v3 cloud API. The open-source `remarkable-mcp` project
  (https://github.com/SamMorrowDrums/remarkable-mcp) has a working client you
  can reuse or copy: device registration from a one-time code, a cloud client
  with get_meta_items() and download(doc), and page renderers.

Configuration via env vars: a reMarkable device token (registered once via
my.remarkable.com/device/desktop/connect), the Obsidian vault root path, a state
file path that lives OUTSIDE the vault, and the folder name to watch (default
"Wiki").

Behavior:
1. List documents under the named top-level reMarkable folder, recursively
   (include subfolders). Folders are matched by name; error if the name is
   missing or ambiguous at the top level.
2. content_hash for a document = "sha256:" + sha256 over the sorted list of
   "fileid=blobhash" pairs from its blob entries. Order independent.
3. State JSON shape: { remarkable_id: {content_hash, filename, title, synced} }.
   Classify each in-scope doc against state:
   not in state -> new; content_hash differs -> changed; same hash but different
   title -> renamed; else unchanged. State ids no longer in the folder -> dropped
   (leave their vault files in place, never auto-delete).
4. Filenames: a kebab-case slug of the title; on collision append a short suffix
   from the id. Docs already in state keep their recorded filename so a same-title
   collision can never overwrite a sibling.
5. For new and changed docs: download the notebook, render each page to a PNG,
   extract any typed or PDF text. Write atomically, images first then the markdown
   via temp-file-plus-rename so a half-written note is never visible:
   - attachments/remarkable/<slug>/page-001.png, one per page
   - raw/remarkable/<slug>.md with YAML frontmatter (source_type: remarkable,
     remarkable_id, title, remarkable_path, page_count, content_hash, synced,
     partial) and a body of "## Page N" sections, each embedding
     ![[remarkable/<slug>/page-NNN.png]] plus any extracted text.
   If a page fails to render, set partial: true, record the failed page numbers,
   and store a sentinel content_hash (the real hash plus ":partial") so the next
   run retries it instead of treating the gap as finished.
6. Renamed docs: move the existing .md and attachments folder to the new slug and
   rewrite the embed paths inside the .md. Do not re-render.
7. Save state. Print a one-line summary: new/changed/unchanged/renamed/partial/
   dropped/errors. Exit non-zero if any doc errored. Handle each doc in its own
   try/except so one failure does not stop the run.
8. Add a --dry-run flag that classifies and logs planned actions but writes
   nothing and downloads nothing (classification needs only metadata).
9. Never put the token in logs, command-line args, or the markdown. Read it from
   a 0600 file at runtime.

Deployment: a systemd timer or cron entry that runs it hourly. It must run on a
machine that has the Obsidian vault on disk via Obsidian Sync, so writing files
and letting Sync propagate them is the only write path. No git, no REST API.

Tests (write them first, mock the reMarkable client so no network or libcairo is
needed): slug and collision suffix; the classify state machine across all five
outcomes; atomic write leaves no partial markdown if it fails mid-write; --dry-run
writes nothing; a second run skips unchanged docs, overwrites a changed one, and
moves a renamed one without duplicating.

When the tool works, give me one rule to paste into my vault assistant's
instructions: "When a file appears in raw/remarkable/, read the page images,
transcribe the handwriting, include any typed text, and create a source page in
wiki/. Store the bundle's content_hash on that page; re-transcribe when it
changes. The image is the ground truth: never edit raw/."

Confirm the stack, ask me for my vault path and schedule preference, then build it.

If your agent asks where the reMarkable cloud API or the rendering lives, point it at remarkable-mcp and rmscene. Both are public. The rest of the logic above is the part you actually need to write.

The result is quiet, which is the point. I write on the reMarkable, drop the notebook in one folder, and it becomes part of a searchable, linked knowledge base without me thinking about it.

You know the kind. You install it, you click the button, your prompt becomes 200 words longer but not actually better. Someone wrapped “make this better” around an API call and called it a product. I tried a few of them. They all felt like the same extension with different color schemes.

At some point I just asked ChatGPT directly: is it even possible to build one of these that actually works? Even if it’s a wrapper, something that uses real prompt engineering techniques.

That conversation went deeper than I expected. We talked about step-back abstraction, where you have the model zoom out before drilling in. Self-refinement, where the model critiques its own output before handing it back. Chain-of-thought, which everyone has heard of and nobody implements properly. And the thing I cared about most: that the same prompt should be structured differently for ChatGPT, Claude, and Gemini, because they reward different things.

By the end of that chat I had a clear picture of what was missing in the existing extensions. I asked ChatGPT to write me a full PRD. Dropped the PRD into Replit. Replit built a working MVP in one shot.

The functionality was solid. The prompts coming out the other side were noticeably better than anything I’d tried. But the landing page looked like a generic Replit app, because it was a generic Replit app.

I opened Claude Code next, gave it the codebase, told it to do the landing page properly. What it produced looked nothing like the Replit version. Better in a way that’s hard to articulate but obvious when you put them side by side. While Claude Code was in the codebase, it offered up two things I hadn’t thought to ask for: follow-up detection, so the extension can tell when you’re refining a prompt versus starting a new one, and per-platform optimization that adjusts the improvement strategy depending on which AI you’re prompting. Both of those ended up being core features. I would not have shipped them on my own.

My workflow ended up being Replit for hosting and the database, Claude Code for feature work and design, Git as the connective tissue. Push from one, pull from the other. I’m sure there’s a better setup. This one has been frictionless enough that I haven’t gone looking.

I used the extension myself for a few weeks before doing anything else with it. Every time the improvement came back feeling slightly off, I’d dig into the pipeline and figure out what was producing the bad output. Most of the fixes involved going back to Claude, researching a technique I’d half-implemented, and putting in the real version. The output now runs a 3-step pipeline: figure out what the user is actually trying to ask, generate a real improvement, then self-critique and refine. Three model calls, one button click.

At some point Claude suggested I should monetize it. Fair enough. Stripe integration, free tier where you bring your own API key, Pro tier where the platform key is included. Claude Code handled the whole setup. Webhooks, subscriptions, trial flow, feature gating. It also walked me through the Chrome Web Store submission, which is more bureaucratic than you’d think the first time through.

Subscribe now

Here’s the part I keep getting stuck on. The distance from “I want this thing to exist” to “shipped product with Stripe payments” used to be a real distance. Months of work I didn’t want to do. Now most of what slowed me down was deciding what I actually wanted. The implementation showed up when I asked for it.

I don’t think that’s a hot take at this point. But it does change what’s worth sitting on. Ideas you’ve been mentally filing under “I would build that if I could” are probably closer than you think.

If you want to try it, the extension is at aipromptcopilot.com. It works on ChatGPT, Claude, Gemini, and Grok. Free with your own API key, seven-day trial on Pro if you want it with the included platform key. Source is on GitHub: github.com/khalid-hasan/ai-prompt-copilot-extension.

Chrome Extension

If you’ve built something similar with a better workflow than mine, I want to hear about it.

The goal

A personal AI wiki. Vault on my phone and desktop (Obsidian Sync), Claude can query and maintain it from any device. Specifically:

• The vault should be the same vault I already use — not a copy, not a fork

• Mobile Claude must work, not just desktop

• OAuth-gated; only I can authenticate

• Cheap (under €10/month on top of what I already pay for Obsidian Sync)

• Reliable enough that I’d trust it with two years of notes

What I tried first

The most prominent existing project for this was benpeter/obsidian-cloud-mcp — a Terraform-driven deployment of an Obsidian MCP server on Hetzner with a Cloudflare Worker doing OAuth. It got me far enough to deploy a VPS, configure the Worker, and set up the GitHub OAuth flow, which gave me a solid mental model of the moving parts.

What I hit was an architecture-vs-dependency mismatch. The repo configures the underlying MCP server (cyanheads/obsidian-mcp-server) with MCP_AUTH_MODE=introspection, but the cyanheads config schema only accepts jwt or oauth. The result: the MCP container crashed on startup with:

Error: Invalid environment configuration.
{"MCP_AUTH_MODE":["Invalid enum value. Expected 'jwt' | 'oauth', received 'introspection'"]}

So the token-introspection layer the design describes isn’t backed by code in any cyanheads commit I could find — looks like an architectural plan that didn’t get fully wired up end-to-end before the repo was published. Not malicious, just incomplete. The Terraform and Cloudflare Worker pieces of benpeter are genuinely useful as scaffolding (I ended up forking and using them), but the OAuth-to-introspection path needed a different approach.

A bunch of “let me just patch this one thing” attempts later, I stepped back to rethink the design.

The pivot

I ran a bunch of research in parallel — what’s the MCP server landscape actually look like in May 2026, what’s the canonical way to put OAuth in front of a remote MCP server, what are people who’ve successfully deployed this using.

Two findings unlocked everything:

1. Cloudflare shipped “Managed OAuth for Access” in 2025. It turns Cloudflare Access itself into an RFC-compliant OAuth 2.1 authorization server for any HTTP service behind it. This didn’t exist when most existing writeups were drafted, and it eliminates most of the custom OAuth proxy code I’d been trying to debug. Free up to 50 users.

2. There’s a purpose-built headless Obsidian MCP server I’d missed: nweii/obsidian-remote-mcp. Six weeks old, 2 stars at the time, but ~150 lines of audit-able OAuth code, standards-correct (PKCE, RFC 8414, RFC 9728), and built to run without the Obsidian desktop app. Just reads markdown off disk. Claude’s callback URI is the default redirect.

Combined with obsidian-headless — Obsidian’s official Node CLI for headless Sync, shipped in Feb 2026 — the stack basically writes itself.

What I ended up building

Claude.ai (desktop / web / mobile)
   │  OAuth (Cloudflare Access Managed OAuth, GitHub IdP, email allowlist)
   ▼
Cloudflare Access
   │
   ▼  Cloudflare Tunnel (no public IP on the VPS)
   ▼
Hetzner cx23 VPS (€4/mo)
   ├── nweii/obsidian-remote-mcp (Docker, :3456 localhost-only)
   ├── obsidian-headless (systemd service: ob sync --continuous)
   └── 5-min cron: git mirror to a private backup repo

Total new spend: ~€4/month on top of my existing Obsidian Sync. The Cloudflare side is free tier.

The unexpected trick

Most “Cloudflare Access + MCP” writeups protect the whole hostname with Access. That’s the obvious move. It breaks.

Why: Claude.ai’s MCP connector OAuth flow involves multiple endpoints with different requirements:

• /.well-known/oauth-protected-resource — must be publicly readable (MCP spec)

• /authorize — needs a browser to complete user auth

• /oauth/token — called from Claude.ai’s backend, no browser context, no Access cookies

• /mcp — carries the MCP-issued bearer, not an Access JWT

Putting Access on the whole hostname blocks the public discovery endpoint AND blocks Claude.ai’s backend from token exchange. The OAuth flow stalls.

So I protected only /authorize with Cloudflare Access. Everything else stays open at the Cloudflare edge, but /mcp is still gated by nweii’s own opaque-token auth. The split:

PathGated byWhy/.well-known/*nothingMCP spec requires public discovery/authorizeCloudflare AccessWhere user identity is established (GitHub + email allowlist)/oauth/tokennothingBackend-to-backend code exchange; nweii validates the code single-use/mcpnweii’s opaque bearerToken issued only after the Access-gated /authorize succeeds

Two layers, zero custom code, clean separation: Access = who are you, nweii = here’s your session.

I haven’t seen this written up anywhere else. Most guides do all-or-nothing.

What’s novel vs. what’s not

Honest take:

• The overall pattern (Tunnel + Access + MCP server for Obsidian) — not novel. Several people have done variants. jimprosser/obsidian-web-mcp is the closest comparable. JonHollander has an all-Cloudflare variant using Containers + R2. Cloudflare’s own docs publish this as a reference architecture now.

• The specific component combination (nweii + obsidian-headless + CF Access Managed OAuth + path-specific protection) — almost certainly a one-of-one. The pieces are all from the last 12 months; nweii has tens of users at most.

• The path-specific Access protection trick — appears to be the actually novel contribution.

• The git-mirror safety net for obsidian-headless — borrowed from rolle.design (2024). Not novel but worth knowing about because obsidian-headless has several open data-loss bugs at time of writing (#19, #21, #25, #27) and you genuinely want a backup ready.

What I wrote up

Full deployment guide at: https://github.com/khalid-hasan/obsidian-mcp-cloudflare

It’s not a tool; it’s a deployment guide. Terraform for the Hetzner VPS, cloud-init for the base image, docker-compose for nweii, systemd unit for ob sync --continuous, a script that wires up the Cloudflare Tunnel + Access via API. MIT licensed. Honest about the tradeoffs (which underlying components have open bugs, when this is the wrong choice vs alternatives, what the threat model does and doesn’t cover).

Use it if you’re already paying for Obsidian Sync and want vault changes from your phone to propagate to a server in real time. Use jimprosser/obsidian-web-mcp if you want a more polished single-package solution. Use Cloudflare’s Containers + R2 reference if you’d rather not run a VPS at all.

Takeaways for anyone going down this path

1. Check that your dependencies actually implement the features your design depends on. A four-hour debugging session would have been a five-minute grep of the underlying server’s source if I’d been more skeptical of the README’s claims.

2. Cloudflare Access Managed OAuth changes the math for anyone putting auth in front of a remote MCP server. If your design was sketched in 2024, revisit it.

3. Path-specific Access protection is the missing trick most writeups don’t mention. Whole-hostname Access doesn’t compose with MCP’s OAuth flow.

4. obsidian-headless is new and has open data-loss bugs. Pair it with a git mirror. Five minutes of cron config saves you from a vault-wide deletion event.

5. Audit auth code in young repos before deploying. nweii/obsidian-remote-mcp was six weeks old when I deployed it. Reading 290 lines of TypeScript took 15 minutes and gave me real confidence (or would have caught real bugs).

Built this with Claude Code doing most of the typing.