Implement localdev: Local development environment setup

[vredchenko]

Summary

The localdev plugin gives Claude a systematic approach to setting up and verifying local development environments. Instead of ad-hoc "try running npm install," it detects the full stack, checks prerequisites, runs setup steps in order, and verifies everything works. This is valuable because local dev setup is the #1 pain point when onboarding to a project and Claude's default behavior is to try one thing at a time reactively.

Original Intent

Plugin that configures Claude Code with local development workflow — which services to start and restart, which data to seed or clear, how to hard reset, clear cache, how to check requirements, debug across stack, etc.

Commands

/localdev:setup

Purpose: Analyze the project and perform full local environment setup.

Behavior:

1. Detect project stack by scanning for manifest/config files:

   File	Detects	Setup Action
   package.json + bun.lockb	Bun project	bun install
   package.json + package-lock.json	Node/npm project	npm ci
   package.json + yarn.lock	Yarn project	yarn install --frozen-lockfile
   package.json + pnpm-lock.yaml	pnpm project	pnpm install --frozen-lockfile
   pyproject.toml	Python project	uv sync or pip install -e .
   requirements.txt	Python (legacy)	uv pip install -r requirements.txt
   go.mod	Go project	go mod download
   Cargo.toml	Rust project	cargo build
   Gemfile	Ruby project	bundle install
   docker-compose.yml	Docker services	docker compose up -d
   Makefile	Make targets	Check for setup / install target

2. Check prerequisites — verify required tools are installed:

   • Runtime version matches (.node-version, .python-version, .tool-versions, rust-toolchain.toml)
   • Docker running if docker-compose present
   • Database CLI tools if migrations detected

3. Environment setup:

   • Copy .env.example → .env if .env doesn't exist
   • Warn about any missing required env vars

4. Install dependencies in detected order (backend before frontend in monorepos)

5. Database setup (if detected):

   • Check if database is reachable (parse connection string from .env)
   • Run migrations:
     • prisma migrate dev (Prisma)
     • alembic upgrade head (SQLAlchemy)
     • diesel migration run (Diesel)
     • rake db:migrate (Rails)
     • knex migrate:latest (Knex)
   • Run seed if seed script/file detected

6. Verify setup:

   • Run test suite (quick sanity check, first 5 tests or smoke tests)
   • Start dev server and check if it responds
   • Report results

7. Output setup summary:

   Local Dev Setup Complete
   
   ✓ Dependencies installed (bun install — 142 packages)
   ✓ Environment configured (.env created from .env.example)
   ✓ Database migrated (3 pending migrations applied)
   ✓ Seed data loaded (15 records)
   ✓ Tests passing (23/23)
   ✓ Dev server starts (http://localhost:3000)
   
   Commands:
     bun run dev     — Start development server
     bun test        — Run tests
     bun run build   — Build for production
   

Edge cases:

• Monorepo (Turborepo, Nx, Lerna) → detect workspace structure, setup in dependency order
• Multiple services (microservices) → setup each, document inter-service dependencies
• Missing runtime version → offer to install via asdf/nvm/pyenv
• Setup script already exists (scripts/setup.sh, make setup) → prefer running it over custom logic

/localdev:check

Purpose: Health-check the local environment and diagnose issues.

Behavior:

1. Run the same detection as setup but in verify-only mode
2. Check each component:

   Environment Health Check
   
   Runtime & Tools
   ✓ bun 1.3.8 (matches .tool-versions)
   ✓ node 22.22.0 (matches .node-version)
   ✗ python — not found (required by scripts/analyze.py)
   
   Dependencies
   ✓ node_modules/ exists and up-to-date
   ⚠ bun.lockb is newer than node_modules — run `bun install`
   
   Environment
   ✓ .env exists
   ✗ Missing: REDIS_URL (defined in .env.example)
   
   Services
   ✓ PostgreSQL — responding on localhost:5432
   ✗ Redis — not responding on localhost:6379
   ✓ Docker — running (3 containers up)
   
   Database
   ✓ Connected to myapp_dev
   ⚠ 2 pending migrations
   
   Ports
   ✓ 3000 — available (dev server)
   ✗ 5173 — in use by PID 12345 (vite)
   

3. For each failure, provide a fix command
4. Offer to auto-fix what can be fixed

Edge cases:

• Database not reachable → suggest starting Docker or checking connection string
• Port in use → identify the process and offer to kill it (with user confirmation)
• Stale lock file → suggest removing and reinstalling

/localdev:reset (new)

Purpose: Hard reset local environment to clean state.

Behavior:

1. Ask user what to reset (with checkboxes):
   • Dependencies (remove node_modules/, .venv/, target/)
   • Database (drop and recreate, re-run migrations and seeds)
   • Cache (remove .next/, .turbo/, pycache/, dist/)
   • Environment (remove .env, re-copy from .env.example)
   • Docker (docker compose down -v, remove volumes)
   • Git (discard uncommitted changes — requires explicit confirmation)
2. Confirm with user before destructive operations:

   ⚠ This will:
   - Remove node_modules/ (142 packages)
   - Drop database myapp_dev (15 tables, ~2300 rows)
   - Remove .next/ cache (48 MB)
   
   Proceed? [y/N]
   

3. Execute selected resets in order
4. Re-run /localdev:setup to rebuild
5. Output: summary of what was reset and rebuilt

Edge cases:

• User selects git reset but has uncommitted work → extra strong warning
• Database reset fails (other connections) → suggest closing other connections first

Hooks

None — this plugin operates through commands only. (Considered a hook on project open, but that would be too intrusive.)

File Manifest

File	Est. Lines	Purpose
commands/setup.md	120-150	Full environment setup
commands/check.md	90-110	Health check and diagnosis
commands/reset.md	80-100	Hard reset to clean state
README.md	160-200	Full plugin documentation
.claude-plugin/plugin.json	15-20	Plugin manifest

README Outline

1. Overview — What localdev does: systematic setup, health checking, and reset
2. Quick Start — Installation + /localdev:check to see current state
3. Commands — Table with all 3 commands
4. Detection Matrix — Full table of what the plugin detects and how
5. Database Support — Supported ORMs/migration tools
6. Monorepo Support — How workspace detection works
7. Customization — How to add project-specific setup steps
8. Troubleshooting — Common issues and fixes

Prerequisites

• No external tools required — the plugin detects and uses whatever's available
• Project-specific tools (Docker, database CLIs, etc.) are checked and reported

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• Detection matrix covers major ecosystems (Node, Python, Go, Rust, Ruby, Docker)
• Database migration support covers popular ORMs
• Plugin provides clear value beyond Claude's defaults (systematic detection vs ad-hoc)