Smart Setup Tool

Detect your project type and automatically configure the complete development environment including package installation, configuration files, environment variables, and development scripts.

When to Use This Command

Run this command when...

• You have cloned a new repository and need to set up the entire development environment from scratch
• You want to auto-detect the project type and install all required dependencies, tools, and configurations
• You need to generate missing configuration files like .env, tsconfig.json, or editor settings
• You are onboarding a new team member and want a single command that makes the project runnable
• You want to verify that all prerequisites (runtime versions, system dependencies, database connections) are met

Quick Start

Copy
# .claude/commands/smart-setup-tool.yaml
name: Smart Setup Tool
description: Auto-detect and configure complete development environment
inputs:
  - name: scope
    description: "full, deps-only, config-only, or verify"
    default: "full"

Copy
# Full project setup
claude "smart-setup-tool"

# Only install dependencies
claude "smart-setup-tool --scope deps-only"

# Verify environment without changes
claude "smart-setup-tool --scope verify"

Output:
  [detect] Project: Node.js + TypeScript + React
  [detect] Package manager: pnpm (pnpm-lock.yaml found)
  [deps] Installing 142 packages via pnpm...
  [config] Generated .env from .env.example (3 vars need values)
  [config] TypeScript config verified
  [config] ESLint + Prettier configured
  [verify] Node.js 20.11 (required: >=20)
  [verify] PostgreSQL connection: OK
  [scripts] Dev server: pnpm dev (port 3000)
  Done. Project ready. Set 3 env vars in .env to complete setup.

Core Concepts

Concept	Description
Project Detection	Identifies project type from manifest files: package.json, requirements.txt, Cargo.toml, go.mod
Dependency Installation	Runs the correct package manager (npm, pnpm, yarn, pip, cargo) based on lock file detection
Config Generation	Creates missing configuration files from templates or examples (.env, tsconfig, eslint)
Prerequisite Verification	Checks runtime versions, system dependencies, database connections, and API access
Development Scripts	Identifies and documents available dev scripts: start, test, build, lint

Setup Pipeline:
  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
  │  Detect  │──>│  Install  │──>│Configure │──>│  Verify  │
  │  Project │   │   Deps    │   │  Files   │   │  Ready   │
  └──────────┘   └──────────┘   └──────────┘   └──────────┘
   - Type          - Packages     - .env          - Runtime
   - Manager       - Tools        - tsconfig      - Database
   - Runtime       - Dev deps     - ESLint        - Services

Configuration

Parameter	Type	Default	Description
scope	string	"full"	Setup scope: full, deps-only, config-only, or verify
manager	string	auto-detected	Force package manager: npm, pnpm, yarn, pip, cargo
node_version	string	auto-detected	Required Node.js version (from .nvmrc or engines field)
skip_optional	boolean	false	Skip optional dependencies to speed up installation
env_file	string	".env.example"	Template file for generating .env

Best Practices

1. Run verify after every pull -- Use --scope verify after pulling changes to catch new dependencies or configuration requirements that teammates added.
2. Maintain a .env.example -- Keep .env.example updated with all required environment variable names (without values). The setup tool uses this to generate .env files for new developers.
3. Pin runtime versions -- Use .nvmrc, .python-version, or rust-toolchain.toml so the setup tool can verify and install the correct runtime version automatically.
4. Document post-setup steps -- Some setup steps cannot be automated (e.g., obtaining API keys). The tool lists these as manual steps. Keep them minimal and well-documented.
5. Use lock files consistently -- Commit your lock file (package-lock.json, pnpm-lock.yaml) so the setup tool installs exact versions rather than resolving new ones.

Common Issues

1. Wrong package manager detected -- If multiple lock files exist (package-lock.json and yarn.lock), the tool may pick the wrong one. Delete the unused lock file or specify --manager explicitly.
2. Database connection fails during verify -- The verification step checks database connectivity. Ensure your database server is running and the connection string in .env is correct.
3. Node.js version mismatch -- The project requires a specific Node.js version but a different one is installed. Use nvm install or nvm use to switch to the required version before re-running setup.