zeromdDeepSeek Harness plugin

zeromd

中文 | English | 日本語

Local-first Obsidian multi-device sync. Zero cost. Zero signup. Zero maintenance.

Why This Exists

The most AI-native knowledge base isn't a SaaS product with an API. It's a folder of markdown files on your disk.

And .md isn't done evolving — Mermaid already turned plain text into live diagrams. Interactivity might be its next chapter.

Obsidian stores everything as plain .md files. AI tools like Claude Code can read and write your knowledge base directly:

No API   No plugins   No middleware

bash
# Claude Code works with your vault natively
Grep "system design" ~/vault/       # search all notes
Read ~/vault/some-note.md           # read content
Edit ~/vault/some-note.md           # modify content
Glob "**/*.md" ~/vault/             # traverse entire knowledge base

Compare with cloud-based solutions:

	Obsidian vault	Notion
AI access	Read files directly, zero config	API + OAuth + MCP required
Data format	Standard markdown	Proprietary blocks, needs parsing
Read/write speed	Local I/O, milliseconds	Network requests + rate limits
Version history	Full Git log of every change	None
Data ownership	Files on your disk	Stored on someone else's server

Local files + standard format = no "integration" needed. It just works.

zeromd simply keeps this local knowledge base in sync across all your devices.

Architecture

mermaid
1graph LR
2    subgraph icloud ["☁️ iCloud — seconds"]
3        direction LR
4        iPhone["📱<br/>iPhone"]
5        Mac["💻<br/>macOS"]
6    end
7
8    subgraph git ["🍀 Git — every 5 min"]
9        direction LR
10        GitHub["🍀<br/>GitHub"]
11    end
12
13    iPhone <--> Mac
14    Mac <--> GitHub
15    GitHub -.->|optional| Windows["🖥️<br/>Windows"]
16
17    style icloud fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
18    style git fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#15803d
19    style iPhone fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
20    style Mac fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
21    style GitHub fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
22    style Windows fill:#94a3b8,color:#fff,stroke:#64748b,stroke-width:2px,stroke-dasharray: 5 5

• macOS ↔ iOS: iCloud auto-sync (seconds)
• macOS ↔ GitHub: Git timed sync (every 5 min, only when changes exist)

Windows users can git clone the repo and use obsidian-git for sync.

Quick Start

Prerequisite: Obsidian with an iCloud vault on your Mac.

