SFTP/FTP Sync + AI Conflict Resolution

Upload, download, and sync your project over SFTP or FTP from VS Code and Cursor. Browse remote files, review changes before overwriting, and resolve upload conflicts yourself or with your editor's AI agent.

Install · Quick start · Configuration · Daily use · Conflicts · Help

What you can do

• Transfer files and folders. Upload a single change, download an existing site, or sync a whole project in either direction.
• Work from the sidebar. Browse remote files, compare them with local copies, and follow progress in Activity.
• Catch remote changes. With conflict checking enabled, uploads pause when the server copy has changed or cannot be verified against a known version.
• Use your existing AI agent. Give it the conflict's local and remote versions through the extension's MCP tools, then let it merge and upload.
• Choose what gets transferred. Use 15 ignore templates for common stacks, switch connection profiles, or upload only Git changes.
• Follow one clear result. Activity groups transfers and conflicts; manual operations get one summary, while successful automatic saves stay quiet.
• Keep previous remote text versions. New configurations enable local overwrite backups with up to 100 versions per file. See recovery limits.

Regular transfers and manual conflict resolution work without AI.

Install or update

Check the publisher is Timorfiy and the extension ID is Timorfiy.sftp-sync-ai. Version-tag releases publish the same verified VSIX to GitHub and Open VSX; Visual Studio Marketplace uploads are handled separately. Registry installations use the editor's update controls. For a manual update, install the newer VSIX the same way; your workspace configuration and saved credentials are retained. Release versions can differ between channels.

Supported: Windows 10/11 · VS Code Desktop 1.104.0+ · Cursor Desktop 3.17.8+. Preliminary compatibility: Ubuntu Desktop 22.04/24.04/26.04 LTS x64 and macOS 14/15/26 on supported Intel and Apple Silicon hardware. One VSIX is used on all platforms. See platform coverage and verification limits.

Linux and macOS compatibility was implemented with AI assistance. Automated checks cover the operating systems and architectures listed in the test report. The extension has not been manually tested in installed VS Code or Cursor on Linux/macOS. Editor UI, credential storage, and editor MCP integration remain unverified in those environments.

SFTP and plain FTP are supported; FTPS is experimental. See limitations.

Quick start

1. Open a folder and create the configuration

Open your local project folder in the editor. If the project is already on the server, start with an empty local folder.

Press Ctrl+Shift+P (Cmd+Shift+P on macOS), run SFTP: Config, and choose your stack's ignore template, or Basic. Edit the generated .vscode/sftp.json:

Use the remote directory exposed by your hosting account. It may differ from the path you see in an SSH shell. The workspace folder maps to remotePath; context lets you map a subfolder instead.

Leave the password out: the extension prompts when needed and can save it in the editor's Secret Storage. For SSH keys, see SFTP options. Copyable complete SFTP and FTP examples are below.

New configurations enable conflict checks and local text backups. Upload on save, automatic watcher actions, and sync deletion start off. Review the chosen ignore rules: excluded paths are skipped in both transfer directions.

2. Test the connection

Save the configuration and run SFTP: Test Connection. It checks credentials, the connection, remotePath, and list/read access without changing remote files. For the first SFTP connection, verify the host-key fingerprint with your server provider before accepting it.

Commands use the SFTP: prefix for both SFTP and FTP.

3. Make your first transfer

The project is already on the server: run SFTP: Sync Remote → Local to download it into your local folder. Start here before editing an existing site.

Downloads can overwrite local work. Commit or copy anything you need before downloading into a non-empty folder. A successful local replacement does not retain an extension recovery version.

You want to upload local work: start with one disposable text file. Right-click it in the local Explorer and choose SFTP: Upload File. Check it in the SFTP/FTP sidebar before uploading a whole project.

Keep the sidebar's Activity open until the operation finishes. A saved file is not proof of a completed upload. Cancelling does not undo completed transfers.

Configuration examples

Each example is a complete .vscode/sftp.json for one connection, with the full Basic ignore list. Replace the example connection details with yours. Use SFTP: Config to generate a configuration with a stack-specific template.

SFTP

