npm - claude-launchpad - Versions diffs - 0.3.3 → 0.4.0 - Mend

claude-launchpad 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 mboss37
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,32 +1,89 @@
 # Claude Launchpad
-**Your Claude Code setup is probably broken. This tool tells you how.**
+[![npm version](https://img.shields.io/npm/v/claude-launchpad?style=flat-square)](https://www.npmjs.com/package/claude-launchpad)
+[![npm downloads](https://img.shields.io/npm/dm/claude-launchpad?style=flat-square)](https://www.npmjs.com/package/claude-launchpad)
+[![GitHub stars](https://img.shields.io/github/stars/mboss37/claude-launchpad?style=flat-square)](https://github.com/mboss37/claude-launchpad)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/mboss37/claude-launchpad/blob/master/LICENSE)
-Claude Code's effectiveness is 90% configuration, 10% prompting. But nobody can tell if their config is actually good. You write a `CLAUDE.md`, add some hooks, install some plugins — and then *hope* Claude follows them.
+**Everything you need to launch a project with Claude Code — and keep it healthy.**
-Claude Launchpad is the first CLI that **diagnoses, scaffolds, enhances, and tests** Claude Code configurations. Think ESLint for your AI setup.
+A launchpad isn't just where you start. It's where you prepare, run checks, and make sure everything is ready before you go. Claude Launchpad does exactly that for your Claude Code setup:
+- **Launch new projects** with production-ready Claude Code config from day one
+- **Check existing projects** — score your config, find issues, auto-fix them
+- **Prove it works** — run Claude against test scenarios and see if your rules are actually followed
 ```bash
-npx claude-launchpad
+npm i -g claude-launchpad
+```
+## Two Paths, One Tool
+### Starting a new project?
+```bash
+claude-launchpad init
 ```
-## The Workflow
+Detects your stack, generates `CLAUDE.md` with your commands and conventions, creates `TASKS.md` for sprint tracking and session continuity, sets up hooks for auto-formatting and `.env` protection, and adds a `.claudeignore` so Claude doesn't waste time reading `node_modules`.
+Then run `enhance` to have Claude read your codebase and fill in the architecture, conventions, and guardrails with real, project-specific content — not boilerplate.
+### Already have a project?
 ```bash
-npx claude-launchpad init          # 1. Auto-detect stack, generate config + hooks + .claudeignore
-npx claude-launchpad enhance       # 2. Claude reads your code, completes CLAUDE.md
-npx claude-launchpad               # 3. Check your score (42%)
-npx claude-launchpad doctor --fix  # 4. Auto-fix everything (→ 86%)
-npx claude-launchpad eval          # 5. Prove your config works (89% eval score)
+claude-launchpad
 ```
-> See the [full story on the landing page](https://mboss37.github.io/claude-launchpad/) — a 42% → 89% journey.
+Scans your Claude Code config, gives you a score out of 100, and tells you exactly what's wrong. Run `--fix` to auto-apply fixes. Run `--watch` to see the score update live as you edit. Run `eval` to prove your config actually makes Claude behave.
+## All Commands
+| Command | What it does | Cost |
+|---|---|---|
+| `claude-launchpad init` | Launch a new project: detects stack, generates config, hooks, TASKS.md | Free |
+| `claude-launchpad` | Check your config: score it 0-100, list issues | Free |
+| `claude-launchpad doctor --fix` | Auto-fix issues: adds hooks, rules, missing sections, .claudeignore | Free |
+| `claude-launchpad doctor --watch` | Live score that updates when you save config files | Free |
+| `claude-launchpad enhance` | Claude reads your code and completes CLAUDE.md with real content | Uses Claude |
+| `claude-launchpad eval --suite security` | Run Claude against test scenarios, prove your config works | Uses Claude |
+## Quick Start
+```bash
+# Install
+npm i -g claude-launchpad
-## Commands
+# Go to any project with Claude Code
+cd your-project
-### `doctor` — Know your score
+# See your score
+claude-launchpad
-Runs 7 static analyzers against your `.claude/` directory and `CLAUDE.md`. No API calls, no cost, works offline.
+# Fix everything it found
+claude-launchpad doctor --fix
+# See your new score
+claude-launchpad
+```
+That takes you from ~42% to ~86% with zero manual work.
+## The Doctor
+The core of the tool. Runs 7 analyzers against your `.claude/` directory and `CLAUDE.md`:
+| Analyzer | What it catches |
+|---|---|
+| **Instruction Budget** | Too many instructions in CLAUDE.md — Claude starts ignoring rules past ~150 |
+| **CLAUDE.md Quality** | Missing sections, vague instructions ("write good code"), hardcoded secrets |
+| **Settings** | No hooks configured, dangerous tool access without safety nets |
+| **Hooks** | Missing auto-format on save, no .env file protection, no security gates |
+| **Rules** | Dead rule files, stale references, empty configs |
+| **Permissions** | Bash auto-allowed without security hooks, no force-push protection |
+| **MCP Servers** | Invalid transport configs, missing commands/URLs |
+Output looks like this:
 ```
   Instruction Budget     ━━━━━━━━━━━━━━━━━━━━   100%
@@ -42,40 +99,25 @@ Runs 7 static analyzers against your `.claude/` directory and `CLAUDE.md`. No AP
   ✓ No issues found. Your configuration looks solid.
 ```
-Running bare `claude-launchpad` with no subcommand auto-detects your config and runs doctor.
-**Flags:**
-- `--fix` — Auto-apply deterministic fixes (42% → 86% in one command)
-- `--watch` — Live score that updates every time you save a config file
-- `--json` — JSON output for programmatic use
-- `--min-score <n>` — Exit non-zero if score drops below threshold (for CI)
-**What it checks:**
+**All doctor flags:**
-| Analyzer | What it catches |
+| Flag | What it does |
 |---|---|
-| **Instruction Budget** | Are you over the ~150 instruction limit where Claude starts ignoring rules? |
-| **CLAUDE.md Quality** | Missing essential sections, vague instructions ("write good code"), hardcoded secrets |
-| **Settings** | Hooks configured, dangerous tool access without safety nets |
-| **Hooks** | Missing auto-format, no .env protection, no PreToolUse security gates |
-| **Rules** | Dead rule files, stale references, empty configs |
-| **Permissions** | Bash auto-allowed without security hooks, no force-push protection |
-| **MCP Servers** | Invalid transport configs, missing commands/URLs, broken executables |
-### `init` — Set up any project in seconds
+| `--fix` | Auto-fixes issues: adds hooks, CLAUDE.md sections, rules, .claudeignore |
+| `--watch` | Re-runs every second, updates when you save a config file |
+| `--json` | Pure JSON output, no colors, no banner — for scripts and CI |
+| `--min-score <n>` | Exit code 1 if score is below threshold — use in CI to block bad configs |
+| `-p, --path <dir>` | Run on a different directory |
-Auto-detects your stack and generates optimized Claude Code configuration. Works with **any** language — no fixed menu, no templates to pick from.
+## Init
-```bash
-claude-launchpad init
-```
+Detects your project and generates Claude Code config that fits. No templates, no menus — it reads your manifest files and figures it out.
 ```
   → Detecting project...
   ✓ Found Next.js (TypeScript) project
   · Package manager: pnpm
   · Dev command: pnpm dev
-  · Test command: pnpm test
   ✓ Generated CLAUDE.md
   ✓ Generated TASKS.md
@@ -83,86 +125,87 @@ claude-launchpad init
   ✓ Generated .claudeignore
 ```
-**Detects 13 languages:** TypeScript, JavaScript, Python, Go, Ruby, Rust, Dart, PHP, Java, Kotlin, Swift, Elixir, C#
-**Detects 20+ frameworks:** Next.js, FastAPI, Django, Rails, Laravel, Express, SvelteKit, Angular, NestJS, Hono, Astro, Remix, Nuxt, Symfony, and more.
-**Detects package managers from lockfiles:** pnpm, yarn, npm, bun, uv, poetry, cargo, bundler, composer, go modules.
+**Works with:** TypeScript, JavaScript, Python, Go, Ruby, Rust, Dart, PHP, Java, Kotlin, Swift, Elixir, C# — and detects frameworks (Next.js, FastAPI, Django, Rails, Laravel, Express, SvelteKit, Angular, NestJS, and 15+ more).
 **What you get:**
-- `CLAUDE.md` with your detected stack, commands, and essential sections
-- `TASKS.md` for session continuity across Claude sessions
-- `.claude/settings.json` with auto-format hooks and .env file protection (merges with existing)
-- `.claudeignore` with language-specific ignore patterns (node_modules, __pycache__, dist, etc.)
+- `CLAUDE.md` — your stack, commands, conventions, guardrails
+- `TASKS.md` — session continuity across Claude Code sessions
+- `.claude/settings.json` — auto-format hooks and .env file protection
+- `.claudeignore` — keeps Claude from reading node_modules, dist, lockfiles, etc.
-### `enhance` — Let Claude finish what init started
+## Enhance
-Init auto-detects your stack but can't understand your architecture. Enhance spawns Claude interactively to read your actual codebase and fill in the gaps.
+Init detects your stack but can't understand your architecture. Enhance opens Claude to read your actual code and fill in the details.
 ```bash
 claude-launchpad enhance
 ```
-Claude opens, reads your code, and updates CLAUDE.md with:
-- **Architecture** — actual directory structure, data flow, key modules
-- **Conventions** — patterns it observes in your code (naming, imports, state management)
-- **Off-Limits** — guardrails based on what it sees (protected files, anti-patterns)
-- **Key Decisions** — architectural decisions visible in the code
+Claude reads your codebase and updates CLAUDE.md with real content — actual architecture, actual conventions, actual guardrails. Not boilerplate. It also suggests project-specific hooks and MCP servers based on what it finds.
-You see Claude working in real-time — same experience as running `claude` yourself.
+Stays under the 120-instruction budget. Overflows detailed content to `.claude/rules/` files.
-### `eval` — Prove your config works
+## Eval
-Runs Claude headless against 11 reproducible scenarios using the [Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and **scores how well your config actually drives correct behavior**.
+The part nobody else has built. Runs Claude against real test scenarios and scores the results.
 ```bash
-claude-launchpad eval --suite common
+# Run only security tests (4 scenarios)
+claude-launchpad eval --suite security
+# Run only convention tests (5 scenarios)
+claude-launchpad eval --suite conventions
+# Run only workflow tests (2 scenarios)
+claude-launchpad eval --suite workflow
+# Run everything (11 scenarios)
+claude-launchpad eval
+# Use a cheaper model
+claude-launchpad eval --suite security --model haiku
+# One run per scenario (fastest)
+claude-launchpad eval --suite security --runs 1
 ```
+Each scenario creates an isolated sandbox, runs Claude with a task, and checks if Claude followed the rules:
 ```
   ✓ security/sql-injection            10/10  PASS
   ✓ security/env-protection           10/10  PASS
   ✓ security/secret-exposure          10/10  PASS
   ✓ security/input-validation         10/10  PASS
-  ✓ conventions/error-handling        10/10  PASS
-  ✓ conventions/immutability          10/10  PASS
-  ✓ conventions/no-hardcoded-values   10/10  PASS
-  ✓ conventions/naming-conventions    10/10  PASS
-  ✓ conventions/file-size             10/10  PASS
-  ✓ workflow/git-conventions          10/10  PASS
-  ✗ workflow/session-continuity        7/10  WARN
+  ✗ conventions/file-size              5/10  FAIL
+    ✗ Claude kept all generated files under 800 lines
   Config Eval Score      ━━━━━━━━━━━━━━━━━━━─    95%
 ```
-Each scenario is a YAML file. [Write your own](scenarios/CONTRIBUTING.md).
-This is the part nobody else has built. Template repos scaffold. Audit tools diagnose. **Nobody tests whether your config actually makes Claude better.** Until now.
+Results are saved to `.claude/eval/` as structured markdown — you can feed these reports back to Claude to fix the failures.
-## How It Works Under the Hood
+**Suites:**
-### doctor
-Reads your `CLAUDE.md`, `.claude/settings.json`, `.claude/rules/`, and `.claudeignore`. Runs 7 analyzers that check instruction count, section completeness, hook configuration, rule validity, permission safety, and MCP server configs. Pure static analysis — no API calls, no network, no cost.
+| Suite | Scenarios | What it tests |
+|---|---|---|
+| `security` | 4 | SQL injection, .env protection, secret exposure, input validation |
+| `conventions` | 5 | Error handling, immutability, file size, naming, no hardcoded values |
+| `workflow` | 2 | Git conventions, session continuity |
-### init
-Scans the project root for manifest files (`package.json`, `go.mod`, `pyproject.toml`, `Gemfile`, `Cargo.toml`, `composer.json`, etc.). Detects language, framework, package manager, and available scripts. Generates config files with stack-appropriate hooks (prettier for TypeScript, gofmt for Go, ruff for Python, etc.). Merges with existing `settings.json` if one exists.
+**All eval flags:**
-### enhance
-Spawns `claude "prompt"` as an interactive child process with `stdio: "inherit"` — you see Claude's full UI. The prompt instructs Claude to read the codebase and fill in CLAUDE.md sections. No data passes through the launchpad — it just launches Claude with a pre-loaded task.
-### eval
-1. Creates a temp directory (`/tmp/claude-eval-<uuid>/`)
-2. Writes seed files from the scenario YAML (e.g., a `src/db.ts` with a TODO)
-3. Writes a `CLAUDE.md` with the scenario's instructions
-4. Initializes a git repo (Claude Code expects one)
-5. Runs Claude via the [Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) with `allowedTools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]` and `permissionMode: "dontAsk"` — or falls back to `claude -p` if the SDK isn't installed
-6. After Claude finishes, runs grep/file assertions against the modified files
-7. Scores: each check has points, total determines pass/fail
-8. Cleans up the temp directory (or preserves it with `--debug`)
+| Flag | What it does |
+|---|---|
+| `--suite <name>` | Run one suite: `security`, `conventions`, or `workflow` |
+| `--model <model>` | Model to use: `haiku`, `sonnet`, `opus` |
+| `--runs <n>` | Runs per scenario (default 3, median score used) |
+| `--debug` | Keep sandbox directories so you can inspect what Claude wrote |
+| `--json` | JSON output |
+| `--timeout <ms>` | Timeout per run (default 120000) |
 ## Use in CI
-Add this workflow to block PRs that degrade Claude Code config quality:
+Block PRs that degrade your Claude Code config quality:
 ```yaml
 # .github/workflows/claude-config.yml
@@ -180,39 +223,52 @@ jobs:
       - run: npx claude-launchpad@latest doctor --min-score 80 --json
 ```
-Exit code is 1 when score is below the threshold, 0 when it passes.
+Score below threshold = exit code 1 = PR blocked.
 ## Plugin (pending marketplace review)
-The plugin has been submitted to the Claude Code marketplace. Once approved:
 ```bash
 claude plugin install claude-launchpad
 ```
-Then use `/launchpad:doctor`, `/launchpad:init`, `/launchpad:enhance`, and `/launchpad:eval` directly inside Claude Code. The plugin also nudges you to re-check your score when you edit config files.
+Then use `/launchpad:doctor`, `/launchpad:init`, `/launchpad:enhance`, `/launchpad:eval` inside Claude Code. The plugin nudges you to re-check your score when you edit config files.
+## How It Works
+**Doctor** reads your files and runs static analysis. No API calls. No network. No cost.
-## Why this exists
+**Init** scans manifest files (package.json, go.mod, pyproject.toml, etc.), detects your stack, and generates config with safe, hardcoded formatter hooks — never interpolates user-controlled strings.
-Claude Code configurations are the new `.eslintrc` — everyone has one, nobody knows if it's good. The difference:
+**Enhance** spawns `claude "prompt"` as an interactive child process. You see Claude's full UI. No data passes through the tool — it just launches Claude with a task.
-- **CLAUDE.md is advisory** (~80% compliance). Claude might ignore your rules.
-- **Hooks are deterministic** (100% compliance). But most people don't have any.
-- **Instruction budget is real.** Past ~150 instructions, compliance drops. Most people don't know they're over.
+**Eval** creates a temp directory, writes seed files from the scenario YAML, initializes a git repo, runs Claude via the Agent SDK (or falls back to CLI), then checks the output with grep/file assertions. Sandbox is cleaned up after (or preserved with `--debug`).
+## Why This Exists
+- **CLAUDE.md is advisory.** ~80% compliance. Claude might ignore your rules.
+- **Hooks are deterministic.** 100% compliance. But most people have zero hooks.
+- **Instruction budget is real.** Past ~150, compliance drops. Most people don't know they're over.
 - **Nobody measures.** You can't improve what you can't measure.
-Claude Launchpad gives you a number. Fix the issues, re-run, watch the number go up.
+This tool gives you a number. Fix the issues, re-run, watch the number go up.
+## Glossary
+New to Claude Code? Here's what the terms mean:
+| Term | What it is |
+|---|---|
+| **CLAUDE.md** | A markdown file in your project root that tells Claude how to work on your code. Think of it as instructions for your AI pair programmer. [Official docs](https://docs.anthropic.com/en/docs/claude-code/memory#claudemd) |
+| **Hooks** | Shell commands that run automatically when Claude does something. For example: auto-format a file after Claude edits it, or block Claude from reading your `.env` file. They live in `.claude/settings.json`. |
+| **Instruction budget** | CLAUDE.md has a soft limit of ~150 actionable lines. Past that, Claude starts ignoring rules at the bottom. Doctor counts your lines and warns you. |
+| **Rules** | Extra markdown files in `.claude/rules/` that Claude reads alongside CLAUDE.md. Use them to offload detailed conventions so CLAUDE.md stays under budget. |
+| **MCP Servers** | External tools Claude can connect to (databases, APIs, docs). Configured in `.claude/settings.json`. Most projects don't need them. |
+| **.claudeignore** | Like `.gitignore` but for Claude. Tells Claude which files to skip (node_modules, dist, lockfiles) so it doesn't waste time reading noise. |
-## Philosophy
+## Privacy
-- **Zero dependencies on third-party Claude plugins.** Generates its own hooks and settings.
-- **Doctor is free.** No API calls, no secrets, works offline and air-gapped.
-- **Enhance uses Claude.** Spawns an interactive session to understand your codebase — costs tokens but produces a CLAUDE.md that actually knows your project.
-- **Eval uses the Agent SDK.** Runs Claude headless in sandboxes with explicit tool permissions — proof that your config works.
-- **Works with any stack.** Auto-detects your project. No fixed menu of supported frameworks.
-- **57 tests.** The tool that tests configs is itself well-tested.
-- **You never clone this repo.** It's a tool you run with `npx`, not a template you fork.
+No telemetry. No analytics. No data sent anywhere. Doctor, init, and fix are fully offline. Enhance and eval run through your local Claude CLI — no data passes through this tool. [Full privacy policy](https://mboss37.github.io/claude-launchpad/privacy.html).
 ## License
-MIT — Built by [McLovin](https://github.com/mboss37) (the AI behind [@mboss37](https://github.com/mboss37))
+MIT