notion-sync

name	notion-sync
description	Sync the Notion PAI second-brain (Projects, To-Do, Inbox, Knowledge Base) with the local gbrain knowledge graph. `pull` mirrors Notion into gbrain (down); `push` sends local gbrain edits up to Notion (up-only — a page changed on the Notion side is left for the next pull, never clobbered). Includes interactive first-time init. Use when the user says /notion-sync, init notion sync, sync notion, pull notion, push notion, refresh brain, notion sync status, notion sync conflicts, notion sync doctor, 初始化 notion, 同步 notion, 拉取 notion, 推回 notion, 雙向同步, brain 沒更新, 檢查 notion 同步, notion 衝突. Sub-commands: init, pull, push, conflicts, schedule, status, doctor. Do NOT use for: ad-hoc Notion page edits (use Notion MCP tools like notion-update-page), general gbrain queries (use mcp__gbrain__* directly), or installing gbrain itself (use gbrain CLI per RUNBOOK.md Step 1).
triggers	["/notion-sync","init notion sync","sync notion","pull notion","push notion","refresh brain","notion sync status","notion sync conflicts","notion sync doctor","初始化 notion","同步 notion","拉取 notion","推回 notion","雙向同步","brain 沒更新","檢查 notion 同步","notion 衝突"]
argument-hint	[init|pull|push|conflicts|schedule|status|doctor]
allowed_tools	["Bash","Read","Write","Glob","Grep","AskUserQuestion"]

/notion-sync

Notion PAI ↔ gbrain sync pipeline, packaged as a Claude Code plugin.

Notion is the human interface (source of truth); gbrain is an agent-friendly local mirror with hybrid search and graph traversal. Two one-way directions: pull mirrors Notion → gbrain (down); push sends local gbrain edits → Notion (up). A "bidirectional" sync is just pull then push. The down direction is always pull's job — push never writes gbrain and never overwrites a Notion page that changed since the last sync.

---

Sub-commands

/notion-sync init

Interactive first-time setup. Walks the user through creating .env with all five required keys (Notion token + four DB IDs), validating each as it is collected. Use this instead of asking the user to manually copy .env.example and edit values.

The flow is conversational: ask one thing at a time, validate via API call before moving on, and write .env only once everything checks out.

Step 1 — Detect existing .env and confirm intent

test -f "$CLAUDE_PLUGIN_ROOT/.env" && echo "EXISTS" || echo "MISSING"

If EXISTS, use AskUserQuestion to ask whether to (a) back up to .env.bak.<timestamp> then overwrite, (b) keep existing and exit, or (c) abort. If MISSING, proceed.

If user picks "back up", run:

cp "$CLAUDE_PLUGIN_ROOT/.env" "$CLAUDE_PLUGIN_ROOT/.env.bak.$(date +%s)"

Step 2 — Collect and validate the Notion token

Ask the user in chat (NOT via AskUserQuestion — token paste is long free text, not a multiple choice):

"Open https://notion.so/my-integrations, create or open an integration, and paste the Internal Integration Secret here (starts with secret_ or ntn_):"

Wait for the user's next message. Take the pasted value as NOTION_TOKEN. Validate immediately:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Notion-Version: 2022-06-28" \
  https://api.notion.com/v1/users/me

Expected: 200. If 401, the token is wrong — ask user to re-paste. If any other code, report it and let the user decide.

Step 3 — Collect the four NOTION_DB_* IDs

For each of the four databases (Projects, To-Do, Inbox, Knowledge Base), ask in chat:

"Paste the Notion page URL OR the 32-character UUID for the Projects database:"

Accept either form. Extract the UUID:

echo "<USER_INPUT>" | grep -oiE '[a-f0-9-]{32,36}' | tr -d '-' | tail -c 33 | head -c 32

This pulls the last 32 hex chars (whether the input is a URL with title prefix, a UUID with dashes, or a bare UUID). Reformat with dashes at positions 8/12/16/20:

