Skip to main content

​
Your First 5 Minutes with HAI Build

This guide will take you from installation to successfully completing your first AI-assisted development task.
Before you begin, ensure you’ve installed HAI Build and configured at least one LLM provider.

​
Understanding HAI Build’s Workflow

HAI Build operates differently from autocomplete tools. Here’s how it works:
1

Analyze

You describe what you want to achieve. HAI analyzes your request and explores your codebase
2

Plan

HAI presents a clear plan outlining what it will do and why
3

Review

You review the plan and proposed changes before anything is applied
4

Execute

Upon approval, HAI executes the plan and modifies your code
You maintain full control at every step. HAI never makes changes without your explicit approval.

​
Task 1: Analyze Your Project Structure

Let’s start with something simple to understand how HAI explores and understands codebases.
1

Open Your Project

Open a workspace or folder in VS Code that contains code you want to work with
2

Open HAI Build

Click the HAI icon in the activity bar or press Ctrl+' (Windows/Linux) or Cmd+' (macOS)
3

Start a New Task

Click the + (New Task) button in the HAI sidebar
4

Ask About Your Project

Type: “Analyze the structure of this project and explain the main components”
HAI Analyzing Codebase

​
What to Observe

Watch how HAI:
  • Reads files: You’ll see HAI exploring your codebase in the activity feed
  • Builds context: HAI identifies key files, dependencies, and architecture patterns
  • Asks questions: If anything is unclear, HAI will ask for clarification
  • Provides analysis: You receive a structured explanation of your project
HAI’s initial exploration helps it understand your codebase structure. This context improves all subsequent tasks.

​
Task 2: Generate Code with Context

Now let’s have HAI write some code based on your project’s patterns.
1

Start a New Task

Click the + button to begin a fresh task
2

Describe Your Goal

Be specific about what you want. For example:“Create a new utility function called formatUserData that takes a user object and returns a formatted string with the user’s full name and email. Follow the existing code style in this project.”
3

Review the Plan

HAI will present a plan showing:
  • Which files it will create or modify
  • What the implementation will look like
  • Why it chose this approach
4

Approve or Request Changes

  • Type “Yes” or “Approve” to proceed
  • Or ask HAI to adjust the approach: “Can you add input validation?”
HAI Planning

​
Understanding the Diff View

When HAI proposes changes, you’ll see: 
// Current code
export function getUserName(user) {
  return user.name;
}
  • Red lines: Code being removed
  • Green lines: Code being added
  • White lines: Unchanged context
Always review diffs carefully before approving. While HAI is intelligent, you’re the final decision-maker for your codebase.

​
Task 3: Refactor Existing Code

Let’s improve existing code while maintaining functionality.
1

Select Code to Refactor

Highlight a function or section of code in your editor
2

Add to HAI

Right-click and select “Add to HAI” or press Ctrl+' / Cmd+' with text selected
3

Request Improvement

HAI will include the selected code in context. Request specific improvements:“Refactor this function to be more readable and add TypeScript types. Also add error handling for edge cases.”
4

Review Suggestions

HAI will show the refactored version with explanations of changes

​
Alternative: Use Context Menu

For common operations, use the context menu shortcuts: 
# Right-click selected code
Add to HAI          - Include code in conversation
Explain with HAI    - Get detailed explanation
Improve with HAI    - Request improvements

​
Task 4: Work with HAI Tasks Integration

If you’re using Specif AI for task generation:
1

Load Tasks

Click the checklist icon in the HAI sidebar to open HAI Tasks
2

Import from Specif AI

Load AI-generated user stories and tasks directly into HAI
3

View Task Details

Click the eye icon next to any task to see:
  • Task description and objectives
  • Prerequisites and dependencies
  • Expected outcomes
4

Execute Task

Click Execute to have HAI begin working on the task automatically
HAI Tasks Detailed View
HAI Tasks streamlines your workflow by centralizing AI-driven tasks from ideation to execution.

​
Advanced Workflows

​
Using Domain Experts

Customize HAI’s behavior with domain-specific experts:
1

Access Experts

Navigate to Settings > Experts in the HAI sidebar
2

Choose Built-in Expert

Select from .NET, Terraform, Node.js, or Go experts for predefined best practices
3

Create Custom Expert

Define your own guidelines and attach reference documentation:
  • Expert name (required)
  • Custom guidelines in prompt.md (required)
  • Up to 3 reference document links (optional)
4

Use in Tasks

When starting a task, HAI will apply the selected expert’s context and guidelines
Custom experts are stored in .hai-experts/[expert-name]/ with metadata.json and prompt.md. Reference documents are processed into the docs/ subfolder.

​
Git Integration

Let HAI help with version control:
1

Stage Your Changes

Use Git to stage files as usual (git add or VS Code source control)
2

Generate Commit Message

Click the HAI icon in the Source Control title bar, or use Command Palette:HAI: Generate Commit Message with HAI
3

Review Generated Message

HAI analyzes your staged changes and generates a meaningful commit message
4

Edit and Commit

Edit the message if needed, then commit as normal
feat: Add user data formatting utility

- Implement formatUserData function with email and name formatting
- Add input validation for user objects
- Follow existing project code style conventions
- Include TypeScript types for type safety

