hf-pi-sync

An hf CLI extension that synchronizes your pi coding agent config directory (~/.pi/agent/) across multiple machines using a private Hugging Face Storage Bucket as the shared store.

Install it with:

hf extensions install tengomucho/hf-pi-sync

then use it as a top-level command:

hf pi-sync init      # login check + create/get private bucket + first push
hf pi-sync push      # stage the shareable subset and upload to the bucket
hf pi-sync pull      # download the bucket, merge, and run `pi update --extensions`
hf pi-sync           # auto-sync: compare mtimes and push or pull accordingly

What gets synced

Path under ~/.pi/agent/	Sync?	Reason
settings.json	✅	Source of truth (provider, model, theme, packages[])
extensions/, skills/, prompts/, themes/	✅ (if present)	Shareable user content
models.json, AGENTS.md	✅ (if present)	Shareable config
memory/MEMORY.md	✅ (if present)	Shareable durable facts (pi-mem extension)
npm/	❌	Regenerated by pi update --extensions from packages[]; large
bin/	❌	Architecture-specific vendored binaries
sessions/	❌	Local per-machine session history
memory/ (except MEMORY.md)	❌	Local per-machine: daily logs, scratchpad, index DBs
auth.json	❌ by default	Credentials — opt in with --with-auth

Top-level ~/.pi/*.json config files (outside ~/.pi/agent/, e.g. web-search.json) are also synced — they are stored in the bucket under a reserved _pi-root/ prefix so they never collide with agent files. Non-json siblings are ignored.

Bootstrap requirement

You will need the hf CLI version >= 1.16, check here on how to install it.

hf --version        # must be 1.16 or newer to install/dispatch
hf extensions install <owner>/hf-pi-sync

Configuration

• Default bucket: <whoami>/pi-config (your Hugging Face username, read live via hf auth whoami — never hardcoded). Override with --bucket <user>/<name> or the PI_SYNC_BUCKET environment variable.
• auth.json: excluded by default. Use --with-auth only on a private bucket you fully control and where all machines should share the same provider credentials.
• Pull semantics: additive by default (never deletes local files). Use --mirror to delete local files not present in the bucket (destructive — use with care).

Backend notes

Buckets are non-versioned, last-writer-wins storage. This is fine when one machine is the source of truth and others pull. If multiple machines push concurrently they may clobber each other; push warns when there are differences.

Headless-safety note for contributors

This tool is developed to be used on headless SSH boxes inside tmux with no GUI. If you contribute and use AI tooling with a web_search capability that defaults to an interactive browser-curator workflow, always pass workflow: "none" (or "auto-summary"), because the default curator UI opens a browser and crashes on boxes with no display.

Development

Make sure you run ruff and pytest before contributing.

License

MIT — see LICENSE.