UUID_RAW=<the 32-char output>
echo "${UUID_RAW:0:8}-${UUID_RAW:8:4}-${UUID_RAW:12:4}-${UUID_RAW:16:4}-${UUID_RAW:20:12}"

Validate the database is reachable AND the integration is shared with it:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Notion-Version: 2022-06-28" \
  "https://api.notion.com/v1/databases/<FORMATTED_UUID>"

Expected: 200. If 404, either the UUID is wrong OR the integration is not shared with this database — tell the user to go to Notion (DB page > ... > Connections > Add) and re-validate. Do not move on until 200.

Repeat for Todo, Inbox, Knowledge.

Step 4 — Optional: install the scheduled task

Use AskUserQuestion:

"Install Windows Task Scheduler entry for automatic 15-minute sync?" Options: "Yes, every 15 min" / "Yes, every 5 min" / "No, I'll run manually"

If yes, after writing .env (Step 5), call install-task.ps1 with the chosen interval.

Step 5 — Write .env

Claude Code's built-in guard blocks the Write/Edit tools on .env files, so compose the file via a shell heredoc instead. The only secret is the user-pasted token; the DB IDs and URLs are not sensitive.

cat > "$CLAUDE_PLUGIN_ROOT/.env" <<EOF
NOTION_TOKEN=<collected>
NOTION_DB_PROJECTS=<formatted UUID>
NOTION_DB_TODO=<formatted UUID>
NOTION_DB_INBOX=<formatted UUID>
NOTION_DB_KNOWLEDGE=<formatted UUID>

# Optional — gbrain HTTP lock-free sync (token = OAuth access_token, not gbrain_cs_)
# GBRAIN_HTTP_URL=http://localhost:7432
# GBRAIN_HTTP_TOKEN=
EOF

Step 6 — Build and verify

cd "$CLAUDE_PLUGIN_ROOT" && bun install --ignore-scripts && bun run build
node scripts/doctor.mjs

All doctor checks should PASS (five env-key checks + gbrain/Notion probes). If anything fails, report it and offer to re-run the relevant step.

Step 7 — Optional first sync

Use AskUserQuestion:

"Run the first sync now? (one-way pull, all four databases)"

If yes:

bun scripts/sync-pull.mjs

(Environment verification is folded into /notion-sync doctor — run it any time to confirm .env, gbrain, and Notion connectivity.)

---

/notion-sync pull

One-shot sync from Notion into gbrain. Also seeds sync-state.db so a later /notion-sync push has a baseline.

Step 1 — Dry-run first

bun "$env:CLAUDE_PLUGIN_ROOT/scripts/sync-pull.mjs" --database <db-name> --dry-run

<db-name> is one of: projects, todo, inbox, knowledge.

Review the listed pages. Stop here if the count looks wrong (token expired, wrong DB ID, or integration not shared).

Step 2 — Execute pull

bun "$env:CLAUDE_PLUGIN_ROOT/scripts/sync-pull.mjs" --database <db-name>

The script fetches all pages, extracts writable properties into frontmatter (src/notion-properties.ts), converts Notion blocks to Markdown (src/block-converter.ts), upserts to gbrain (src/gbrain-adapter.ts), and records the post-write baseline in sync-state.db.

Step 3 — Confirm

gbrain list --limit 1000 | wc -l

Compare against Step 1's dry-run count.

---

/notion-sync push

One-way push: send local gbrain edits up to Notion. The Notion → gbrain direction is pull's job — push never writes gbrain and never overwrites a Notion page that changed since the last sync.

Step 1 — Dry-run first

cd "$CLAUDE_PLUGIN_ROOT" && bun run push:dry

Prints the classification for every page without writing anything. Review before executing.

Step 2 — Execute push

cd "$CLAUDE_PLUGIN_ROOT" && bun run push

For each gbrain page (only those whose frontmatter source is one of projects / todo / inbox / knowledge), scripts/sync.mjs compares the live Notion state and the gbrain page against the sync-state.db baseline:

