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 the Transfer Queue.
• 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.
• 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. 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+. 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, 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 Transfer Queue 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. File and folder actions are also available from Explorer context menus.

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. Choose how to handle that file:

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 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.

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 with Windows credential protection, 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/Windows versions, protocol, reproduction steps, and redacted diagnostics. Leave out credentials, private keys, tokens, and confidential file content.

Limitations

• Windows 10/11 desktop editors are the supported target. macOS, Linux, browser editors, remote-only editor variants, and older editor versions are outside the current support scope.
• 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.