{
  "name": "My SFTP Server",
  "host": "sftp.example.com",
  "protocol": "sftp",
  "port": 22,
  "username": "deploy",
  "remotePath": "/var/www/site",
  "uploadOnSave": false,
  "conflictCheck": true,
  "useTempFile": false,
  "openSsh": false,
  "concurrency": 4,
  "watcher": {
    "files": false,
    "autoUpload": false,
    "autoDelete": false,
    "autoRename": false
  },
  "syncOption": {
    "delete": false,
    "skipCreate": false,
    "ignoreExisting": false,
    "update": false
  },
  "ignore": [
    ".vscode",
    ".git",
    ".github",
    ".idea",
    ".DS_Store",
    "Thumbs.db",
    ".env",
    ".env.*",
    "AGENTS.md",
    "CLAUDE.md",
    ".claude",
    ".cursor",
    "*.log",
    "*.tmp",
    "*.bak"
  ],
  "backup": {
    "enabled": true,
    "location": "local",
    "folder": ".vscode/sftp-backup",
    "versions": 100,
    "onDelete": false
  }
}

Plain FTP

{
  "name": "My FTP Server",
  "host": "ftp.example.com",
  "protocol": "ftp",
  "port": 21,
  "username": "deploy",
  "remotePath": "/public_html",
  "secure": false,
  "uploadOnSave": false,
  "conflictCheck": true,
  "useTempFile": false,
  "openSsh": false,
  "concurrency": 1,
  "watcher": {
    "files": false,
    "autoUpload": false,
    "autoDelete": false,
    "autoRename": false
  },
  "syncOption": {
    "delete": false,
    "skipCreate": false,
    "ignoreExisting": false,
    "update": false
  },
  "ignore": [
    ".vscode",
    ".git",
    ".github",
    ".idea",
    ".DS_Store",
    "Thumbs.db",
    ".env",
    ".env.*",
    "AGENTS.md",
    "CLAUDE.md",
    ".claude",
    ".cursor",
    "*.log",
    "*.tmp",
    "*.bak"
  ],
  "backup": {
    "enabled": true,
    "location": "local",
    "folder": ".vscode/sftp-backup",
    "versions": 100,
    "onDelete": false
  }
}

Plain FTP sends credentials and file content without encryption. Prefer SFTP when your host supports it. FTPS modes are experimental.

Already have a configuration? It is not rewritten automatically. In an existing file, omitting conflictCheck leaves it false, and omitting backup.enabled leaves backups disabled. The examples set these explicitly. See the generated values and omission defaults.

Everyday workflows

Open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS). File and folder actions are also available from Explorer context menus.

Follow transfers in Activity

Activity groups files by operation and connection. Use Filter Activity to show All, Active, or Needs Attention. Select a file for details, conflict actions, or recovery options. Relative paths keep the list readable; full local and remote paths are available in tooltips.

Show Output opens the bottom Output panel with the sftp channel. It contains configuration, transfer logs, and errors as text you can copy. Credentials are redacted. Activity remains available in the sidebar.

The status bar shows preparation, completed-file counts, parallel operations, and pending conflicts. Clicking it opens the sftp Output channel. One summary follows each manual operation; successful automatic saves stay quiet. Repeated background connection errors are grouped. Notifications appear inside the editor on every platform, without separate Windows popups or sounds.

Set Notifications: Show Success in the SFTP settings (sftp.notifications.showSuccess) to false in editor settings to hide successful manual summaries. Errors and conflict review remain visible. Activity keeps up to 100 completed operation groups for the current editor session; active operations and pending conflicts are retained. Clear Completed does not delete private conflict snapshots.

Upload automatically

After checking a manual transfer, set uploadOnSave to true if you want editor saves to upload. Keep conflictCheck: true to detect remote changes.

For files written by build tools or other applications, configure the file watcher. Watcher uploads, deletions, and renames are separate opt-in settings.

Ignore files for your stack

SFTP: Apply Ignore Template adds exclusions to an existing connection or profile while preserving your current rules and other settings. Save pending configuration edits before running it.

Templates cover Basic, Bitrix, WordPress, PHP/Composer, Laravel, Yii2, Node.js, React/Vue/Vite, Next.js, Nuxt, Python, Go, Java, .NET, and Ruby/Rails. See all templates and exact rules.

Transfer exclusions differ from Git exclusions: built files and dependencies may be needed on your server. Templates keep deployable output where appropriate. The Bitrix template is for an existing site: it excludes the root /bitrix and /upload directories while keeping custom code under local.

Sync a folder or project

Bulk upload: Sync Local → Remote may overwrite many remote files. The command always asks for confirmation before connecting or running hooks. Check the profile and both paths in the dialog. Cancel changes nothing.

Keep syncOption.delete: false unless you intend to delete destination-only files. When enabled, Remote → Local deletes them locally; Local → Remote deletes them on the server. These deletions have no backup guarantee. Local → Remote deletion cannot be combined with conflictCheck: true. Both Directions does not apply syncOption.delete.

