FreshClone

Stop guessing why the repo you just cloned won't run.

FreshClone is a local-first VS Code project setup doctor. Open an unfamiliar repository, run one scan, and get a short list of the things that can actually stop it from starting: missing dependencies, missing environment variables, the wrong runtime, the wrong package manager, Docker problems, uninitialized submodules, and likely port collisions.

No account. No AI API. No source-code upload. No telemetry.

FreshClone project setup scan

What it catches

Dependencies: missing node_modules, absent Python virtual environments, package-manager/lockfile conflicts
Environment: missing .env, missing variable names compared with .env.example / .env.sample / .env.template
Runtimes: missing Node.js, Python, Go, Rust, Java, or .NET tooling, plus Node version requirements from .nvmrc, .node-version, or package.json
Package managers: npm, pnpm, yarn, or Bun expected by the project but missing locally
Docker: missing Docker/Compose tooling or a Docker engine that is not responding
Git: submodules that were cloned but never initialized
Ports: likely dev ports that are already in use
Startup: detects the most likely dev, start, serve, develop, or preview command

FreshClone currently recognizes Node/JavaScript/TypeScript, Python, Docker, Go, Rust, Java, and .NET project markers.

One scan instead of setup whack-a-mole

FreshClone sorts findings into Blockers, Warnings, Notes, and Ready checks. The score is intentionally simple: a blocker means something is likely to stop first run; a warning means you should look at it before assuming the repo is broken.

FreshClone environment check

Fix the obvious stuff without giving an extension free rein

FreshClone can prepare the right dependency-install command, create .env from an existing template, and initialize Git submodules. Nothing runs silently.

Terminal commands require a click and confirmation. Existing .env files are never overwritten.

FreshClone runtime version check

It respects Workspace Trust

In VS Code Restricted Mode, FreshClone stays useful but conservative. It can inspect supported project files, but command-based runtime checks, localhost port probes, and terminal fixes stay off until you trust the workspace.

FreshClone package manager and port checks

Run the project when the blockers are gone

When FreshClone finds a likely start script, the full report shows the detected command. Once setup looks clean, you can launch it from FreshClone instead of digging through package.json again.

FreshClone one-click fix and run flow

Quick start

Install FreshClone — Project Setup Doctor.
Open a project folder.
Click the FreshClone icon in the Activity Bar, or run FreshClone: Scan Project from the Command Palette.
Open the full report and work from blockers down.

Commands

Command	What it does
`FreshClone: Scan Project`	Runs a new local project-setup scan
`FreshClone: Open Full Report`	Opens the detailed readiness report
`FreshClone: Copy Report as Markdown`	Copies a secret-safe report for an issue, teammate, or AI assistant
`FreshClone: Run Suggested Start Command`	Opens a terminal with the detected project start command
`FreshClone: Refresh`	Re-runs the scan quietly

Settings

Setting	Default	Purpose
`freshclone.scanOnOpen`	`true`	Scan shortly after opening a workspace
`freshclone.checkPorts`	`true`	Probe likely localhost dev ports in trusted workspaces
`freshclone.showStatusBar`	`true`	Show the latest score in the status bar
`freshclone.envExampleFiles`	common templates	Choose which env-template filenames to compare

Privacy

FreshClone works locally. It does not collect or transmit source code, file contents, scan results, analytics, telemetry, identifiers, or environment-variable values.

Environment files are used only to compare variable names. The copied Markdown report never includes env values.

See PRIVACY.md for the full policy and SECURITY.md for the security model.

Why this exists

A README can tell you the happy path. FreshClone checks the machine and workspace you actually have in front of you.

That is the whole idea.

Contributing

Issues and focused pull requests are welcome. If FreshClone misses a common first-run failure for a real project stack, open an issue with a minimal example and the expected diagnosis.

FreshClone — Project Setup Doctor

Ryan Panda