How /notion‑sync Creates a Read‑Only Pipeline View in Notion

/notion‑sync is a one‑way publishing command that exports your job‑search pipeline state to a Notion database without uploading any document contents, keeping the repository as the single source of truth.

The ai-job-search repository developed by MadsLorentzen provides a suite of Claude Code commands for managing AI‑assisted job applications. Among these, /notion‑sync serves a specific purpose: it creates a glanceable, always‑up‑to‑date view of your ranked jobs and tracked applications that you can access from any device running Notion. This article explains the architecture, setup steps, and privacy guarantees behind this read‑only pipeline view.

One‑Way Data Flow Architecture

The /notion‑sync command implements a strictly unidirectional data pipeline. Understanding this architecture is key to using the feature correctly.

Data Sources and Aggregation

The command aggregates data from two internal sources:

• Ranked job list — produced by the /rank command and stored in tracker.json
• Tracked applications — produced by /apply and /outcome commands

According to the deduplication logic referenced in .claude/skills/upskill/SKILL.md at line 57, jobs that appear in both the ranked list and the applications list are merged into a single row. This prevents duplicate entries for positions you have already applied to.

What Gets Synced (and What Doesn't)

The sync includes only metadata fields:

Synced	Excluded
Job titles	Résumé contents
Company names	Cover letter contents
Role descriptions	Any other document files
URLs	—
Application status	—

As documented in SECURITY.md at line 15, this selective sync respects privacy guarantees by ensuring no personal document contents leave your local repository. The repository remains the authoritative data store.

Notion MCP Integration Setup

The command relies on the official Notion MCP (Managed Cloud Platform) server for authentication and API access.

Prerequisites

Before running /notion‑sync, you must complete a one‑time OAuth configuration:

# Step 1: Add the Notion transport (run once per environment)

claude mcp add --transport http notion https://mcp.notion.com/mcp

# Step 2: Restart your Claude session to pick up the new server

claude session start

# Step 3: Complete OAuth authentication inside the session

/mcp

The command specification in .claude/commands/notion-sync.md at line 31 explicitly warns: "Notion MCP isn't connected. Run claude mcp add … then re‑run /notion‑sync" if this setup is incomplete.

Executing the Sync

Once authenticated, trigger the sync with a single command:

/notion-sync

This reads the current tracker.json state, applies deduplication, and pushes rows to your configured Notion database.

Row Structure and Read‑Only Semantics

Each job or application becomes one row in the target Notion database with the following characteristics:

• Write‑once briefing page — Attached to each row, containing a snapshot of key details
• Repository backlinks — Links point back to the corresponding files in your local repo
• No edit capability — The Notion side has no connection back to the repository; any desired changes must be made locally and then re‑synced

This design creates the read‑only pipeline view: Notion serves as a display layer while all state management happens in the repository.

Comparison with /html‑report

The /notion‑sync command complements rather than replaces the offline reporting lane:

Feature	/notion‑sync	/html-report
Access	Any device with Notion (desktop, web, mobile)	Local machine only
Update mechanism	Re‑run command to refresh	Re‑run command to regenerate
Interactivity	Read‑only, glanceable	Detailed, filterable dashboard
Network requirement	Requires Notion MCP connection	Fully offline

As noted in .claude/commands/notion-sync.md at line 9, /notion‑sync prioritizes ubiquitous access while /html-report prioritizes rich local analysis.

Security and Privacy Guarantees

The feature implements defense‑in‑depth privacy controls:

1. Filename‑only sync — Document paths are referenced, never uploaded
2. OAuth‑scoped permissions — Uses standard Notion MCP authorization flows
3. No bidirectional sync — Eliminates risk of external modifications propagating to your repository

These constraints are intentional design decisions documented across SECURITY.md and the command specification.

Summary

• /notion‑sync creates a one‑way, read‑only view of your job‑search pipeline in Notion
• Only job metadata (titles, companies, URLs, status) is synced—no document contents
• Requires one‑time Notion MCP setup via claude mcp add and OAuth flow
• Each row includes a briefing page with backlinks to repository files
• Changes must be made locally and re‑synced; Notion remains a display layer
• Complements the offline /html-report with cross‑device accessibility

Frequently Asked Questions

What happens if I edit data directly in Notion?

Any changes made directly in Notion are not synchronized back to your repository. The next time you run /notion‑sync, those edits will be overwritten with the current repository state. To make persistent changes, update your local tracker files and re‑run the command.

Can I sync to multiple Notion workspaces?

The current implementation supports one Notion MCP connection per Claude environment. To target a different workspace, you would need to reconfigure the transport with claude mcp add using credentials for that workspace, then restart your session.

Why are my documents not appearing in Notion?

By design, /notion‑sync never uploads document contents. Only filenames and metadata are transmitted. If you need to review full résumés or cover letters, use the repository directly or the local /html-report output. Refer to SECURITY.md line 15 for the privacy rationale.

How do I update the Notion view after applying to new jobs?

Run /notion-sync again after any repository changes—such as running /rank, /apply, or /outcome. The command performs deduplication automatically and refreshes all rows to reflect the current pipeline state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}