Enhances Claude to give you an optimal experience developing full-stack web apps with Wasp (React, Node.js, Prisma), by providing curated access to docs, workflows and best practices.
- version
- 1.3.1
- GitHub stars
- 14
Install
/plugin install wasp@wasp-agent-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add wasp-lang/wasp-agent-plugins.
What it does
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚡️ QUICK START ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 /wasp-plugin-init - initial setup (run this first!) 📖 /wasp-plugin-help - view all plugin features
Sponsors
Contents
Discovered from sourceSkills 6
add-feature
Add Wasp's batteries-included features to your app. Each invocation focuses on one feature at a time.
Before Starting
- Verify user is in the app directory (check for the Wasp config file:
main.waspormain.wasp.ts)
Available Wasp Features
Present these features to the user and let them choose ONE to configure:
| Feature | Description |
|---|---|
| App Branding | Set your app's name, description, and meta tags |
| Authentication | Add login methods (Email, Google, GitHub, etc.) |
| Email Provider | Configure email sending (SendGrid, Mailgun, etc.) |
| Database | Set up your database (PostgreSQL, SQLite, etc.) |
| Styling (CSS, UI) | Add Tailwind CSS or ShadCN UI (on top of Tailwind CSS) |
Feature Selection
Using the AskUserQuestion tool, ask the user which Wasp feature they'd like to configure:
- Use the most relevant options as selectable choices (limited to 2-4 options)
- Remind users they can select "Other" to choose from additional features
Execute Selected Feature
Based on the user's selection, follow the corresponding guides below. ALWAYS follow the feature guide's corresponding raw text documentation URLs and use it as the basis for assisting the user.
- App Branding → app-branding.md
- Authentication → authentication.md
- Email Provider → email-provider.md
- Database → database.md
- Styling (CSS, UI) → styling.md
Guidelines for Using AskUserQuestion with Lists
When asking the user to choose from fetched lists (e.g., auth methods, email providers):
-
Always display the full list to the user before asking them to choose, so they know all available options.
-
Use the most popular/common options as the selectable choices in
AskUserQuestion(limited to 2-4 options). -
Remind users they can select "Other" to specify any option from the full list that isn't shown in the quick-select options.
-
Example format:
Available auth methods: Username & Password, Email, Google, GitHub, Discord, Keycloak, Slack [AskUserQuestion with 3-4 most common options] Note: Select "Other" to choose from additional options like Discord, Keycloak, or Slack.
After Feature Completion
After completing a feature configuration:
- Summarize the changes made
- If applicable, let them know if there are any environment variables they need to set and ask them if they need guidance on how to set them
- If so, fetch the raw github doc file URL for the environment variables and guide the user through the process
- Ask if the user would like to configure another feature
- If yes, return to Feature Selection
deploying-app
Pre-Deployment
- Run a pre-deployment check via validating-pre-deployment to validate configuration.
- Present the list of supported
wasp deployproviders under the "Wasp Deploy" section of the docs and ask the user to choose one. - Follow the steps from the chosen provider's guide to deploy the app.
Verify Deployment
Open the deployed client URL. In Wasp 0.26+, verify the server returns HTTP 200 at /up and configure platform health checks to use that path.
OAuth Redirect URLs
If they user is using OAuth providers, inform them that they need to add the redirect URLs to the OAuth providers in the provider's dashboard. For example: https://your-server-url.com/auth/google/callback
More info can be found in the Wasp Social Auth Providers docs.
Deployment Interrupted
Safe to rerun: wasp deploy <provider> deploy
DO NOT rerun: wasp deploy <provider> launch commands (one-time only)
- Explore the current codebase
- Fetch the Wasp docs for the current project version
- Decide on a few improvements (if the user supplies arguments in the command, use them as a starting point, if not, your ideas can be app features, code improvements, enhancements, etc.)
- Present the improvements to the user with their names, descriptions, and pros and cons
User's assist request: $ARGUMENTS
Step 0: Get User Preferences
- Ask the user if they want to start the dev server(s) as a background task in the current session, or on their own in a separate terminal:
- Starting as a background task
- Pros: The agent has more autonomy, can respond directly to dev server logs (warnings, errors).
- Cons: Certain actions can be slower, and the user has less direct control. Server logs are only visibile to the user from within the
background taskstab.
- Starting externally (User)
- Pros: The user has more direct control over app development and the Wasp CLI commands. Can be advantageous for more advanced users.
- Cons: Debugging and feature discovery can be slower, as the agent doesn't have direct access to dev server logs (warnings, errors) or Wasp CLI commands.
- Starting as a background task
- Depending on the user's choice, follow the steps below and run the commands for the user as background tasks, or guide them through running them manually in a separate terminal.
Step 1: Prepare the Checkout
If node_modules is missing, install the project dependencies:
wasp install
If .env.server or .env.client are missing and .env.server.example or .env.client.example are available, create the missing file from the example file. Ask the user to edit the file to set the correct values.
Step 2: Ensure the Development Database is Running
Grep the .env.server file for DATABASE_URL. If no line starts with DATABASE_URL, continue following this step.
If the user does have their own DATABASE_URL env var set, move on to Step 3.
Check the schema.prisma file in the project root for the datasource block to see which database is being used.
SQLite
Skip to Step 3: SQLite stores data in a local file, no database server needed.
PostgreSQL
Start the managed database container as a background task:
wasp start db
Docker needs to be installed and running for the managed Postgres database container (wasp start db) to work.
Run this as a background task in the current session. Wait 5-15 seconds for the database to be ready.
Step 3: Run Database Migrations
If this is the first time starting the app, or if there are pending migrations, run the following command:
wasp db migrate-dev --name <migration-name>
Some apps require seed data to work properly. Run the following command to seed the database:
wasp db seed <name>
Step 4: Start Dev Server
Start the Wasp development server as a background task:
wasp start
Step 5: Verify Server is Running
Read the client and server URLs from wasp start output and verify the client loads.
In Wasp 0.26+, verify the server returns HTTP 200 at /up. Occupied ports are replaced automatically. Use --client-port and --server-port to choose ports, or --client-url and --server-url for externally accessible URLs. URL overrides do not choose listening ports. Development ports and URLs are managed by Wasp, so remove PORT, WASP_SERVER_URL, and WASP_WEB_CLIENT_URL from .env.server, REACT_APP_API_URL from .env.client, and server.port/server.strictPort from Vite config. Keep deployment environment variables unchanged.
In Wasp 0.26+, managed databases also select a free port. Wasp discovers it automatically. Use wasp start db --db-port <port> when a fixed database port is needed.
If started as background task in current session: Listen to the output for development and debugging information. If started externally: Instruct the user to check the output of the external terminal and share its output with you.
Step 6: Connect Browser Console Access (Important!)
This step is critical for effective development and debugging. Without browser console access, the agent cannot see client-side errors, warnings, or React issues that occur in the browser.
Ask the user (via the AskUserQuestion tool) which method they'd like to use for giving the agent visibility into the browser console:
| Option | Description |
|---|---|
| Chrome DevTools MCP (recommended) | Must be installed |
| Built-in Chrome | Use Claude Code's built-in browser connection (check status with /chrome command) |
| Manual | User will manually copy/paste console output when needed |
| Other | User has another preference |
For the Chrome DevTools MCP option, if not already installed, add the following config to their mcp client:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
- run the check-wasp-init hook using the Bash tool with
nodecommand to check if the Wasp plugin has been initialized. - let the user know if the Wasp plugin has been initialized or not.
- if the Wasp plugin has not been initialized (the hook outputs JSON), let the user know they should take care of this first by running
/wasp-plugin-init:
⚠️
The Wasp plugin hasn't been initialized for the current project.
Run `/wasp-plugin-init` to get the plugin's full functionality.
- display the Wasp Plugin for Claude Code section to the user exactly as it is below.
--- --- 🐝 🐝 🐝 --- ---
🐝 Wasp Plugin for Claude Code
What This Plugin Does
This plugin makes Claude Code, Codex, Copilot, etc. work better with Wasp by:
- Using the right documentation — Automatically fetches the correct Wasp docs for your project's version
- Avoiding common mistakes — Provides Wasp-specific tips, patterns, and best practices so the agent doesn't hallucinate or use outdated approaches
- Guided workflows — Skills and commands so the agent can walk you through setting up Wasp's batteries-included features (auth, email, database, styling) and deploying
- Full debugging visibility — Start managed databases, dev servers, and connect browser console access so the agent has full development and debugging visibility across the entire stack
The result: The agent actually understands Wasp instead of guessing.
Quick Reference
Skills:
add-feature - Add Wasp's built-in features (auth, email, database, styling)
deploying-app - Guided deployment to Railway or Fly.io
expert-advice - Get advice on app improvements and functionality from a Wasp expert
start-dev-server - Start dev environment with full debugging visibility (db -> server -> browser console)
wasp-plugin-init - Adds Wasp knowledge, LLM-friendly documentation fetching instructions, and best practices to your project's CLAUDE.md or AGENTS.md file
💬 Example Prompts
- "Add Google authentication to my app"
- "Help me add ShadCN UI to my app"
- "Migrate the database from SQLite to PostgreSQL and start it for me"
- "Set up email sending with SendGrid"
- "Solve the errors in the browser using the Chrome DevTools MCP server"
- "Why isn't my recurring job working?"
- "Deploy my app to Railway"
📖 Documentation Access
The plugin ensures Claude detects your project's Wasp version and references the correct, LLM-friendly documentation.
🫂 Community & Contribute
Join the Wasp Discord for help and web dev discussion. Submit issues, feedback, or PRs: Wasp Agent Plugins
-
inform the user that this process will give their agent (Claude, Codex, Copilot, etc.) access to knowledge on Wasp's features, commands, workflows, and best practices by importing the
general-wasp-knowledge.mdfile into the user's AGENTS.md or CLAUDE.md file. Use the AskUserQuestion tool (or equivalent) to: a) ask the user if they want to continue, b) ask if they are using Claude Code (CLAUDE.md) or other agents like Codex, Gemini, Copilot, etc. (AGENTS.md). -
if the user is using Claude Code, follow the Claude Code memory instructions. If the user is using other agents, follow the Other agents memory instructions.
-
inform the user that process is complete and they can run
/wasp-plugin-helpto see the plugin's available skills and features. -
recommend the user do the following for the best Wasp development experience with Claude, Codex, Copilot, etc.:
- Start the dev server: Tell it to run the 'start-dev-server' skill to start the Wasp app and give it access to server logs, build errors, and Wasp CLI commands
- Enable Chrome DevTools: Prompt it to
use the Chrome DevTools MCP serverto give it visibility into browser console logs, network requests, and runtime errors
Explain that together these provide end-to-end insight (backend + frontend) for faster debugging and development.
Claude Code memory
- get the plugin version from
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json(versionfield). Use it below as{VERSION}. - check if
.claude/wasp/.wasp-plugin-initialized-v{VERSION}already exists. If it does, inform the user the plugin is already initialized for this version and skip the remaining steps. - check for any old marker files matching the pattern
.wasp-plugin-initialized*in.claude/wasp/. If found, remove them — this is a version upgrade:
rm -f .claude/wasp/.wasp-plugin-initialized*
- copy
general-wasp-knowledge.mdto the user's project root.claude/waspdirectory:
mkdir -p .claude/wasp && cp ./general-wasp-knowledge.md .claude/wasp/general-wasp-knowledge.md
- if the CLAUDE.md file does not already contain a
# Wasp Knowledgesection, append it as an import:
# Wasp Knowledge
Wasp knowledge can be found at @.claude/wasp/general-wasp-knowledge.md
- create the versioned marker file so the plugin knows this version's init has been run:
touch .claude/wasp/.wasp-plugin-initialized-v{VERSION}
Other agents memory
- get the plugin version from
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json(versionfield). Use it below as{VERSION}. - if the AGENTS.md file already contains a section starting with
# Wasp Knowledge [GENERATED BY WASP, remove that entire section (from the heading to the next#heading or end of file) before adding the new one. - append the entire contents of
general-wasp-knowledge.mdinto the user's AGENTS.md file:- Append a new section at the end of the file with the title
# Wasp Knowledge [GENERATED BY WASP v{VERSION}]. - Copy and paste the contents of
general-wasp-knowledge.mdinto this new section.
- Append a new section at the end of the file with the title
Hooks 1
MCP servers 1
Details
- Marketplace
- wasp-lang/wasp-agent-plugins
- Source
- plugins/wasp
- Author
- Wasp
- Category
- Framework
- License
- MIT
- Keywords
- wasp, full-stack, react, nodejs, deployment, authentication, web-development
