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.
- 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, orpackage.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, orpreviewcommand
FreshClone currently recognizes Node/JavaScript/TypeScript, Python, Docker, Go, Rust, Java, and .NET project markers.
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 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.
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.
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.
- 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.
| 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 |
| 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 |
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.
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.
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.
MIT © 2026 Ryan Panda