Sync AI Setup for VSCode (SyncAI)

Keeps a team's user-level AI-agent configuration in sync: Copilot instructions, skills, agent definitions, prompts, templates, Serena memories and shared rules.

• Destination: the user's home directory, in ~/.copilot, ~/.serena and ~/.agents. Nothing is ever written inside a workspace.
• Source: the configuration bundled with the extension, or a group, which is a folder shared through OneDrive or SharePoint. OneDrive handles invitations, permissions and file transfer. The extension makes no network calls and collects no telemetry.

Where files go

The project name is the workspace folder name, normalized (My Repo (fork) → My-Repo-fork). If two repositories share the same folder name, set syncai.projectName in that folder's settings.

Groups (OneDrive / SharePoint folder)

A group is a shared folder with the same layout as resources/. OneDrive provides e-mail invitations, permissions and distribution. The extension reads the local copy of the folder, checks that it is complete and applies it to the home directory.

Workflow

1. Create. Run SyncAI: Create Group and enter a group name, then pick an empty folder inside OneDrive or a synced SharePoint library. The extension copies the starter configuration into it, publishes version 1.0.0 and adds you to the group.
2. Invite. In File Explorer or OneDrive, right-click the folder → Share and enter your colleagues' e-mail addresses ("Can view" for members). OneDrive sends the invitation.
3. Join. Each colleague accepts the invitation (for SharePoint: Sync or Add shortcut to My files), runs SyncAI: Join Group and selects their local copy of the folder. The group configuration replaces the previously installed one; personal files and locally edited files are kept.
4. Publish. Anyone with "Can edit" changes the files in the folder and runs SyncAI: Publish Group Update (patch / minor / major). The list of changed files is shown before confirming.
5. Receive. Members get the new version at startup, every syncai.checkIntervalMinutes minutes (default 15) and when VS Code regains focus.
6. Leave. SyncAI: Leave Group switches back to the bundled configuration and removes what the group installed (except locally edited files). To stop receiving the folder, also remove it from OneDrive.

Safeguards

• Incomplete sync: Publish writes the SHA-256 of every file into the group's version.json. A version is applied only when every file matches. While OneDrive is still downloading, the last verified version stays in use (cached in ~/.copilot/syncai/cache/). Files added to the folder but not yet published are ignored.
• MCP servers: these are programs that agents run. Servers coming from a group are added to ~/.copilot/mcp-config.json only after explicit approval, in a dialog that shows the full command. During automatic syncs they stay pending. Server removals are always applied.
• Malicious or misconfigured group folder: the group manifest is validated against the same allow-list, so it can only write to ~/.copilot, ~/.serena and ~/.agents.
• Permissions: users with "Can view" only cannot publish, and get a clear error.
• Limitation: anyone with "Can edit" can change the agent instructions of the whole group. Grant it to maintainers only.

OneDrive tips

• Set the group folder to "Always keep on this device" so it is available offline and its files are not cloud-only placeholders.
• The local path differs for each user (e.g. C:\Users\<user>\OneDrive - <Company>\… or C:\Users\<user>\<Company>\<Site> - Documents\…), so each user selects their own copy with Join Group. The setting also accepts variables such as %OneDriveCommercial%.

Architecture

Extension resources/ (read-only)            User home directory
├── sync-manifest.json                      ├── .copilot/
├── version.json                            │   ├── copilot-instructions.md   [block]
├── .copilot/ ───────────── global ──────►  │   ├── mcp-config.json           [json-merge]
├── .agents/  ───────────── global ──────►  │   ├── instructions/ prompts/ agents/ skills/ templates/
│                                           │   ├── projects/<name>/          ◄─ project
└── project-template/                       │   ├── serena/<name>/.serena/    ◄─ project
    ├── copilot/ ────────── project ─────►  │   └── syncai/   (version.json, state.json, sync.lock, cache/, backups/, projects/)
    └── serena/  ────────── project ─────►  ├── .agents/skills/
                                            └── .serena/

File modes

In project files, the {{syncai.projectName}} placeholder is replaced with the project name.

