Step-by-Step Guide

BuildFix User Guide

Everything you need to get started with BuildFix, from initial setup to advanced features.

Table of Contents

1. Getting Started2. Setting Up API Keys3. Creating Your First Project4. Using the Development Page5. Setting Up Auto-Healing6. Managing Knowledge Base

1. Getting Started

Sign Up

  1. 1.Navigate to buildfix.dev
  2. 2.Click "Start Building Free" or "Sign In"
  3. 3.Create an account using email or OAuth (Google, GitHub)
  4. 4.Complete your profile setup
[Screenshot: Sign up page]

No Credit Card Required

BuildFix is completely free while we build our user base. You only pay for API usage to providers you already use (Anthropic, GitHub, Vercel).

2. Setting Up API Keys

Required API Keys

BuildFix uses a BYOK (Bring Your Own Key) model. You'll need these API keys:

Anthropic Claude API Key

  1. 1.Go to console.anthropic.com
  2. 2.Sign up or log in
  3. 3.Navigate to "API Keys" in the left sidebar
  4. 4.Click "Create Key" and give it a name like "BuildFix"
  5. 5.Copy the key (starts with sk-ant-...)
[Screenshot: Anthropic console with API key creation]

GitHub Personal Access Token

  1. 1.Go to github.com/settings/tokens
  2. 2.Click "Generate new token" â†' "Generate new token (classic)"
  3. 3.Name it "BuildFix" and set expiration (90 days or longer)
  4. 4.Select scopes: repo (full control of private repositories)
  5. 5.Click "Generate token" and copy it (starts with ghp_...)
[Screenshot: GitHub token creation with repo scope selected]

Vercel Token (Optional)

Only needed if you want auto-healing for Vercel deployments

  1. 1.Go to vercel.com/account/tokens
  2. 2.Click "Create Token"
  3. 3.Name it "BuildFix" and set expiration
  4. 4.Select scope: "Full Account" (for webhook setup)
  5. 5.Copy the token

Adding Keys to BuildFix

  1. 1.Navigate to Settings â†' API Keys in BuildFix
  2. 2.Paste your Anthropic API key in the first field
  3. 3.Paste your GitHub token in the second field
  4. 4.(Optional) Paste your Vercel token in the third field
  5. 5.Click "Save Keys" - they'll be encrypted and stored securely
[Screenshot: BuildFix settings page with API key fields]

Keys are Encrypted

Your API keys are encrypted at rest with AES-256. BuildFix never shares your keys with anyone. You can revoke access anytime by rotating your keys in the provider's dashboard.

3. Creating Your First Project

Step-by-Step

  1. 1.

    Navigate to Projects

    Click "Projects" in the sidebar, then "Create New Project"

  2. 2.

    Enter Project Details

    • Project Name: e.g., "My SaaS App"
    • GitHub Repository: e.g., "username/my-saas-app"
    • Branch: Usually "main" or "master"
    • Framework: Select your tech stack (Next.js, React, etc.)
  3. 3.

    Connect Vercel (Optional)

    If you're using Vercel, enter your Vercel Project ID for auto-healing

  4. 4.

    Create Project

    Click "Create" - BuildFix will verify GitHub access and initialize your project

[Screenshot: Project creation form with fields filled out]

What Happens Next

After creating your project, BuildFix automatically:

  • Verifies GitHub access by fetching your repository
  • Creates a Knowledge Base structure in .metadev/knowledge/
  • Initializes context files with best practices
  • Makes the project available on your Development page

4. Using the Development Page

The Interface

The Development page is where the magic happens. It's your AI-powered code generation interface.

[Screenshot: Development page with main interface elements labeled]

Main Components:

  • 1
    Project Selector: Choose which project you're working on
  • 2
    Mode Toggle: Switch between Planning (surgical edits) and Normal (full generation)
  • 3
    Prompt Field: Describe what you want to build in natural language
  • 4
    Model Selector: Choose AI model (Haiku, Sonnet, Opus)
  • 5
    Results Panel: Shows generated code with diff view

