amox-pi-sync

简体中文

Advantage

Sync Pi sessions through a private Git repository, with paths you choose. Deleting a session also removes the child sessions it produced (orphan sessions), and that deletion is synced.

Features

• Default paths are sessions and missions. You can include or exclude other agent-data paths. Files move as-is: no Markdown export and no JSONL merge. If both sides changed the same file, sync stops.
• /sync-prune finds subagent sessions whose parent is gone, including descendants, previews them, and syncs that deletion. It does not run before push unless you turn that on.
• A pull backs up only the files it is about to replace or delete.
• With Starline, a status capsule opens the actions. Without it, the same actions stay on /sync-*.

Source

@gfgghgftgffg/amox-pi-sync is a selective fork of MuratAitov/pi-sync, based on MIT pi-sync-suite@0.1.1 (Copyright © 2026 Murat). The source ref is npm:pi-sync-suite@0.1.1. Transport is SSH Git. See MAINTENANCE.md.

Usage

Point it at a private SSH Git repository. This does not transfer files yet:

/sync-setup git@host:owner/private-repo.git

Send local sessions, then bring remote sessions back:

/sync-push
/sync-pull

Preview orphan subagent sessions, then delete them and sync that deletion:

/sync-prune
/sync-prune --yes

/sync-status opens the same actions without Starline. /sync-settings changes paths and whether prune runs before push.

Install

Requires Pi >=1.1.0, Node >=22.19.0, npm, Git and working SSH authentication.

From this repository checkout:

node scripts/install-extension.mjs amox-pi-sync

Only this extension is installed. Do not load it alongside the original pi-sync-suite; inspect existing sources with pi list and remove the old source yourself. If the first npm publication is pending, use the checkout installer above. Once available, npm installation and updates use:

pi install npm:@gfgghgftgffg/amox-pi-sync
pi update --extensions

Details

• A per-device syncedPaths baseline records paths present at the last successful push or pull. Push removes previously synced paths that are now missing locally. Pull applies remote deletions after a backup and keeps local missing baseline paths as pending deletions, so a pull before push does not resurrect them. Files that were never synced, and remote-only files not yet pulled, are not deleted. The first baseline is the intersection of local and snapshot paths; deletions from before that baseline are not inferred.
• Orphan prune compares parent basenames without case sensitivity, accepts names matching type#8hex, and cascades to descendants. It skips files modified in the last 10 minutes and the active session, previews count, size and names, writes the snapshot deletion before deleting locally, and refuses a dirty repository. Prune before push is off by default. A prune failure warns and does not block the push.
• Network Git operations time out after 10 minutes. Local Git operations time out after 60 seconds. A process ended by timeout or cancellation is a failure, even if Pi reports exit code 0. Pull fast-forwards when it can; otherwise it does a clean three-way merge. A rejected non-fast-forward push fetches, integrates without rebase or force, and retries once.
• Pull and restore back up only the local files being replaced or deleted. A pull that only adds files creates no backup. Manual create-backup is still a full snapshot of managed data.
• Windows prefers native OpenSSH (System32/OpenSSH/ssh.exe) when it is available. Git commands force core.autocrlf=false and core.eol=lf, and the snapshot repo uses a local * -text attribute. Existing mixed line endings are not rewritten.

Settings and UI

• The settings menu contains View Status, Sync Mode (auto, manual, off), Sync Paths (include/exclude safe relative agent-data paths), Prune before push (default Off), Backups (create/list/restore), Diagnostics (doctor/diff/log), and Cleanup (Preview, Run, Delete Selected Backup, Retention). Excluding a path stops future transfers for it; existing snapshot copies are not removed by that setting alone.
• Manual/off startup performs no network access. Auto startup computes a local fingerprint, starts timers and launches a background pull without awaiting network completion. /sync-setup only saves configuration and stops timers; reload to activate auto mode if enabled.
• With Starline, the clickable status capsule opens details and actions. The status key remains pi-sync for existing placement; the pill bridge takes precedence over legacy extensionStatuses.commands. There is no three-line widget.
• Pill clicks anchor bubbles to the corresponding Starline cell, like Model; settings, submenus and confirmations retain that anchor. /sync-status uses the last clicked anchor, or a centered fallback before the first click. Text entry still uses Pi input dialogs.
• Bubble colour defaults to Follow pill; alternatively choose the current theme’s accent, success, warning or error colour for borders and selection. Before a pill click, Follow pill uses theme accent. The optional bubbleColor setting stores pill, accent, success, warning or error; changing it performs no transfer. Without Starline this option is hidden and Pi renders its native dialogs.
• Labels and values are separated by a colon (for example, Paths: 2 configured); Starline action rows start with •. Labels and values use Pi theme colours, while bold action rows keep Starline’s selection contrast. State shows Manual, Auto or Off directly; active operations use Push/Pull, with the configured mode shown separately. RPC and no-Starline output stay plain text.

Data and safety

[!WARNING] Sessions, missions and other selected files may contain secrets. Use a private SSH repository, review included paths, and secure both the remote and local backups. Private Git is not encryption or a secret scrubber.

• Paths are relative to Pi's agent-data directory, not the current project. Arbitrary safe data paths can be included or excluded; the extension does not change the working directory.
• Concurrent edits are not a semantic merge. Coordinate devices and inspect diagnostics. Incoming content replaces differing same-path files after backup; active sessions must not be deleted or overwritten. Restore applies only the currently managed paths.
• Backups use amox-pi-sync-backups under the agent-data directory. Cleanup only deletes local backups after manual preview/confirmation, using complete backup directories rather than individual files. The default limits are 20 complete backups and a maximum age of 180 days; older or excess backups become cleanup candidates. There is no automatic deletion; sessions and missions are never cleanup targets.
• Settings use amox-pi-sync.json. If absent, legacy pi-sync-suite.json can be read for migration. The old file is not changed before new settings are saved; saving writes the new file. Migration uses a separate amox-pi-sync-repo directory rather than reusing the old snapshot.

Configuration sync/settings merging, Markdown/JSON archives, Environment Tools and Local Packages from the original suite are not included. Deployment tools such as amox-agent-bootstrap own environment setup and machine-specific configuration; Pi's native /export handles readable exports. Raw data selection, backups and manual backup cleanup remain part of sync. See feature decisions for the reasons and maintenance boundaries. This is a selectively maintained fork, not a runtime wrapper or a full replacement of the upstream suite. Daily reviews track published upstream changes, port worthwhile retained behavior, skip removed features and ask the owner through ntfy when uncertain; removed modules are not restored automatically.