• to_notion — only the gbrain side changed → push the edit to Notion (properties via pages.update; body only if the Notion page has no converter-unsupported blocks, else properties sync and a conflict is recorded).
• created — a gbrain page with no notion_page_id is created in Notion (allowed only into Inbox or Knowledge Base).
• skip — only the Notion side changed, or nothing changed. Left untouched; run /notion-sync pull to bring Notion's update down to gbrain.
• diverged (conflict) — both sides changed since the last sync. Neither side is written; the page is recorded as a conflict. Run /notion-sync pull to refresh gbrain, then re-push.

Step 3 — Review conflicts

If the summary reports conflict > 0, run /notion-sync conflicts.

Requires a prior /notion-sync pull to seed the baseline.

---

/notion-sync conflicts

List sync conflicts recorded in sync-state.db.

Step 1 — List

cd "$CLAUDE_PLUGIN_ROOT" && bun scripts/sync.mjs --conflicts

Two kinds get recorded during push:

• diverged — both Notion and gbrain changed since the last sync. The backup_path reads (diverged — run pull, then re-push).
• body-unsupported — a gbrain body edit could not be pushed because the Notion page contains converter-unsupported blocks; the local body is backed up to .conflict/ (backup_path points to that file).

Step 2 — Resolve manually

For a diverged page, run /notion-sync pull to refresh gbrain from Notion, then re-push your edit. For a body-unsupported page, open the .conflict/ backup and reconcile by hand. The full audit trail is appended to ~/.notion-sync/conflicts.jsonl.

---

/notion-sync schedule

Install or remove a Windows Task Scheduler entry that runs /notion-sync pull on a fixed interval (default 15 minutes).

Step 1 — Install

powershell -ExecutionPolicy Bypass -File "$env:CLAUDE_PLUGIN_ROOT\scripts\install-task.ps1" -Interval 15m

Creates Task Scheduler entry gbrain-notion-sync running as the current user.

Step 2 — Check status

powershell -ExecutionPolicy Bypass -File "$env:CLAUDE_PLUGIN_ROOT\scripts\install-task.ps1" -Status

Reports next run time and last result code.

Step 3 — Uninstall

powershell -ExecutionPolicy Bypass -File "$env:CLAUDE_PLUGIN_ROOT\scripts\install-task.ps1" -Uninstall

Windows only. macOS/Linux scheduler support is planned for v0.2.

---

/notion-sync status

Show current sync state.

Step 1 — Brain contents

gbrain list pages

Step 2 — Scheduled task state

schtasks /Query /TN gbrain-notion-sync /V /FO LIST

Reports Next Run Time, Last Run Time, Last Result (0 = success).

Step 3 — Unresolved conflicts

cd "$CLAUDE_PLUGIN_ROOT" && bun scripts/sync.mjs --conflicts

Lists diverged / body-unsupported conflicts pending manual resolution (empty if none).

---

/notion-sync doctor

Comprehensive health check.

Step 1 — Run

node "$env:CLAUDE_PLUGIN_ROOT/scripts/doctor.mjs"

Checks (in order):

1. gbrain doctor exit code is 0
2. .env exists and all five required keys are non-empty
3. Notion API reachable: GET each of the four NOTION_DB_* IDs
4. gbrain put --help succeeds (CLI alignment)
5. ${CLAUDE_PLUGIN_ROOT}/dist/ exists (build artifact present)

Exit code 0 if all pass, 1 if any check fails.

---

Gotchas