bash
bash <(curl -sL https://raw.githubusercontent.com/yuukiLike/zeromd/main/install-remote.sh)

The installer will find your vault, set up Git, let you choose SSH or HTTPS, connect to GitHub, and start syncing.

• 1 vault + gh CLI → creates or connects the repo, then uses your chosen protocol
• Manual setup → pick SSH or HTTPS, then paste the matching repo URL
• No SSH key → HTTPS still works; SSH setup tells you exactly how to fix it

iPhone: Install Obsidian → open the same iCloud vault. Done.

Why gmd Instead of md

Some shell environments define md as an alias (e.g., oh-my-zsh aliases md='mkdir -p'). To avoid conflicts, the primary command is gmd (git + md). If md is not taken in your shell, it works too — both point to the same script.

Verify

Mac → iPhone: Create a note on Mac, it should appear on iPhone within 30 seconds.

iPhone → Mac: Write something on iPhone, it should appear on Mac within 30 seconds.

Git sync: Wait 5 minutes or run gmd sync, then check GitHub for new commits. Run gmd status to see current state.

SSH or HTTPS? zeromd supports both. If you use HTTPS and GitHub rejects your credentials, zeromd now reports that as an HTTPS auth error instead of a generic push failure.

Switched to a new Mac? On this machine's first sync, zeromd checks whether the local vault has already established sync with origin/main. If the local state may conflict, it creates a local zeromd-backup-<timestamp> branch first, then force-resets local main to origin/main.

How Sync Works

iCloud (macOS ↔ iOS): Handled by Apple automatically. Vault lives at ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/<vault>/. Syncs in seconds.

Git (macOS ↔ GitHub): A launchd job runs sync.sh every 5 minutes:

mermaid
1flowchart TD
2    subgraph trigger ["⏰ Every 5 min — launchd"]
3        check{"📂<br/>Any changes?"}
4    end
5
6    subgraph sync ["🍀 Sync pipeline"]
7        stage["➕ git add -A"]
8        commit["💾 git commit"]
9        pull["⬇️ git pull --rebase"]
10        push["⬆️ git push"]
11    end
12
13    check -->|No| skip(["💤 Sleep — nothing to do"])
14    check -->|Yes| stage
15    stage --> commit --> pull --> push
16    push --> done(["✅ Synced to GitHub"])
17    pull -->|conflict| err(["⚠️ Needs manual fix<br/>gmd doctor to diagnose"])
18
19    style trigger fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
20    style sync fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#15803d
21    style check fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
22    style stage fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
23    style commit fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
24    style pull fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
25    style push fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
26    style skip fill:#94a3b8,color:#fff,stroke:#64748b,stroke-width:2px
27    style done fill:#15803d,color:#fff,stroke:#166534,stroke-width:2px
28    style err fill:#ef4444,color:#fff,stroke:#dc2626,stroke-width:2px

Why 5 minutes: 30s is too noisy, 1h is too slow, 5 min is just right for finishing a thought. Adjustable via StartInterval in ~/Library/LaunchAgents/com.zeromd.sync.plist.

Why Not Other Solutions

Alternative	Why not
iCloud everywhere	Poor Windows sync, no version history
Obsidian Sync	~$4/mo, ~$480 over 10 years
Git everywhere	No good free Git client on iOS
Notion	Proprietary format, data not local, AI needs API
Self-hosted	High maintenance cost, dies when you stop

This approach: iCloud for Apple ecosystem sync, Git for cross-platform + version history. Zero cost.

Risks & Mitigations

Risk	Mitigation
iCloud corrupts .git	Low probability; remote repo is full backup
macOS off, iOS edits can't push	Auto-syncs when Mac wakes up
Git conflicts	pull --rebase + plain text is easy to resolve
GitHub down	Local + iCloud dual backup

Common Commands

bash
gmd                      # check sync status (same as gmd status)
gmd doctor               # health check, diagnose issues
gmd sync                 # manual sync now
gmd log                  # view last 20 log entries
gmd log 50               # view last 50 log entries
gmd setup                # smart setup (idempotent, skips completed steps)
gmd help                 # compact help (Chinese, English, or Japanese)
# "md" also works as a backward-compatible alias for "gmd"

With no language specified, gmd help and gmd doctor use your macOS preferred language. A language appended to the command takes priority: use zh or its convenience alias cn for Chinese, en for English, and ja for Japanese—for example, gmd help ja or gmd doctor cn. For a persistent override, add export ZEROMD_LANG=en (or zh, cn, ja) to your shell config.

Vault renamed? No action needed. sync.sh auto-discovers the vault by scanning for .git in the iCloud Obsidian directory.

Sync issues? Run gmd doctor to diagnose.

Background task stopped? Rerun gmd setup. Switching vaults? Run gmd init.

HTTPS auth failed? GitHub no longer accepts account passwords for Git operations. Update the HTTPS credentials your system Git uses, or switch the repo to SSH.

New machine shows old local commits? The first sync on that Mac compares against origin/main. If it detects stale/diverged local state, zeromd saves it into a zeromd-backup-<timestamp> branch and realigns local main to the remote branch.

Uninstall

bash
bash scripts/uninstall.sh

Your notes are not affected. iCloud sync continues. Only auto-push to GitHub stops.

Contributing

bash
bash tests/run.sh

Pure bash test suite, zero dependencies. Run it after any change to scripts/. All tests must pass before submitting a PR.

Project Structure

zeromd/
├── scripts/
│   ├── zeromd               # CLI client (gmd status/sync/doctor/log/setup/help)
│   ├── setup.sh            # smart installer (idempotent, 8 phases)
│   ├── install.sh          # backward-compat wrapper → setup.sh
│   ├── uninstall.sh        # uninstall
│   └── sync.sh             # auto-sync (every 5 min)
├── tests/
│   ├── run.sh              # test runner
│   ├── test_zeromd.sh       # CLI tests
│   ├── test_sync.sh        # sync logic tests
│   └── test_setup.sh       # setup logic tests
├── install-remote.sh       # curl one-liner entry point
├── com.zeromd.sync.plist    # launchd job template
├── LICENSE
├── README.md               # English
├── README.zh.md            # 中文
└── README.ja.md            # 日本語