Generating Code

Planning Mode (Quick Edits)

Best for small, targeted changes to existing files:

  1. 1. Select "Planning Mode"
  2. 2. Choose the file you want to edit
  3. 3. Write a prompt like: "Add a loading spinner to the submit button"
  4. 4. Click "Generate Plan"
  5. 5. Review the surgical edits (line-by-line changes)
  6. 6. Click "Execute Plan" to apply changes
  7. 7. Review the diff and create a PR
[Screenshot: Planning mode with surgical edits displayed]

Normal Mode (Full Generation)

Best for creating new files or major changes:

  1. 1. Select "Normal Mode"
  2. 2. Choose your AI model (Sonnet recommended)
  3. 3. Write a detailed prompt: "Create a dashboard component with 3 charts showing user growth, revenue, and activity"
  4. 4. Click "Generate"
  5. 5. Wait for 5-layer validation to complete
  6. 6. Review the generated code and diff
  7. 7. Click "Create Pull Request"
[Screenshot: Normal mode with generated code and validation status]

Pro Tips for Better Prompts

  • ✓ Be specific: "Add a dark mode toggle to the navbar" vs "improve navbar"
  • ✓ Include context: "Using Tailwind CSS, create a modal that..."
  • ✓ Mention constraints: "Must be mobile-responsive and accessible"
  • ✓ Reference existing patterns: "Following the same style as the settings page"

5. Setting Up Auto-Healing

What is Auto-Healing?

Auto-healing watches your Vercel deployments and automatically creates fix PRs when builds fail. It's like having a developer on call 24/7.

Example: You push code at 2 AM → Build fails → BuildFix detects it in <1 second → Analyzes the error → Creates a PR with the fix → All in ~12 seconds

Configuring Vercel Webhook

  1. 1.

    Get Your Webhook URL

    In BuildFix, go to your Project Settings → Webhooks

    Copy the webhook URL (looks like: https://buildfix.dev/api/webhook/vercel)

  2. 2.

    Go to Vercel Project Settings

    Open your project in Vercel Dashboard → Settings → Git → Deploy Hooks

  3. 3.

    Add Webhook

    • • Paste the BuildFix webhook URL
    • • Select events: "Deployment Failed"
    • • Save the webhook
  4. 4.

    Test the Connection

    Trigger a test event in Vercel to verify BuildFix receives it

[Screenshot: Vercel webhook configuration page]

Auto-Healing is Live!

From now on, whenever a Vercel deployment fails, BuildFix will automatically analyze it and create a fix PR. You'll get a notification and can review/merge the PR.

6. Managing Your Knowledge Base

What is the Knowledge Base?

Your project's Knowledge Base contains all the patterns, rules, and conventions that make your code consistent. It lives in .metadev/knowledge/ in your repository.

Knowledge Base Files:

patterns.json

Your coding conventions and patterns

mistakes.json

Documented errors and their fixes (auto-updated)

rules.json

Architectural rules and constraints

react-patterns.json

React-specific best practices

Managing Your KB

You can manage your Knowledge Base from the BuildFix interface:

  1. 1.Navigate to your Project → Knowledge Base tab
  2. 2.View and edit any of the JSON files
  3. 3.Use the "Add Pattern" button to document new conventions
  4. 4.Review auto-learned mistakes from the mistakes.json file
  5. 5.Changes are committed directly to your GitHub repo
[Screenshot: Knowledge Base management interface]

Why This Matters

The Knowledge Base is what makes BuildFix get smarter over time. Every mistake it learns becomes a pattern it avoids. Your code stays consistent, and the same errors never happen twice.

Think of it as your project's institutional memory—the collective wisdom that normally lives in senior developers' heads, now documented and automated.

You're All Set! 🎉

You now know everything you need to use BuildFix effectively.

Start BuildingTechnical DocsFAQ