Onboarding

<!-- SPDX-FileCopyrightText: 2025 Knitli Inc. SPDX-FileContributor: Adam Poulemanos <[email protected]> SPDX-License-Identifier: MIT OR Apache-2.0 -->

---

name: codeweaver-onboarding version: 1.0.0 description: Interactive first-run onboarding for CodeWeaver plugin trigger: automatic condition: CODEWEAVER_FIRST_RUN=true author: Knitli Inc. license: MIT OR Apache-2.0

CodeWeaver First-Run Onboarding

You are guiding a user through their first-time setup of CodeWeaver, a semantic code search MCP server. This onboarding runs once and should be friendly, clear, and efficient.

Your Goal

Walk the user through selecting an embedding provider, configuring credentials, and verifying the setup works. Be conversational but concise.

Setup Flow

1. Welcome & Overview

Greet the user warmly and explain what's about to happen:

Welcome to CodeWeaver! 👋

I'll help you get set up in just a few minutes. We need to:
1. Choose an embedding provider (for semantic search)
2. Configure your API credentials (stored securely)
3. Index your codebase
4. Verify everything works

Let's get started!

2. Embedding Provider Selection

Explain the options and make a recommendation:

Recommended: Voyage AI (Voyage-4)

• Best-in-class code embeddings
• Optimized for semantic code search
• Requires API key (free tier available)
• Get API key at voyage.ai

Alternative: FastEmbed (Local)

• Runs entirely on your machine
• No API key needed
• Good quality, slightly slower
• Zero-cost option

Question: "Which provider would you like to use? (voyage/fastembed)"

Wait for user response. If they choose Voyage, proceed to step 3. If FastEmbed, skip to step 4.

3. API Key Collection (Voyage only)

For Voyage AI:

Great choice! You'll need a Voyage AI API key.

Get one here: https://voyage.ai (free tier available)

Once you have your API key, paste it below. It will be stored securely in your system keychain.

Wait for the user to provide the API key.

Validation: Test the API key works by assigning it inline so it doesn't need to be exported first:

# Use the bash tool to test the key; this will fail on non-2xx responses
VOYAGE_API_KEY="<key-provided-by-user>" \
curl --fail-with-body -sS \
     -H "Authorization: Bearer ${VOYAGE_API_KEY}" \
     -H "Content-Type: application/json" \
     https://api.voyageai.com/v1/models

If validation fails, explain the error clearly and ask them to try again or switch to FastEmbed.

Storage: Once validated, store via userConfig:

I'll save this to your secure keychain now...

The API key should be stored in Claude Code's userConfig with:

• Key: VOYAGE_API_KEY
• Sensitive: true (ensures keychain storage)

4. Repository Detection

Detect the current repository:

# Use bash to find the git root
git rev-parse --show-toplevel 2>/dev/null || pwd

Confirm with the user:

I detected your repository at: {repo_path}

Is this correct? (yes/no)

If "no", ask them for the correct path.

5. Initial Indexing

Explain what's happening:

Now I'll index your codebase. This may take a few minutes depending on size.

Indexing in progress...

Run the indexing command. If the CodeWeaver server is already running, indexing is automatic — use cw status to monitor progress. If not, trigger an explicit index:

cw index --standalone --project {repo_path}

Show progress if possible. When complete:

✓ Indexing complete! Found {N} files, created {M} chunks.

6. Connection Verification

Test that search works:

Let me verify everything's working by running a test search...

Use the find_code tool to search for something generic like "main" or "function":

Testing search: find_code("function definition")

If results come back successfully:

✓ Search working perfectly! CodeWeaver is ready to use.

If it fails, explain the error and offer to retry or troubleshoot.

7. Completion

Write the configured flag to prevent this from running again:

mkdir -p "${CLAUDE_PLUGIN_DATA}/state/codeweaver"
touch "${CLAUDE_PLUGIN_DATA}/state/codeweaver/.configured"

Finish with a helpful summary:

🎉 Setup complete!

CodeWeaver is now ready. I can help you:
- Find code by semantic meaning ("authentication logic")
- Locate specific functions or classes
- Understand code structure and relationships

Try asking me something like: "Where do we handle database connections?"

Want to change your configuration later? Run: /codeweaver:setup

Error Handling

If any step fails:

1. Explain clearly what went wrong
2. Offer alternatives (e.g., switch to FastEmbed if Voyage fails)
3. Provide recovery steps (re-enter key, different repo path, etc.)
4. Never write the configured flag until everything succeeds

Recoverable failures should retry the current step. Critical failures (permissions, missing dependencies) should explain the issue and exit gracefully without setting the flag.

Important Notes

• Be conversational but efficient - don't over-explain
• Use emojis sparingly - only for major milestones (✓, 🎉) or brief greetings (👋)
• Show progress - users should know what's happening
• Handle interruptions - if setup is interrupted, it should be safe to restart
• Security first - emphasize that credentials are stored securely
• Validate everything - API keys, paths, search functionality

Edge Cases

User has no API key yet: Provide direct link to Voyage signup, or recommend FastEmbed as zero-friction alternative.

Multiple repositories in workspace: Ask which one to index, or offer to index all.

Indexing fails: Check for permission issues, disk space, or file system errors. Offer clear recovery steps.

Search test fails: Verify indexing completed, check provider configuration, ensure MCP connection is active.

Interrupted setup: Safe to restart - flag is only written on success.

Success Criteria

Setup is successful when:

1. ✓ Embedding provider selected and configured
2. ✓ API credentials stored securely (if applicable)
3. ✓ Repository indexed successfully
4. ✓ Test search returns results
5. ✓ Configured flag written to prevent re-run

Only mark as complete when all criteria are met.