Versions

The global version is stored in ~/.copilot/syncai/version.json, and each project's version in ~/.copilot/syncai/projects/<name>/version.json. The version file is written last and only when there were no errors, so an interrupted sync is retried.

Several VS Code windows starting at the same time do not interfere: syncs use a file lock (~/.copilot/syncai/sync.lock, removed automatically if abandoned).

Project layout

sync-ai-setup/
├── package.json  tsconfig.json  .vscodeignore  README.md  CHANGELOG.md  LICENSE
├── media/icon.png
├── resources/
│   ├── sync-manifest.json
│   ├── version.json
│   ├── .copilot/
│   │   ├── copilot-instructions.md            (block)
│   │   ├── mcp-config.json                    (json-merge)
│   │   ├── instructions/{general,security}.instructions.md
│   │   ├── prompts/code-review.prompt.md
│   │   ├── agents/reviewer.agent.md
│   │   └── templates/pull-request.md
│   ├── .agents/skills/code-review/SKILL.md     (→ ~/.agents/skills and ~/.copilot/skills)
│   └── project-template/
│       ├── copilot/project.instructions.md     (seed)
│       └── serena/
│           ├── project.yml                     (seed)
│           └── memories/organization_conventions.md
└── src/
    ├── extension.ts
    ├── commands/index.ts
    ├── services/{bundle,source,syncService,groupService,statusService,exportService}.ts
    ├── vscode/{vscodeDirectory,configuration,statusBar}.ts
    ├── core/{constants,pathGuard,scopedDirectory,nodeDirectory,memoryDirectory,
    │         manifest,versioning,semver,hashing,syncEngine,groupBundle,userState,logger}.ts
    └── test/                                   (node:test, 47 tests)

Settings

All settings are machine/user level: a workspace cannot override them (except projectName).

Commands

Build and packaging

npm install
npm run compile
npm test               # optional, recommended
npx vsce package       # -> sync-ai-setup-1.0.0.vsix
code --install-extension sync-ai-setup-1.0.0.vsix

Before publishing to the Marketplace, make sure publisher and repository in package.json match your Marketplace publisher and source repository.

Updating the bundled configuration

1. Edit the files in resources/.
2. Increase the version in resources/version.json (SemVer) and update updatedAt.
3. Increase version in package.json and update CHANGELOG.md.
4. Run npm test && npx vsce package.

Security

• The extension makes no network calls (OneDrive distributes group folders), collects no telemetry and has no runtime dependencies.
• Writes only under ~/.copilot, ~/.serena and ~/.agents (allow-list in the code; extending it requires a code change).
• No writes inside workspaces: they are only read (folder name, workspace check).
• Inside ~/.copilot the extension only touches what it installed: Copilot CLI sessions, logs and settings are left alone.
• Symlinks are never followed; sources are opened read-only.
• Export writes only to the destination chosen by the user and never includes personal content.

Notes

• Remote (SSH / WSL / Dev Containers): the extension runs where the workspace runs, so it writes to that machine's home directory, which is where the agents run.
• Serena and ~/.copilot/serena/<name>/.serena: the extension prepares the files; Serena must be configured to use that location instead of a .serena folder in the repository root.
• Skills in ~/.agents: the .agents → ~/.agents mapping is enabled by default. To keep skills only in ~/.copilot, add "enabled": false to that mapping in resources/sync-manifest.json; skills are still copied to ~/.copilot/skills.

Extending

1. One source, many destinations: a single source in the bundle can map to several destinations in the manifest (already used for skills). When agents need different formats, add a transform field to the mapping backed by a Renderer interface in the core.
2. Distribution: private marketplace or device management; recommend the extension via extensions.json in repositories.
3. CI: run npm test, check that version.json is increased whenever resources/ changes, run vsce package, then sign and archive the VSIX.
4. Team profiles: add profiles.<team> sections to the manifest, selectable from a setting, instead of forking the extension.
5. Versioned schema: the manifest has a schemaVersion (currently 2); unknown schemas are rejected.