claude-launchpad
Is your Claude Code setup actually good? This plugin tells you. It scans your CLAUDE.md, hooks, rules, and settings, gives you a score out o
Open source Repository Open in the app JSON README (API)
About
Is your Claude Code setup actually good? This plugin tells you. It scans your CLAUDE.md, hooks, rules, and settings, gives you a score out of 100, and auto-fixes what's broken. One command to set up any project. One command to fix common issues. One command to test if Claude actually follows your rules. Works with any language or framework.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- mboss37
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 6
- Forks
- 2
- Last push
- 2026-09-03T13:10:10Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
mboss37/claude-launchpad/claude-launchpad
README
# Claude Launchpad
[](https://www.npmjs.com/package/claude-launchpad)
[](https://www.npmjs.com/package/claude-launchpad)
[](https://github.com/mboss37/claude-launchpad)
[](https://github.com/mboss37/claude-launchpad/blob/master/LICENSE)
**Claude follows CLAUDE.md ~80% of the time. Hooks run at 100%. Most setups have zero hooks.**
Launchpad scores your coding-agent config, fixes gaps with hooks and permissions, and runs scenarios to prove the agent follows your rules. Local Cursor Agent projects can be scaffolded, diagnosed, repaired, and evaluated with `--harness cursor`. Memory is the same local SQLite store and MCP server for both harnesses (`memory install --harness claude|cursor|both`). Cursor Cloud memory is not supported.
Cursor can also consume Claude Code files (`CLAUDE.md`, `.claude/skills/`, `.claude/agents/`, supported hooks) when [third-party configuration](https://cursor.com/docs/reference/third-party-hooks) is enabled. That is a migration bridge, not the native target. Launchpad generates native Cursor files (`AGENTS.md`, `.cursor/`) and certifies them with a live Agent canary. Verified against Cursor Agent `2026.08.25-3e8eec8` via `pnpm canary:cursor`. Eval through Cursor Agent is `pnpm canary:cursor:eval`.
For developers using Claude Code or Cursor Agent who want consistent results: solo devs, vibe coders, AI-first teams.
## Install and See Your Score
```bash
npx claude-launchpad
```
```
Instruction Budget ━━━━━━━━━━━━━━━━━━━━ 100%
CLAUDE.md Quality ━━━━━━━━━━━━━━━━━━━━ 100%
Settings ━━━━━━━━━━━━━━━━━━━━ 100%
Hooks ━━━━━━━━━━━━━━━━━━━━ 100%
Rules ━━━━━━━━━━━━━━━━━━━━ 100%
Permissions ━━━━━━━━━━━━━━━━━━━━ 100%
MCP Servers ━━━━━━━━━━━━━━━━━━━━ 100%
Overall ━━━━━━━━━━━━━━━━━━━━ 100%
✓ No issues found. Your configuration looks solid.
```
A typical unconfigured project scores ~31%. After `--fix`, it jumps to ~91%.
## Quick Start
**New project:**
```bash
npx claude-launchpad init
```
Detects your stack, generates config, hooks, and permissions. Start at ~93%.
**Existing project:**
```bash
npx claude-launchpad doctor --fix
```
Scores your config, auto-repairs everything it can.
## The Three-File System + Workflow Rules
Without structure, CLAUDE.md becomes a dumping ground:
- Future ideas bury active guidance
- Sprint notes push conventions off-screen
- Past ~200 lines, Claude starts ignoring rules at the bottom
The three-file split keeps each concern where it belongs:
| File | Purpose | Example |
|---|---|---|
| `CLAUDE.md` | What Claude needs to know | Stack, commands, conventions, guardrails |
| `TASKS.md` | What we're doing now | Current sprint, session log (empty between sprints) |
| `BACKLOG.md` | What we're doing later | WP-NNN template, 7 mandatory fields, P0/P1/P2/P3 sections |
Init generates all three plus a path-scoped workflow rule: `.claude/rules/workflow.md` (Claude) or `.cursor/rules/workflow.mdc` (Cursor). It also installs a `workflow-check.sh` hook that injects drift warnings into the agent's context: a WP entry live in both files, TASKS.md > 80 lines, Current Sprint > 15 items, Session Log > 3 entries, and dependency-blind pulls.
Doctor flags MEDIUM when the workflow rule is missing, LOW when the hook is missing, and MEDIUM on duplicate `## Memory` headings. `--fix` installs or repairs any of them without clobbering existing user content. See the [workflow docs](https://mboss37.github.io/claude-launchpad/docs/workflow) for the full lifecycle.
## Commands
| Command | What it does | Runs |
|---|---|---|
| `claude-launchpad` | Score your config (routes to doctor) | Locally, free |
| `claude-launchpad init` | Detect stack, generate config + hooks + permissions | Locally, free |
| `claude-launchpad init --harness cursor` | Scaffold a local Cursor Agent project (`AGENTS.md`, `.cursor/`) | Locally, free |
| `claude-launchpad doctor --fix` | Auto-fix issues found by doctor (Claude, Cursor, or both) | Locally, free |
| `claude-launchpad doctor --harness cursor` | Score a Cursor Agent project; add `--fix` to repair Launchpad-managed files | Locally, free |
| `claude-launchpad eval` | Run Claude or Cursor Agent against test scenarios | Via the selected harness CLI/SDK |
| `claude-launchpad memory` | Optional knowledge base that persists across sessions | Locally |
| `/lp-enhance` (skill) | The agent reads your code and completes CLAUDE.md or AGENTS.md | Inside Claude Code or Cursor Agent |
## Doctor
Runs analyzers against the selected harness. Claude: `.claude/` and CLAUDE.md. Cursor: `AGENTS.md` and `.cursor/`. Scores stay separate. No API calls, no network, no cost.
**Analyzers:**
| Analyzer | What it catches |
|---|---|
| **Instruction Budget** | Too many instructions. Claude starts ignoring rules past ~200. |
| **CLAUDE.md Quality** | Missing sections, vague instructions, hardcoded secrets, duplicate `## Memory` headings |
| **Settings** | No hooks configured, dangerous tool access without safety nets |
| **Hooks** | Missing auto-format, no .env protection, dead PostCompact hooks (the event doesn't exist — `--fix` migrates to a SessionStart `compact` matcher), missing workflow-check hook, missing jq, no auto-sync on session end |
| **Rules** | Dead rule files, stale references, empty configs, missing `.claude/rules/workflow.md` |
| **Permissions** | Credential exposure (~/.ssh, ~/.aws), blanket Bash approval, bypass-mode unprotected |
| **MCP Servers** | Invalid transport configs, missing commands/URLs |
An optional Memory analyzer runs when agentic memory is detected.
**Flags:**
| Flag | What it does |
|---|---|
| `--fix` | Auto-fix: adds hooks, CLAUDE.md or AGENTS.md sections, BACKLOG.md, rules, .claudeignore / .cursorignore |
| `--fix --dry-run` | Preview fixes without applying them |
| `--watch` | Re-runs every second as you edit config files |
| `--json` | Pure JSON output for scripts and CI |
| `--min-score <n>` | Exit code 1 if score is below threshold (for CI) |
| `-p, --path <dir>` | Run on a different directory |
| `--harness` | `auto` (default), `claude`, `cursor`, or `both`. Scores stay separate. |
## Init
Reads your manifest files (package.json, go.mod, pyproject.toml, etc.) and generates config that fits. No templates, no menus.
```
→ Detecting project...
✓ Found Next.js project
· Package manager: pnpm
✓ Generated CLAUDE.md
✓ Generated TASKS.md
✓ Generated BACKLOG.md
✓ Generated .claude/settings.json (schema, permissions, hooks)
✓ Generated .claude/.gitignore
✓ Generated .claudeignore
✓ Generated .claude/rules/conventions.md
```
**What init writes (Claude, default):**
- Always: `CLAUDE.md`, `TASKS.md`, `BACKLOG.md`, `.claude/settings.json`
- Creates when missing: `.claude/.gitignore`, `.claudeignore`, `.claude/rules/conventions.md`, `.claude/rules/workflow.md`, `.claude/rules/hooks.md`, `.claude/rules/verification.md`, `.claude/agents/code-reviewer.md`
- Offers `/lp-enhance` install (project/global/skip) if not already present
**What init writes (`--harness cursor`):**
- Always: `AGENTS.md`, `TASKS.md`, `BACKLOG.md`, `.cursor/hooks.json`, `.cursorignore`
- Creates when missing: `.cursor/rules/*.mdc`, `.cursor/agents/code-reviewer.md`, `.cursor/skills/lp-enhance/SKILL.md`, hook scripts under `.cursor/hooks/`
- `--force` overwrites `AGENTS.md` only
**Supported stacks:** TypeScript, JavaScript, Python, Go, Ruby, Rust, Dart, PHP, Java, Kotlin, Swift, Elixir, C#. Detects frameworks: Next.js, FastAPI, Django, Rails, Laravel, Express, SvelteKit, Angular, NestJS, and 15+ more.
## Enhance
Init detects your stack but cannot read your architecture. The `/lp-enhance` skill runs inside Claude Code or Cursor Agent to fill in the details.
```
/lp-enhance
```
The agent reads your codebase and updates `CLAUDE.md` or `AGENTS.md` with real content: actual architecture, actual conventions, actual guardrails. Not boilerplate. It also suggests project-specific hooks and MCP servers.
Stays under the 200-instruction budget. Overflows detailed content to `.claude/rules/` or `.cursor/rules/*.mdc`. If the skill is missing, `doctor --fix` will create it.
**When to re-run:** after major refactors, new dependencies, or architecture changes.
## Eval
Runs the selected coding agent against real test scenarios and scores the results.
```bash
# Interactive mode (pick suite, runs, model)
claude-launchpad eval
# Or pass flags directly
claude-launchpad eval --suite security --runs 1 --model haiku
claude-launchpad eval --harness cursor --suite security --runs 1 --model auto
```
If both Claude and Cursor configs are present, `--harness` is required. Each scenario creates an isolated sandbox with only that harness's project config. It runs the agent and checks whether the configuration made it follow 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/file-size 5/10 FAIL
✗ Claude kept all generated files under 800 lines
Config Eval Score ━━━━━━━━━━━━━━━━━━━─ 95%
```
Results save to `.claude/eval/` or `.cursor/eval/` as structured markdown. Feed them back to the agent to fix failures.
**Suites:**
| Suite | Scenarios | What it tests |
|---|---|---|
| `security` | 7 | SQL injection, .env protection, secret exposure, input validation, credential read, env exfil via Bash, env-read-attempt |
| `conventions` | 5 | Error handling, immutability, file size, naming, no hardcoded values |
| `workflow` | 5 | Git conventions, session continuity, memory persistence, deferred tracking, premature-victory |
**Flags:**
| Flag | What it does |
|---|---|
| `--suite <name>` | Run one suite: `security`, `conventions`, or `workflow` |
| `-p, --path <dir>` | Project root to evaluate (defaults to cwd) |
| `--scenarios <path>` | Use a custom scenarios directory |
| `--harness <name>` | `claude` or `cursor` (required when both configs exist) |
| `--model <model>` | Model to use: `haiku`, `sonnet`, `opus`, or a Cursor model id / `auto` |
| `--runs <n>` | Runs per scenario (default 3, median score used) |
| `--debug` | Keep sandbox directories for inspection |
| `--json` | JSON output |
| `--timeout <ms>` | Timeout per run (default 120000) |
## Hooks
Instruction-file rules are ~80% reliable. Hooks are 100% enforced by the harness. Init and `--fix` set up these hooks automatically. Claude event names below; Cursor uses the native equivalents (`beforeReadFile`, `beforeShellExecution`, `afterFileEdit`, `postToolUse`, `sessionStart`).
| Hook | Trigger | What it does |
|---|---|---|
| **.env protection** | Before any Read/Write/Edit | Blocks Claude from reading `.env` files that contain secrets |
| **Force-push protection** | Before any Bash command | Blocks `git push --force` to prevent destroying remote history |
| **Auto-format** | After any Write/Edit | Runs your language's formatter (prettier, ruff, gofmt, rustfmt, etc.) |
| **SessionStart** | Session opens | Injects TASKS.md so Claude knows where you left off |
| **PostCompact** | After context compression | Re-injects TASKS.md so Claude doesn't lose sprint state mid-session |
| **workflow-check** | After BACKLOG.md/TASKS.md Edit/Write | Injects context warnings: WP entry in both files, TASKS.md > 80 lines, Current Sprint > 15 items, Session Log > 3 entries, dependency-blind pulls |
| **sprint-size / sprint-open** | Session start / `git commit` | Warns on microsprints (<3 WPs), oversized sprints (>7 WPs), new sprint opened without BACKLOG cleanup |
Claude Code memory projects get three additional hooks. Cursor Agent does not — it uses `memory_search` and explicit `memory sync` / `push` / `pull`:
| Hook | Trigger | What it does |
|---|---|---|
| **SessionStart pull** | Session opens | Auto-pulls memories from GitHub Gist |
| **SessionStart context** | Session opens | Injects the most relevant memories into Claude's context (6-signal scoring + diversity + token budget) |
| **SessionEnd push** | Session closes | Auto-pushes new memories to GitHub Gist |
## Memory (optional)
Claude's built-in memory resets per machine. Launchpad gives each project persistent, cross-device memory that syncs via a private GitHub Gist. Switch laptops and your decisions are already there.
**Why this memory and not another:**
- **Free cross-machine sync.** Native Claude Code memory is single-machine; cloud memory layers need API keys and subscriptions. Launchpad syncs through a private GitHub Gist you already have — zero cost, deletions propagate, machines converge.
- **Measured, not assumed.** The only local agent memory with a benchmark suite (59 tests) gating every release: retrieval quality, injection quality, decay accuracy, scale. `doctor` diagnoses memory health; `eval` proves behavior.
- **Zero infrastructure.** One native dep, stdio MCP, local SQLite. No Docker, no vector DB service, no localhost API server, no cloud account.
- **Engineered injection.** Session context is packed by 6-signal relevance scoring with diversity re-ranking under a token budget — not just "last N memories".
```bash
claude-launchpad memory
claude-launchpad memory install --harness cursor
```
Interactive setup if not installed, stats if it is. The one native dep is installed for you (`npm install -g better-sqlite3`) or on demand. Sync requires the [GitHub CLI](https://cli.github.com/). `--harness claude|cursor|both` writes the MCP file for the selected local harness. Cursor Agent uses `.cursor/mcp.json` and does not auto-inject memories; Cursor Cloud Agents cannot use this local server.
Once set up, `claude-launchpad memory sync` is the everyday command — pull + push in one call, so every machine has the same project brain. Deletions propagate too (tombstones): machines converge to the same memory set, never more, never less. This is the piece Claude Code's built-in memory doesn't do — see [built-in vs Launchpad memory](https://mboss37.github.io/claude-launchpad/docs/memory#built-in-memory-vs-launchpad-memory).
- Claude: relevant memories auto-injected at session start. Cursor: call `memory_search` — no auto-inject. New memories stored as the agent works.
- Stale knowledge fades, important decisions persist
- Each project has its own scoped memory
- `--dashboard` opens a terminal UI with vim nav, filtering, and search
Full flag and subcommand reference in [the memory docs](https://mboss37.github.io/claude-launchpad/docs/memory).
## Use in CI
Block PRs that degrade your agent config quality. `--min-score` gates each harness separately:
```yaml
# .github/workflows/agent-config.yml
name: Agent Config Quality
on:
pull_request:
paths: ['CLAUDE.md', '.claude/**', '.claudeignore', 'AGENTS.md', '.cursor/**', '.cursorignore']
jobs:
config-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '22' }
- run: npx claude-launchpad@latest doctor --min-score 80 --json
```
Score below threshold = exit code 1 = PR blocked.
## Glossary
New to the harnesses? Here's what the terms mean.
| Term | What it is |
|---|---|
| **CLAUDE.md** | Claude Code's project instruction file. [Official docs](https://docs.anthropic.com/en/docs/claude-code/memory#claudemd) |
| **AGENTS.md** | Cursor Agent's project instruction file. Same job as CLAUDE.md, different filename. |
| **TASKS.md** | Sprint tracker and session log. Shared by both harnesses. |
| **BACKLOG.md** | Where deferred features live. Priority tiers (P0/P1/P2) keep future ideas organized without cluttering TASKS.md. |
| **Hooks** | Commands that run automatically when the agent does something. Instruction-file rules are ~80% reliable. Hooks are 100% enforced. |
| **Instruction budget** | Soft limit of ~200 actionable lines in CLAUDE.md or AGENTS.md. Past that, rules at the bottom get ignored. Doctor counts them. |
| **Rules** | Extra files in `.claude/rules/` or `.cursor/rules/*.mdc` so the instruction file stays under budget. |
| **Compaction** | Claude Code compresses long conversations. A SessionStart `compact` matcher re-injects TASKS.md. Cursor uses `sessionStart`. |
| **MCP Servers** | External tools. Claude: `.mcp.json` or settings. Cursor: `.cursor/mcp.json`. |
| **.claudeignore / .cursorignore** | Like `.gitignore` for the agent — skip noise files. |
## Privacy
- No telemetry, no analytics, no data sent anywhere
- Doctor, init, and fix run fully offline
- Memory stores data locally at `~/.agentic-memory/`
- Sync (`memory push/pull`) uses a private GitHub Gist under your account
- Enhance runs inside the local Claude Code or Cursor Agent session; eval uses that harness's CLI/SDK
[Full privacy policy](https://mboss37.github.io/claude-launchpad/privacy.html).
## License
MIT