​
MCP Server Integration

Extend HAI’s capabilities with Model Context Protocol servers:
1

Open MCP Marketplace

Click the server icon in HAI sidebar navigation
2

Browse Available Servers

Explore integrations for:
  • Database connections (PostgreSQL, MongoDB, etc.)
  • External APIs (GitHub, Slack, etc.)
  • Development tools (Docker, Kubernetes, etc.)
3

Install and Configure

Install desired servers and provide configuration (connection strings, API keys)
4

Use in Tasks

HAI can now interact with these systems. For example:“Query the users table in my PostgreSQL database and create a report of active users”

​
Jupyter Notebook Support

For data science and ML workflows: 
# From notebook toolbar
Generate Jupyter Cell with HAI  - Create new cell with AI

# From cell context menu
Explain Jupyter Cell with HAI   - Get cell explanation
Improve Jupyter Cell with HAI   - Optimize cell code

​
Best Practices

Be Specific

Provide clear, detailed descriptions of what you want to achieve. Include context about your project’s architecture and constraints.

Review Everything

Always review proposed changes before approval. HAI is intelligent but you know your codebase best.

Iterate Freely

If HAI’s first approach isn’t quite right, ask for adjustments. The conversation is iterative.

Leverage Context

Use “Add to HAI” to include relevant code. More context leads to better results.

​
Effective Prompting Examples

"Create a REST API endpoint for user registration that follows 
the existing authentication pattern in auth.service.ts. Include 
input validation, password hashing, and proper error handling."

"Refactor the PaymentProcessor class to use dependency injection 
and follow SOLID principles. Maintain backward compatibility with 
existing code."

"Add comprehensive unit tests for the UserService class, covering 
happy paths and error cases. Use the testing patterns from existing 
test files."
The more context and specificity you provide, the better HAI can understand your needs and generate appropriate solutions.

​
Managing HAI’s Activity

​
Task History

View and restore previous conversations:
1

Open History

Click the history icon (clock) in the HAI sidebar
2

Browse Tasks

See all previous tasks with timestamps and descriptions
3

Resume or Review

Click any task to review the conversation and continue if needed

​
Checkpoints and Rollback

HAI uses checkpoints to enable easy rollback:
HAI Transparency
  • Each approved change creates a checkpoint
  • You can revert to any previous state
  • Full transparency into every file read and modification

​
Common Workflows

​
Adding a New Feature

1

Describe the Feature

“Add a dark mode toggle to the settings page that persists user preference in localStorage”
2

Review Plan

HAI will outline which components to modify and what new code to create
3

Approve Implementation

Review the proposed changes and approve
4

Test and Iterate

Test the feature. If adjustments are needed, ask HAI to refine

​
Fixing a Bug

1

Describe the Bug

Include:
  • What’s happening (unexpected behavior)
  • What should happen (expected behavior)
  • Steps to reproduce
  • Any error messages
2

Help HAI Investigate

Add relevant code to context using “Add to HAI”
3

Review Proposed Fix

HAI will identify the root cause and propose a solution
4

Verify Fix

Test the fix and confirm it resolves the issue

​
Writing Documentation

1

Select Code

Highlight a function, class, or module
2

Request Documentation

“Add JSDoc comments to this function with parameter descriptions, return value, and usage examples”
3

Review and Approve

Verify the documentation is accurate and complete

​
Keyboard Shortcuts Cheat Sheet

# Open HAI chat
Ctrl+' (Windows/Linux) | Cmd+' (macOS)

# Add selected code to HAI
Select code + Ctrl+' | Cmd+'

# New task
Click + button in sidebar

# Open settings
Click gear icon in sidebar

​
Troubleshooting Common Issues

​
HAI Doesn’t Understand Context

1

Provide More Information

Use “Add to HAI” to include relevant files and code
2

Be More Specific

Clarify your request with details about architecture and constraints
3

Reference Files

Mention specific files: “Look at user.service.ts for the pattern to follow”

​
Changes Not Applied as Expected

1

Review Diffs Carefully

Ensure you understand what’s being changed before approval
2

Request Adjustments

If the approach isn’t right, ask HAI to modify: “Can you preserve the existing error handling?”
3

Use Checkpoints

Revert to a previous state if needed

​
Performance Issues

1

Check Model Selection

Faster models like Claude Haiku or GPT-3.5 provide quicker responses
2

Limit Context

For large projects, be selective about which files to include in context
3

Use Targeted Queries

Break large tasks into smaller, focused subtasks

​
Next Steps

Now that you’re productive with HAI Build:

Explore Custom Experts

Create domain-specific experts for your team’s standards and practices

Try MCP Integration

Connect HAI to databases, APIs, and external tools

Set Up Telemetry

Monitor AI usage across your team with Langfuse or PostHog

Join the Community

Contribute to HAI Build and share your experiences

​
Get Help

Documentation

Browse comprehensive guides and references

GitHub Issues

Report bugs or request features

Discussions

Ask questions and share ideas

Email Support

Contact the HAI team directly
Remember: HAI Build is designed to assist and enhance your development workflow, not replace your expertise. You’re always in control.

Build docs developers (and LLMs) love

Get started for freeTalk to us