There is no sync preview or dry-run mode. See sync options.

Resolve upload conflicts

With conflictCheck: true, an upload pauses if the remote file changed since the last known version, no baseline exists, or an FTP server cannot provide an exact timestamp. Open SFTP/FTP → Activity or choose Review Conflicts in the notification, then select a file to choose an action. Closing the menu keeps the upload pending; cancellation requires Cancel upload:

Resolve manually

Review the diff before overwriting. If either side changes during review, the extension refreshes the conflict instead of applying an outdated decision.

Resolve with your editor's agent

The extension automatically registers upload and conflict tools through MCP (Model Context Protocol) in supported VS Code and Cursor versions. Use an agent in that editor with access to those tools; your agent's normal account and model setup still apply. The extension itself needs no AI-provider API key.

For a separate local client, enable sftp.externalMcp.enable in each editor window and reload those windows. One external MCP connection can serve multiple projects: the agent calls conflicts_workspaces and explicitly selects the root matching its task. See external MCP setup.

For explicit uploads, the agent calls upload_files with workspace and a list of saved file paths (relative to the workspace or absolute). Watcher and uploadOnSave can stay off. The active profile, exclusions, backups, hooks, and conflict checks still apply. File content is read by the extension from disk; it is not sent to the model just to upload it.

Results contain uploaded/total counts and only files that need attention. If terminal is false, resolve any returned conflicts and use uploads_wait with the returned operationId; do not submit the same batch again. A timed-out wait can leave transfers running. Use Activity to cancel them. Operation IDs are valid only in the same editor session.

With a conflict pending, ask your agent:

Resolve the pending SFTP/FTP upload conflict. Read both versions and the diff, preserve the remote changes and my intended local edits, upload the merged result, and wait for uploaded before continuing.

The tools let the agent inspect both versions, submit or acknowledge a local merge, and resume the upload against the latest revision. Only uploaded confirms success; a failed upload or stale revision still needs attention.

Agent merging is text-only. If the file is binary, snapshots are unavailable, or the editor buffer is dirty, use the manual path. See the full agent instructions for tool names, revision handling, and terminal statuses.

Recovery

New configurations store previous remote text/source versions in .vscode/sftp-backup, keeping up to 100 versions per file. The Backups view provides Open Backup and Restore Backup. Inspect the current remote file before restoring: restore can overwrite it.

Conflict snapshots are stored privately outside the project and are never synchronized. They have separate retention limits. To clear inactive records, run SFTP/FTP Sync + AI Conflict Resolution: Clear Conflict State; active decisions are preserved.

Security and privacy

Secure password storage

Keep passwords and passphrases out of .vscode/sftp.json. The extension can save them in the editor's Secret Storage backed by the editor's OS credential store, scoped to the workspace and connection. Use SFTP: Delete Saved Password to remove a saved credential. Secret Storage does not encrypt plain FTP traffic.

• Server identity: changed SFTP host keys are rejected. Verify the new fingerprint with the server owner before changing a saved key.
• Transfer exclusions: .vscode and private conflict state are always excluded, including from force transfers.
• Diagnostics: the extension sends no telemetry. Its local diagnostics redact secrets and exclude file contents.
• AI tools: when an agent reads conflict content, that content is available to the agent and its configured model provider.
• Hooks: configured hooks run shell commands. Review them before using someone else's configuration.

Troubleshooting

Start with SFTP: Test Connection, or run SFTP: Open Troubleshooting to open the bundled guide.

Need help? Open an issue with extension/editor/OS versions, architecture, protocol, reproduction steps, and redacted diagnostics. Leave out credentials, private keys, tokens, and confidential file content.

Limitations

• Windows 10/11 desktop editors retain the existing support scope. Linux/macOS desktop compatibility is preliminary pending manual editor verification. Linux ARM64, other Linux distributions, browser editors, Remote SSH, WSL, Dev Containers, and older editor versions are outside this compatibility stage.
• FTPS is experimental; SFTP and plain FTP are supported.
• Bulk sync has no preview/dry-run and does not merge file contents.
• AI conflict resolution requires an available editor agent with tool access and supports text files only.
• Backups have the operation-specific boundaries listed in Recovery.

Documentation and project

License and attribution

MIT. Independently maintained by Timorfiy, with code contributions inherited from SFTP Neo and earlier vscode-sftp projects. See LICENSE and the historical changelog for attribution.