• Engine is Supabase Postgres + pgvector (migrated 2026-06-07; local PGLite retired because its WASM runtime aborts on Windows + bun — gbrain #939/#1502). Any gbrain CLI that runs schema/DDL needs GBRAIN_DIRECT_DATABASE_URL set to the Supabase session pooler URL (port 5432); without it gbrain auto-derives the IPv6-only db.<ref>.supabase.co host and dies with getaddrinfo ENOTFOUND. Persisted at user level via setx. Plain page upserts (pull/push) go through the pooler (6543) and do not need it; only DDL/maintenance does.
• Windows bun install against gbrain dependencies fails without --ignore-scripts (gbrain issue #218 — bash-only postinstall scripts).
• The old gbrain jobs submit gbrain_sync syntax is outdated. Use the Task Scheduler entry installed by /notion-sync schedule instead.
• On the Supabase Postgres engine, gbrain jobs work (long-running worker) IS supported (it was the retired local PGLite engine that had no daemon supervisor). Periodic pull is still simplest via the Task Scheduler entry from /notion-sync schedule.
• Notion API rate limit is 3 req/sec. src/notion-client.ts caps at 2 req/s to leave headroom — do not raise without testing.
• .env, sync-state.db, and .conflict/ are in .gitignore. Never commit them.
• gbrain put is the correct CLI command, not gbrain page put (alignment fix shipped in commit c814887).
• pull and push run under bun, not node — they load sync-state.js, which imports bun:sqlite. doctor stays on node.
• Push never creates a Notion property or select option. A frontmatter value not present in the live Notion schema is skipped with a warning.
• Body push is blocked when the Notion page contains converter-unsupported blocks (callout, table, toggle, ...) — properties still sync, and the divergence is recorded as a conflict.
• gbrain get / gbrain list print human-readable text, not JSON — there is no --json flag (see docs/gbrain-cli-signatures.md).

Roadmap (not yet shipped)

• v0.4 — Block type expansion (callout, toggle, database mention, file, image)

(Auto-embedding is already provided by gbrain — it embeds on every put via the key in ~/.gbrain/config.json; no separate sync step needed.)

Reference

• Setup guide: RUNBOOK.md
• Compatibility log: docs/compat-matrix.md
• gbrain repo: https://github.com/garrytan/gbrain

2026-05-25 HTTP/OAuth 實測備註（給代理）

當使用者改走 gbrain serve --http 時，先套用以下規則：

• Admin UI 用 http://localhost:7432/admin/，不是 /admin
• 不要硬猜 token endpoint；先看 /.well-known/oauth-authorization-server
• 目前實測 token endpoint 是 http://localhost:7432/token
• GBRAIN_HTTP_URL 應填主機根位址，例如 http://localhost:7432，不要加 /mcp
• GBRAIN_HTTP_TOKEN 必須是 OAuth access_token
• 若 .env 內是 gbrain_cs_...，那是 client_secret，不是 token；同步會回 401 invalid_token
• 若同步停在第一頁且最後一行是 Wrote ... created_or_updated，優先檢查 adapter 是否又回退到本機 CLI 讀頁面

2026-05-25 已修正 src/gbrain-adapter.ts，讓 HTTP 模式下的 getPage() 也走 MCP get_page，避免 PGLite lock / 等待卡住。

2026-06-08 引擎遷移備註（給代理）

gbrain 已從 PGLite 遷到 Supabase Postgres + pgvector（engine=postgres）。對本 skill 的影響：

• HTTP 模式現在是「較乾淨」而非「避免鎖必須」：Postgres 無單寫入者鎖，CLI（gbrain put）與 serve 可並行寫。仍建議 HTTP 模式，因為 sync 程序就不需要自己的 DB 憑證。
• HTTP 模式 .env：GBRAIN_HTTP_URL=http://localhost:7432（根，不加 /mcp）、GBRAIN_HTTP_TOKEN=<OAuth access_token>（非 client_secret）。
• CLI 模式下，pull/push 的頁面 upsert 走 pooler（6543）即可；只有 DDL/維護命令需要 GBRAIN_DIRECT_DATABASE_URL（session pooler 5432），否則 getaddrinfo ENOTFOUND。
• 本機已無 ~/.gbrain/brain.pglite（2026-06-07 刪除），資料全在 Supabase（ap-northeast-1）。