End-to-end testing has always been the gold standard for verifying that your application actually works the way users experience it. But let’s be honest: writing and maintaining E2E tests is often a thankless job. Flaky selectors, timing issues, brittle test code that breaks with every UI change, the pain points are real and numerous.

What if instead of writing test code, you could simply describe what you want to test in plain language, and have an AI assistant execute those tests for you, then generate a detailed report of what happened? That’s exactly what becomes possible when you combine the Chrome DevTools MCP server with AI-powered testing workflows.

This is Part 2 of our Chrome DevTools MCP series. In Part 1 (Chrome DevTools MCP Server Guide), we explored the fundamentals of the Chrome DevTools MCP server and its tools for browser automation. Now, we’re going to put those tools to work in a complete, practical workflow: taking a product requirements document, generating test scenarios, executing them automatically, and producing comprehensive test reports, all orchestrated by your AI assistant.

By the end of this article, you’ll understand how to transform requirements documents into executable test scenarios and leverage AI to execute Gherkin-style tests via browser automation.

Let’s dive in with a real example: a Tic-Tac-Toe game. I’ve generated both React and Angular versions of this demo app in the companion GitHub repository, so you can follow along with whichever framework you prefer. The repository contains everything you need: the complete PRD, architecture documentation, generated Gherkin scenarios, and test reports.

This article is also available on dev.to with better source code syntax highlighting.

The Traditional E2E Testing Workflow (The Old Way)

Before we explore the AI-assisted approach, let’s acknowledge how E2E testing typically works and why it’s often neglected. The traditional workflow starts with writing specifications or a PRD to document what the application should do. Then you manually create test scenarios by thinking through user flows and edge cases. Next comes the real work: writing Puppeteer, Playwright, or Cucumber Gherkin scripts to translate those scenarios into code, followed by hours of debugging flaky selectors and timing issues. Finally, you maintain that test code as the UI inevitably changes, updating selectors, refactoring tests, and fixing breakages.

Introducing the AI-Assisted Testing Workflow

Here’s what changes when you let AI orchestrate your E2E testing using the Chrome DevTools MCP server:

The Five-Step Process

1. Document requirements: PRD, you’re doing this anyway

2. Generate Gherkin scenarios: AI translates requirements into test scenarios

3. AI executes tests: via Chrome DevTools MCP, no test code to write or maintain

4. AI generates detailed test reports

5. Iterate and maintain: Update requirements and regenerate tests as needed

Why This Works

The key insight is that we’re working in natural language throughout the entire process. Your requirements get written in natural language (PRD), then translated into natural language test scenarios (Gherkin). The AI orchestrates test execution by understanding these natural language instructions, and finally generates test reports in natural language that anyone can read. There’s no translation layer into brittle test code, no fighting with selectors, just clear descriptions of what should happen, executed and verified automatically.

Let’s see this in action with our Tic-Tac-Toe example.

Step 1: Foundation: The Product Requirements

Every good testing strategy starts with clear requirements. For our Tic-Tac-Toe game, we have a comprehensive Product Requirements Document (PRD) that lays everything out. You can find the complete PRD in the GitHub repository.

The Product Requirements Document (PRD)

Our PRD covers everything we need to know about how the game should behave:

User Stories organized by category:

• Core Gameplay: Placing marks, seeing turns, winning, draws

• Game Management: New game, undo, move counter

• User Experience: Hover effects, mobile support, accessibility

Functional Requirements (FR-1 through FR-19) that specify exact behaviors:

• FR-1: The game must support two players: X and O

• FR-2: Player X always goes first

• FR-3: Players alternate turns

• FR-4: A player wins by placing three marks in a row

• FR-5: The game ends in a draw if all cells are filled

• FR-6: Cells cannot be overwritten once marked

• ...and so on

Non-Functional Requirements covering performance, usability, and accessibility:

• NFR-8: All interactive elements must have proper ARIA labels

• NFR-9: Game must be fully keyboard navigable

• NFR-10: Screen readers must be able to announce game state

Why This Documentation Matters

This PRD serves as the single source of truth for both development and testing. When requirements are this clear and structured, AI can extract testable behaviors, generate appropriate test scenarios, understand the expected outcomes, and verify that the implementation matches the specification.

The investment in writing good requirements pays dividends throughout the entire development lifecycle, but especially in testing. Think of it as building a solid foundation, everything else gets easier when you start with clarity.

Step 2: From Requirements to Gherkin Scenarios

Gherkin is a business-readable, domain-specific language for describing software behaviors without detailing how those behaviors are implemented. It uses a simple structure:

Feature: Description of the feature
  Scenario: Description of a specific behavior
    Given [initial context]
    When [action taken]
    Then [expected outcome]

If you’re new to Gherkin, the Gherkin reference has everything you need to know about the syntax and best practices. But don’t worry, you’ll pick up the basics just by following along with our examples.

The Translation Process

Here’s the simple prompt I used to transform our PRD into executable test scenarios:

Create Gherkin feature files based on the PRD (Product Requirements Document) located at:
`tic-tac-toe-react/src/features/tic-tac-toe/PRD.md`

Save the generated feature files to the following directory:
`e2e`

Additionally, create a README.md file in the same `e2e` folder that explains:
- How each feature file maps to specific PRD requirements
- The relationship between test scenarios and product specifications

That’s all it took. The AI read through the PRD, identified testable behaviors, and organized them into four focused feature files covering everything from basic gameplay to accessibility.

Let me show you how it translates requirements into Gherkin. The following examples are from the core-gameplay.feature file in our repository. Take this functional requirement:

From this requirement:

FR-2: Player X always goes first

To this Gherkin scenario:

Scenario: First move is always Player X
  When the game starts
  Then the status should display “Player X’s turn”
  And all cells should be empty
  And the move counter should show “0”

Or this user story:

From this user story:

As a player, I want to click on an empty cell to place my mark, so I can make my move

To this Gherkin scenario:

Scenario: Player places mark in empty cell
  When Player X clicks on cell 0
  Then cell 0 should display “X”
  And it should be Player O’s turn
  And the move counter should show “1”

Pretty straightforward, right? The AI maintains the intent of each requirement while converting it into a testable format that anyone on your team can read and understand.

For our Tic-Tac-Toe game, the AI organized everything into four feature files covering core gameplay, game outcomes, controls, and accessibility. Rather than walk through all of them in detail, let me show you what the core gameplay scenarios look like, this will give you a good feel for how comprehensive these tests become.

The Traceability Matrix

One of the most valuable outputs is the traceability matrix that links each requirement to its corresponding test scenarios. You can see the complete traceability matrix in the repository:

This matrix ensures complete test coverage and makes it easy to verify that every requirement has been tested.

Step 3: AI Executes Tests Using Chrome DevTools MCP

Now comes the magic: executing these Gherkin scenarios automatically using the Chrome DevTools MCP server. Let’s walk through the actual conversation that orchestrated the entire test suite execution.

The Initial Request

Before running tests, you need your application running locally. In our case, we have both React and Angular implementations available in the GitHub repository. To start the React version, run npm start from the tic-tac-toe-react directory, it’ll launch on port 4305. For Angular, navigate to tic-tac-toe-ng and use ng serve. Once your app is running, you can begin testing.

Here’s the prompt I used to kick off the test execution:

I have a React app located in the `tic-tac-toe-react` directory that’s running on http://127.0.0.1:4305/.

Please use the Chrome DevTools MCP server to:
1. Execute the test steps defined in `e2e/core-gameplay.feature`
2. Generate a test report and save it to `e2e/core-gameplay.report.md`

For each Gherkin step in the report, include a text result indicating whether it passed or failed (and any relevant details).

That’s it. No test code to write.

Advanced Approach: Using Subagents for Large Test Suites

For complex applications with many test scenarios, there’s a more scalable approach using subagents. Instead of executing all test steps in a single AI conversation context, you can delegate each scenario to its own subagent. The main orchestrator agent maintains only the Gherkin file, coordinates subagent executions, and generates the final consolidated report, while each subagent independently runs its assigned scenario’s steps.

This architecture provides significant benefits for large test suites. The main agent’s context stays clean and focused on orchestration rather than getting cluttered with hundreds of detailed test execution steps. Each scenario executes in isolation with its own fresh context, preventing context pollution and token limit issues. Most importantly, this approach allows you to run comprehensive test suites with many scenarios and steps without hitting context length limitations.

Here’s how you structure the prompt for subagent-based testing. The following example is for the Angular app and GitHub Copilot:

I have an Angular app located in the `tic-tac-toe-ng` directory 
that’s running on http://127.0.0.1:4200/.

Please use the Chrome DevTools MCP server to execute the test 
scenarios defined in `e2e/core-gameplay.feature`.

For each scenario in the feature file:
1. Use `runSubagent` to execute the test steps for that specific scenario
2. Each subagent should test the scenario independently and return 
   a detailed text result indicating whether it passed or failed, including:
   - Pass/fail status for each Gherkin step in the scenario
   - Any relevant details, observations, or error messages
   - Verification data (e.g., DOM state, element content, computed styles)

After all subagents complete:
3. Aggregate all the scenario results and generate a comprehensive test report
4. Save the final report to `e2e/core-gameplay.report-ng-subagents.md`

The report should include the pass/fail status and details for 
each scenario returned by the subagents.

This subagent approach becomes essential as your test suite grows beyond a dozen scenarios or when individual scenarios involve complex multi-step interactions.

How AI Interprets Gherkin Steps

The AI reads the Gherkin scenarios and translates them into Chrome DevTools MCP tool calls. Let’s look at a concrete example from the actual test execution:

Example: Preventing Cell Overwrites

Gherkin:

Given Player X clicks on cell 4
When Player O attempts to click on cell 4
Then cell 4 should still display “X”
And it should still be Player O’s turn

AI’s internal process:

1. navigate_page to http://127.0.0.1:4305/
2. take_snapshot → Find cell 4 (uid: “48_8”)
3. click uid “48_8”
4. take_snapshot → Verify cell 4 now shows “Cell with X” (disabled)
5. click uid “49_8” → Attempt to click again
   Result: Click timed out (element disabled, click prevented)
6. take_snapshot → Verify state unchanged:
   - Cell 4: Still “Cell with X”
   - Status: Still “Current player: O”
   - Move counter: Still “Moves: 1”

The insight: The click timeout actually confirms the test passed! The cell is disabled, so the click cannot complete, which is exactly the expected behavior.

The Power of Accessibility-Driven Testing

Notice how every test relies on the accessibility tree rather than implementation details. This approach provides remarkable stability since accessibility properties remain unchanged even when you refactor CSS or restructure DOM elements. Tests verify what users actually experience rather than just confirming that certain classes are applied. When your accessibility tree is well-structured, you’re simultaneously ensuring your app is accessible to screen reader users. The snapshots themselves are immediately understandable, showing “Button”, “Empty cell”, “Cell with X” instead of cryptic selectors or implementation details that make sense to humans.

Step 4: The Test Report: Automated Documentation

After executing all tests, the AI generates a comprehensive test report in Markdown format. Let’s examine the structure and value of this automatically generated documentation. You can view the complete test report in the repository.

The report opens with a summary table, this immediately tells you the health of your application at a glance.

For each Gherkin step, the report includes:

1. Pass/Fail status (✅ or ❌)

2. Detailed result description explaining what was observed

3. Element UIDs referenced during the test

4. Evidence from Chrome DevTools interactions

Limitations and Considerations

While this AI-assisted testing approach offers significant advantages, let’s be realistic about where it fits in your testing strategy.

Standardization for Production Use

For real-world usage in production environments, you’ll want to establish consistency across your test artifacts. This means defining report templates that standardize how test results are formatted and presented, making it easier to compare results across different test runs and share reports with stakeholders. You’ll also want to establish a coding standard for Gherkin files that defines naming conventions, step patterns, and structural guidelines, ensuring that AI-generated scenarios follow your team’s conventions and integrate smoothly with your existing test documentation.

These standards become especially important when multiple team members are generating tests or when you’re maintaining a large test suite over time. Consider creating example templates and style guides that you can reference in your prompts to the AI.

Requirements Are Your Foundation

The quality of your tests directly reflects the quality of your requirements. Vague or incomplete PRDs lead to vague or incomplete tests, there’s no magic here. This approach shines when your requirements are specific, testable, and well-structured. The good news? The discipline of writing better requirements benefits your entire project, not just testing.

Complex Interactions May Need Detailed Steps

Simple interactions like clicking buttons and filling forms work automatically. But complex scenarios, think multi-step wizards, drag-and-drop operations, or dynamic content loading, often need more granular Gherkin steps. Instead of “When the user completes the checkout flow,” you’ll want to break it down: “When the user adds items to cart, And navigates to checkout, And fills in shipping address...” The AI can handle complexity, but it needs clear, step-by-step instructions.

Human Review Still Matters

AI can generate tests from your documented requirements, but it won’t catch missing requirements, undocumented edge cases, or critical integration points you forgot to mention. A human reviewer should verify test coverage, ensure both happy paths and error cases are tested, and confirm that scenarios match real-world usage patterns.

Complement, Don’t Replace

E2E tests through Chrome DevTools MCP excel at verifying user-facing behaviors in the actual browser. They complement but don’t replace unit tests for isolated functions, integration tests for component interactions, or API tests for backend functionality. Think of this as the top layer of your testing pyramid or thropy, you still need the foundation underneath.

About the Author

My name is Gergely Szerovay, and I’ve worked as a data scientist and full-stack developer for many years. Currently, I work as a frontend tech lead focusing on Angular-based development. As part of my role, I’m constantly following how Angular and the frontend development scene in general is evolving.

To share my knowledge, I started the Angular Addicts monthly newsletter and publication in 2022, sending subscribers the best resources each month. Whether you’re a seasoned Angular developer or just getting started, I’ve got you covered.

In the past year, with the rise of generative AI, our software development workflows have evolved rapidly. To closely follow this evolution, I decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Join me on this learning journey:

• 🔥 Subscribe to Angular Addicts

• 🚀 Subscribe to AIBoosted.dev

Connect with me:

• Medium

• Dev.to

• Twitter

• LinkedIn

Learn more about Angular, TypeScript, React, and how to build AI-assisted development workflows that make you more productive!

Ever wished your AI assistant could actually see and interact with a browser like you do? That’s exactly what the Chrome DevTools MCP server delivers: a direct connection between your AI coding assistant and Chrome’s powerful developer tools, enabling everything from automated testing to debugging and performance analysis.

Instead of asking your AI to generate Puppeteer scripts or guess at how your web app behaves, it can now control a real Chrome browser, inspect network requests, capture screenshots, and even record performance traces. The Model Context Protocol (MCP) creates this bridge, giving your AI assistant the same view into your web application that you’d get from Chrome DevTools.

But here’s where it gets really interesting. Need to debug why a form submission isn’t working? Your AI can take a snapshot of the page, examine the form elements, fill them out, and capture any console errors, all while explaining what’s happening. Want to understand why your page is loading slowly? It can record a performance trace and break down the Core Web Vitals for you with actionable insights.

This article is also available on dev.to with better source code syntax highlighting.

Common Workflows

Before we dive into the individual tools, let me show you how they work together to solve real problems you face every day. These workflows demonstrate the power of combining different tools to automate complex testing and debugging scenarios.

End-to-End Testing

Testing a complete user flow from start to finish:

“Test the checkout process with these steps: add a product to cart, proceed to checkout, fill in shipping details, and verify the order confirmation appears.”

Your AI will:

1. Take a snapshot to find the “Add to Cart” button (take_snapshot)

2. Click it and wait for the cart to update (click)

3. Navigate to checkout (click)

4. Take another snapshot to identify form fields (take_snapshot)

5. Fill in shipping details using realistic test data (fill_form)

6. Submit the form (click)

7. Wait for the confirmation message (wait_for)

8. Take a screenshot of the confirmation for your records (take_screenshot)

If anything fails, it’ll capture console errors and network requests to help debug (list_console_messages, list_network_requests).

Performance Debugging

Understanding why a page loads slowly:

“Analyze the performance of example.com and tell me what’s slowing it down.”

Your AI will:

1. Navigate to the URL (navigate_page)

2. Start a performance trace with page reload (performance_start_trace)

3. Wait for the trace to complete (performance_stop_trace)

4. Analyze Core Web Vitals (LCP, FID, CLS)

5. Examine specific insights like ImageDelivery breakdown (performance_analyze_insight)

6. Identify the largest contributors (render-blocking resources, slow server response, large images)

7. Suggest concrete optimizations with priority order

Responsive Design Testing

Verifying layouts work across different screen sizes:

“Test how the navigation menu behaves on mobile, tablet, and desktop.”

Your AI will:

1. Start at desktop size (1920x1080) (resize_page)

2. Take a snapshot and screenshot of the navigation (take_snapshot, take_screenshot)

3. Resize to tablet (768x1024) (resize_page)

4. Check if the menu collapses to a hamburger icon (take_snapshot)

5. Test that the hamburger menu opens correctly (click)

6. Resize to mobile (375x667) (resize_page)

7. Verify mobile navigation works (take_snapshot, click)

8. Report any layout issues or broken interactions

API Testing Through UI

Debugging network requests triggered by user interactions:

“Submit the search form and show me what API calls are made.”

Your AI will:

1. List network requests to establish a baseline (list_network_requests)

2. Take a snapshot to find the search input and button (take_snapshot)

3. Fill in the search term (fill)

4. Click the search button (click)

5. Wait for results to appear (wait_for)

6. List new network requests since the click (list_network_requests)

7. Show you the request details (URL, headers, payload, response) (get_network_request)

This is incredibly useful for debugging API integration issues without opening DevTools manually.

Available Tools

Now that you’ve seen what’s possible, let’s explore the individual tools. The Chrome DevTools MCP server organizes its 26 tools into six categories, each targeting a specific aspect of browser automation and debugging.

Input Automation (7 tools)

Tools for interacting with page elements:

• click - Click or double-click elements on the page

• drag - Drag one element onto another

• fill - Type text into inputs or select options from dropdowns

• fill_form - Fill out multiple form fields at once

• handle_dialog - Accept or dismiss browser dialogs (alerts, confirms, prompts)

• hover - Hover over elements to trigger hover states

• upload_file - Upload files through file input elements

Navigation Automation (7 tools)

Tools for controlling browser tabs and navigation:

• close_page - Close browser tabs by index

• list_pages - Get a list of all open tabs

• navigate_page - Navigate to a specific URL

• navigate_page_history - Go back or forward in browser history

• new_page - Open a new tab with a URL

• select_page - Switch context to a different tab

• wait_for - Wait for specific text to appear on the page

Emulation (3 tools)

Tools for simulating different device and network conditions:

• emulate_cpu - Throttle CPU to simulate slower devices (1-20x slowdown)

• emulate_network - Simulate network conditions (Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G)

• resize_page - Change viewport dimensions to test responsive designs

Performance (3 tools)

Tools for analyzing page performance:

• performance_start_trace - Begin recording a performance trace

• performance_stop_trace - Stop the active trace recording

• performance_analyze_insight - Get detailed information about specific performance insights (like LCP breakdown or document latency)

Network (2 tools)

Tools for inspecting network activity:

• list_network_requests - Get all network requests since the last navigation, with filtering options

• get_network_request - Retrieve detailed information about a specific request by its ID

Debugging (4 tools)

Tools for inspecting and debugging pages:

• evaluate_script - Execute JavaScript code in the page context and get JSON-serializable results

• list_console_messages - Retrieve all console logs, warnings, and errors

• take_screenshot - Capture screenshots of the full page or specific elements (PNG, JPEG, or WebP)

• take_snapshot - Get a text representation of the page based on the accessibility tree with unique element identifiers

Configuration

Let’s get you up and running! The Chrome DevTools MCP server is pretty flexible, so you can configure it to match your workflow. I’ll cover the essentials here, but if you want to dive deeper into all the configuration options, check out the official configuration documentation.

Basic Setup

The simplest way to get started is to let the server launch a fresh Chrome instance with default settings:

{
  // or “mcpServers”, depending your IDE / tool
  “servers”: {
    “chrome-devtools”: {
      “command”: “npx”,
      “args”: [”-y”, “chrome-devtools-mcp@latest”]
    }
  }
}

That’s it! This configuration will work great for most use cases.

Connecting to a Running Chrome Instance from Docker

Here’s a scenario I’ve run into a lot: you’re developing in a Docker container but want to use a Chrome instance that’s running on your host machine. Maybe you want to see the browser window, or you need to use your existing Chrome profile. Whatever the reason, connecting to a running instance is the way to go.

First, start Chrome on your host machine with remote debugging enabled. Chrome needs a user data directory when remote debugging is on, so make sure to specify one:

“C:\Program Files\Google\Chrome\Application\chrome.exe” ^
  --remote-debugging-port=9222 ^
  --user-data-dir=”C:\Temp\chrome-profile-stable”

Now for the Docker-specific part. Docker provides a special DNS name called host.docker.internal that resolves to your host machine. From inside your container, you can find the IP address:

host host.docker.internal
# Output: host.docker.internal has address 192.168.65.254

Use that IP address in your MCP server configuration:

{
  // or “mcpServers”, depending your IDE / tool
  “servers”: {
    “chrome-devtools”: {
      “command”: “npx”,
      “args”: [
        “-y”,
        “chrome-devtools-mcp@latest”,
        “--browserUrl=http://192.168.65.254:9222”
      ]
    }
  }
}

You might be wondering: “Why can’t I just use host.docker.internal directly in the browserUrl?” If you’re curious about the details, check out this discussion in the Puppeteer GitHub issues.

For more configuration options like headless mode, custom Chrome paths, network throttling, and debugging settings, take a look at the full configuration guide.

Tool Reference

Input Automation Tools

click

Clicks or double-clicks an element identified by its unique ID from a page snapshot.

Input Schema:

{
  uid: string,        // Required: The uid of an element on the page from the page content snapshot
  dblClick?: boolean  // Optional: Set to true for double clicks. Default is false.
}

In Action: Let’s say you want to test a login form. First, take a snapshot to get element IDs, then use click to submit the form. Your AI assistant can chain these actions naturally when you ask “Can you test the login flow?” It’ll find the form, fill it out, click submit, and report what happened.

drag

Drags one element onto another, useful for testing drag-and-drop interfaces.

Input Schema:

{
  from_uid: string,  // Required: The uid of the element to drag
  to_uid: string     // Required: The uid of the element to drop into
}

In Action: Testing a kanban board? Ask your AI to “move the task card from ‘In Progress’ to ‘Done’” and it’ll locate both elements from a snapshot and perform the drag operation. It can even verify the move succeeded by checking the DOM afterward.

fill

Types text into input fields, text areas, or selects an option from a dropdown.

Input Schema:

{
  uid: string,    // Required: The uid of an element on the page from the page content snapshot
  value: string   // Required: The value to fill in
}

In Action: When you ask “Fill out the contact form with test data,” your AI can take a snapshot, identify all the form fields, then use fill on each one. It’s smart enough to generate appropriate test data based on field names and types.

fill_form

Fills multiple form fields in a single operation, more efficient than calling fill repeatedly.

Input Schema:

{
  elements: Array<{
    uid: string; // The uid of the element to fill out
    value: string; // Value for the element
  }>;
}

In Action: This is perfect for complex forms. Instead of watching your AI fill fields one by one, it batches everything together. Ask “Complete the registration form” and it’ll snapshot the page, identify all required fields, then fill them all at once.

handle_dialog

Responds to JavaScript alerts, confirms, or prompts.

Input Schema:

{
  action: ‘accept’ | ‘dismiss’,  // Required: Whether to dismiss or accept the dialog
  promptText?: string            // Optional: Optional prompt text to enter into the dialog.
}

In Action: Testing a “delete item” flow that shows a confirmation dialog? Your AI will click the delete button, detect the dialog, then use handle_dialog to confirm or cancel. You can specify which action you want: “Test the delete flow but cancel the confirmation.”

hover

Triggers hover states on elements, essential for testing dropdown menus and tooltips.

Input Schema:

{
  uid: string; // Required: The uid of an element on the page from the page content snapshot
}

In Action: Want to test if your navigation dropdown works? Ask “Check if the Products menu shows all categories” and your AI will hover over the menu, wait for it to expand, then snapshot and verify the contents.

upload_file

Uploads a file through a file input element.

Input Schema:

{
  uid: string,       // Required: The uid of the file input element or an element that will open file chooser on the page from the page content snapshot
  filePath: string   // Required: The local path of the file to upload
}

In Action: Need to test an image upload feature? Tell your AI “Upload test-image.jpg to the profile picture form” and it’ll locate the file input, handle the upload, and can even wait to verify the upload succeeded.

Navigation Automation Tools

close_page

Closes a browser tab by its index. You can’t close the last remaining tab.

Input Schema:

{
  pageIdx: number; // Required: The index of the page to close. Call list_pages to list pages.
}

In Action: After opening multiple tabs for testing, clean them up: “Close all the test tabs we opened.” Your AI will list the pages, then close the ones that aren’t needed, keeping your main tab active.

list_pages

Returns all open browser tabs with their URLs and indices.

Input Schema: None

In Action: This runs automatically whenever your AI needs to know what tabs are open. When you ask “What pages do I have open?” or “Switch to the documentation tab” it uses this tool behind the scenes.

navigate_page

Navigates the current tab to a URL.

Input Schema:

{
  url: string,        // Required: URL to navigate the page to
  timeout?: number    // Optional: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
}

In Action: The most straightforward tool. “Go to https://example.com“ triggers this directly. Your AI can also chain it with other actions: “Navigate to the login page and check if the form is accessible.”

navigate_page_history

Moves backward or forward through the browser history.

Input Schema:

{
  navigate: ‘back’ | ‘forward’,  // Required: Whether to navigate back or navigate forward in the selected pages history
  timeout?: number                // Optional: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
}

In Action: Testing multi-step flows? “Complete the checkout process, then go back and verify the cart is still correct.” Your AI navigates forward through each step, then uses history navigation to go back and verify state.

new_page

Opens a new tab and navigates to a URL.

Input Schema:

{
  url: string,        // Required: URL to load in a new page.
  timeout?: number    // Optional: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
}

In Action: Comparing pages side-by-side? “Open the production and staging sites in separate tabs and compare the homepage layouts.” Your AI opens both pages and can switch between them to analyze differences.

select_page

Changes which tab is active for subsequent tool operations.

Input Schema:

{
  pageIdx: number; // Required: The index of the page to select. Call list_pages to list pages.
}

In Action: When working with multiple tabs, this switches context. Ask “Check the console errors in the second tab” and your AI uses list_pages to find it, select_page to switch to it, then list_console_messages to check for errors.

wait_for

Waits for specific text to appear on the page, useful after triggering actions that update the UI.

Input Schema:

{
  text: string,       // Required: Text to appear on the page
  timeout?: number    // Optional: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
}

In Action: After submitting a form, you want to verify success: “Submit the form and check for the success message.” Your AI clicks submit, then uses wait_for to ensure “Thank you for your submission” appears before continuing.

Emulation Tools

emulate_cpu

Throttles CPU performance to simulate slower devices.

Input Schema:

{
  throttlingRate: number; // Required: The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling
}

In Action: Want to see how your app performs on older devices? “Test the page performance on a slow device” triggers CPU throttling, helping identify performance bottlenecks that only appear on less powerful hardware.

emulate_network

Simulates various network conditions.

Input Schema:

{
  throttlingOption: “No emulation” |
    “Offline” |
    “Slow 3G” |
    “Fast 3G” |
    “Slow 4G” |
    “Fast 4G”; // Required: The network throttling option to emulate. Available throttling options are: No emulation, Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G. Set to “No emulation” to disable. Set to “Offline” to simulate offline network conditions.
}

In Action: Testing offline functionality? “Check if the app works without internet” sets the network to offline mode, then you can ask your AI to verify that your service worker and caching work correctly. You can also test on slow connections: “How does the page load on 3G?”

resize_page

Changes the viewport dimensions to test responsive designs.

Input Schema:

{
  width: number,   // Required: Page width
  height: number   // Required: Page height
}

In Action: Checking mobile responsiveness? “Test the layout on iPhone 12 dimensions” resizes to 390x844, takes screenshots, and you can explicitly ask it to check that the mobile menu works correctly. Your AI can test multiple sizes in sequence to catch responsive design issues.

Performance Tools

performance_start_trace

Begins recording a performance trace to analyze page load and runtime performance.

Input Schema:

{
  reload: boolean,    // Required: Determines if, once tracing has started, the page should be automatically reloaded.
  autoStop: boolean   // Required: Determines if the trace recording should be automatically stopped.
}

In Action: “Analyze the performance of this page” starts a trace with reload enabled and autoStop true. After recording, your AI gets Core Web Vitals (LCP, FID, CLS) and performance insights automatically.

performance_stop_trace

Stops the active performance trace and returns the analysis.

Input Schema: None

In Action: If you started a trace with autoStop disabled (to capture user interactions), you’d stop it manually: “Stop the performance recording and show me the results.” The trace includes detailed timing information and performance insights.

performance_analyze_insight

Gets detailed information about specific performance issues identified in a trace.

Input Schema:

{
  insightName: string; // Required: The name of the Insight you want more information on. For example: “DocumentLatency” or “LCPBreakdown”
}

Here’s the list of all 18 Chrome DevTools Performance Insights and their names:

Each of these insights focuses on a specific aspect of performance that can help you make your pages faster. When you run a performance trace, Chrome analyzes your page and highlights which of these insights are relevant to your situation:

• Cache: Use efficient cache lifetimes

• CLSCulprits: Layout shift culprits

• DocumentLatency: Document request latency

• DOMSize: Optimize DOM size

• DuplicatedJavaScript: Duplicated JavaScript

• FontDisplay: Font display

• ForcedReflow: Forced reflow

• ImageDelivery: Improve image delivery

• INPBreakdown: INP breakdown

• LCPBreakdown: LCP breakdown

• LCPDiscovery: LCP request discovery

• LegacyJavaScript: Legacy JavaScript

• ModernHTTP: Modern HTTP

• NetworkDependencyTree: Network dependency tree

• RenderBlocking: Render-blocking requests

• SlowCSSSelector: CSS selector costs

• ThirdParties: Third parties

• Viewport: Optimize viewport for mobile

Want to understand how Chrome generates these insights and what each one means for your page? The Performance Insights documentation has all the details.

In Action: After running a trace that shows “LCP could be improved,” ask “What’s causing the slow LCP?” Your AI uses this tool to get a breakdown of what contributed to the Largest Contentful Paint time and suggests specific optimizations.

Network Tools

list_network_requests

Retrieves all network requests since the page loaded.

Input Schema:

{
  pageSize?: number,          // Optional: Maximum number of requests to return. When omitted, returns all requests.
  pageIdx?: number,           // Optional: Page number to return (0-based). When omitted, returns the first page.
  resourceTypes?: string[]    // Optional: Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.
}

In Action: Debugging API calls? “Show me all the failed network requests” lists requests, filters to status codes 4xx and 5xx, and shows you what went wrong. You can also check “Are there any requests taking longer than 2 seconds?”

get_network_request

Gets a network request by URL. You can get all requests by calling list_network_requests.

Input Schema:

{
  reqid: number; // Required: The reqid of a request on the page from the listed network requests
}

In Action: After listing requests, dive into details: “What headers were sent with that POST request?” Your AI uses the request ID to fetch complete information including headers, response body, timing breakdown, and status.

Debugging Tools

evaluate_script

Executes JavaScript code in the page context and returns JSON-serializable results.

Input Schema:

{
  function: string,  // Required: A JavaScript function to run in the currently selected page
  args?: Array<{     // Optional: An optional list of arguments to pass to the function.
    uid: string      // The uid of an element on the page from the page content snapshot
  }>
}

In Action: Need to inspect page state? “What’s the current value of the search input?” triggers evaluation of document.querySelector(’input[name=”search”]’).value. You can also modify state, check global variables, or debug complex interactions.

list_console_messages

Retrieves console logs, warnings, and errors from the page.

Input Schema:

{
  pageSize?: number,   // Optional: Maximum number of messages to return. When omitted, returns all requests.
  pageIdx?: number,    // Optional: Page number to return (0-based). When omitted, returns the first page.
  types?: string[]     // Optional: Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.
}

In Action: After page interactions, check what happened: “Did any errors occur?” Your AI lists console messages, filters to errors, and explains what each one means. Great for catching JavaScript errors during testing.

take_screenshot

Captures visual snapshots of the page or specific elements.

Input Schema:

{
  format?: ‘png’ | ‘jpeg’ | ‘webp’,  // Optional: Type of format to save the screenshot as. Default is “png”
  quality?: number,      // Optional: Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.
  uid?: string,          // Optional: The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.
  fullPage?: boolean,    // Optional: If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.
  filePath?: string      // Optional: The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.
}

In Action: Visual regression testing made easy: “Take a screenshot of the homepage and compare it to yesterday’s version.” Your AI captures the image, compares layouts, and highlights any differences. You can also screenshot specific components: “Show me what the modal looks like when open.”

take_snapshot

Generates a text representation of the page based on the accessibility tree, with unique IDs for each element. Think of this as getting a bird’s eye view of your page’s structure: it shows you all the interactive elements, their roles, and how they’re organized, similar to how a screen reader would understand the page.

The accessibility tree is a simplified version of the DOM that exposes only the information needed for assistive technologies. By using this tree, the snapshot focuses on semantically meaningful elements while filtering out purely visual markup. This makes it perfect for understanding page structure and finding elements to interact with.

For a deeper dive into how Chrome’s accessibility tree works and what information it provides, check out the Full Accessibility Tree in Chrome DevTools blog post.

Input Schema:

{
  verbose?: boolean  // Optional: Whether to include all possible information available in the full a11y tree. Default is false.
}

In Action: This is your AI’s eyes into the page structure. When you ask “What form fields are on this page?” it takes a snapshot to see all interactive elements. The unique IDs from this snapshot are what other tools use to interact with specific elements.

👨‍💻About the author

My name is Gergely Szerovay, I worked as a data scientist and full-stack developer for many years, and I have been working as frontend tech lead, focusing on Angular based frontend development. As part of my role, I’m constantly following how Angular and the frontend development scene in general is evolving. To share my knowledge, I started the Angular Addicts monthly newsletter and publication in 2022, so that I can send you the best resources I come across each month. Whether you are a seasoned Angular Addict or a beginner, I got you covered. Let me know if you would like to be included as a writer. Let’s learn Angular together! Subscribe here 🔥

Angular has evolved very rapidly over the past few years, and in the past year, with the rise of generative AI, our software development workflows have also evolved rapidly. In order to closely follow the evolution of AI-assisted software development, I decided to start building AI tools in public, and publish my progress on AIBoosted.dev. Join my on this learning journey: Subscribe here 🚀

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, Twitter or LinkedIn to learn more about Angular, and how to build AI apps with AI, Typescript, React and Angular!

The main problem with vibe coding

The term "vibe coding" was coined by Andrej Karpathy to describe the process of letting AI assistants generate code while you "fully give in to the vibes" - essentially delegating the details to the AI and forgetting that code even exists.

While this approach delivers initial velocity, especially for quick prototypes, it becomes problematic as the projects grow. After my initial excitement with vibe coding wore off, I noticed something troubling: my codebase was becoming increasingly difficult to maintain and understand.

If this sounds familiar, you're not alone. Vibe coding delivers remarkable speed, especially when building on a solid boilerplate. But without proper guardrails, that speed comes at a hidden cost to your codebase's long-term health.

3 Common Challenges with AI-Assisted Development

After spending many hours experimenting with vibe coding myself, I've seen three common problems emerge:

1. Organizational chaos: Files end up in unpredictable locations, making the project structure increasingly difficult to navigate.

2. Growing files: What starts as a reasonably-sized component gradually balloons into a 500+ line monstrosity as the AI keeps adding "just one more function" to existing files.

3. Inconsistency: Your codebase becomes a patchwork quilt of different styles, patterns, and approaches as the AI draws from various influences or implements similar features differently across your application.

I've learned the hard way: the key to successful vibe coding isn't just about getting the AI to write code faster - it's about getting it to write structured code following simple, clean guidelines.

While this article uses TypeScript and React as primary examples, it's important to note that these principles apply broadly across different programming languages and frameworks. Whether you're building with Angular and Material, or MCP servers using Node.js, the same four pillars of maintainable vibe coding will help you maintain quality and consistency. The specific tools and configurations will differ, but the underlying approach remains effective across technology stacks.

The 4 Pillars of Maintainable AI-Assisted Development

After some trial and error, I've found that maintainable AI-assisted development rests on four pillars:

1. Choosing the right tech stack: Selecting technologies that are well-documented and well-understood by AI tools

2. Coding guidelines: Clear, explicit rules that both humans and AI can understand and follow

3. Enforcement tools: Linters, formatters, and validation systems that catch deviations from your guidelines

4. Solid boilerplate: A minimal but complete starting point with all the necessary development tools pre-configured

Let's dive into each of these areas and see how they work together to keep your vibe coding maintainable over time.

1. Choosing the Right Tech Stack

The foundation of maintainable vibe coding starts with choosing the right tech stack. Some technologies work notably better with AI assistance than others, usually because they're widely used, well-documented, and the AI has seen many examples of them in its training data.

For frontend development, I often use TypeScript, React, and Shadcn UI, paired with a Supabase backend. This combination leverages technologies that AI assistants understand well.

The TypeScript/React/Shadcn/Supabase stack works exceptionally well because:

1. TypeScript provides strong type safety that catches many issues that might otherwise slip through in AI-generated code, while ensuring data structures are cleanly defined

2. React is widely used and most LLMs generate React components at higher quality by default compared to other frameworks

3. Shadcn UI provides consistent, accessible components that follow predictable patterns

4. Supabase handles authentication, database, and storage with minimal boilerplate

I've shared a boilerplate for projects with this tech stack on my GitHub that includes all the necessary configurations and enforcements to get started with maintainable vibe coding right away.

When selecting your tech stack for AI-assisted development, consider these factors:

• Type safety: Strongly typed languages help catch errors in AI-generated code and ensure data structures are cleanly defined

• Documentation quality: Better documented tech leads to better AI-generated implementation

• Community size: More widely used technologies typically have better AI support

• Technologies with clear patterns are easier for AI to follow

2. Coding Guidelines: Teaching AI How You Work

Think of coding guidelines as creating a shared language between you and your AI assistant. With clear guidelines, you can simply tell the AI to "follow our project's architectural patterns" instead of explaining your code organization philosophy from scratch every time.

One important practice I've discovered is to continuously remind the AI about your coding guidelines throughout the development session. AI assistants can sometimes drift away from your guidelines as the conversation progresses, especially during complex implementations. Simple reminders like "Remember to follow our AIBD guidelines" can dramatically improve consistency and prevent architectural drift.

Creating a unique abbreviation for your coding guidelines (like AIBD in my case) adds significant value to your workflow. When you use this abbreviation consistently throughout your guidelines and development process, it creates a clear reference point that you can use in your prompts. Simply mentioning "follow our AIBD guidelines" instantly communicates to the AI which specific rule set you're referring to.

I've shared my AIBD (AI Boosted Development) guidelines for TypeScript-based development on my GitHub. These guidelines have evolved through months of experimentation and have proven effective across multiple vibe coding projects, and I continuously improve and extend them. You're welcome to use them as a starting point and adapt them to your needs.

Once you've established your guidelines, you need a way to efficiently share them with your AI tools. Different AI-powered development environments offer various approaches:

• Cursor has "Cursor Rules" that provide system-level guidance.

• Cline and Roo Code offers "Custom instructions" that can be applied to your development sessions.

• For chat-based interfaces with filesystem access like Claude, you can ask the AI to read and follow your guidelines stored in project files.

Regardless of which AI tool you're using, after you've shared your guidelines once, you can simply tell any AI assistant to "follow our AIBD guidelines" without explaining them from scratch each time.

Our guidelines should cover several key areas:

Architecture

A well-defined architecture provides the structural foundation for your codebase. It should clearly specify:

• How code is organized (folders, files, modules)

• Boundaries between different parts of the application

• Dependency rules (what can import what)

• Shared code organization

My AIBD (AI Boosted Development) guidelines use features as the building blocks of your app. A feature is simply a chunk of related functionality packaged together. Each feature gets its own folder, follows a standard structure, and keeps its internal code separate from what other features can access.

Instead of organizing by technical layers (models, components, services), we organize by features that map to business capabilities. This approach makes it much easier to describe what you want to the AI and ensures generated code fits naturally into your architecture. Example of a feature directory:

src/
├── features/            # Feature-based organization
│   ├── user-management/ # Each feature is self-contained
│   │   ├── prd.md       # Feature requirements
│   │   ├── UserProfile.ts  # Public exports
│   │   ├── UserSettings.ts
│   │   └── internal/    # Private implementation details
│   │       ├── Theme.ts
│   │       └── validateEmail.ts
│   └── payment-processing/
└── shared/              # Shared utilities and types
    ├── types/
    ├── utils/
    └── http/
        └── internal/    # Private implementation details

Another crucial aspect of my AIBD architecture is using many small files, each containing a single declaration or definition. This approach offers several benefits:

• The import graph directly represents connections between types, functions, and classes, making dependencies visually clear

• Reduces token usage with AI tools - the LLM processes multiple small files focused specifically on what it needs, rather than loading huge files with thousands of lines. Tools like Cursor have line number limits (e.g., reading only 200 lines from a file at once). By staying below these limits, the AI agent can be more efficient

• Improves focus - both you and the AI can concentrate on one specific piece of functionality at a time, rather than getting lost in a large file

AIBD intentionally avoids using barrel files (index.ts exports), as they make it easier to inadvertently introduce circular imports and make it harder for LLMs to track and understand import relationships. Direct imports from specific files create a clearer dependency graph that both humans and AI assistants can follow more easily.

Coding Style Guidelines

Beyond architecture, you need guidelines for the code itself. Your coding style guidelines should cover how to define and document types, structure function parameters, handle errors consistently, and follow appropriate naming conventions for different kinds of variables. These seemingly small decisions, when applied consistently, create a codebase that feels cohesive rather than cobbled together from different sources.

For example, instead of using both interfaces and type aliases randomly throughout your codebase, set a clear guideline like:

// Don't use interfaces
interface User {
  id: number;
  name: string;
}

// Do use type aliases
type User = {
  id: number;
  name: string;
};

When the AI knows your preference, it can consistently apply it without you having to correct it repeatedly.

Tech Stack-Specific Guidelines

Different frameworks and libraries have their own best practices. Create specific guidelines for each major technology in your stack.

For example, my React and Shadcn UI guidelines specify how to properly structure React components, separate smart and UI components, and correctly import Shadcn UI components from the appropriate paths. These guidelines ensure that our components follow consistent patterns, maintain proper separation of concerns, and correctly utilize the UI library's built-in accessibility features.

Feature Blueprints

Blueprints provide templates for common types of features. They're incredibly valuable for AI assistance because they give the AI a starting point that already follows your patterns.

A feature blueprint might include:

• Required files and their purpose

• Component structure

• Testing requirements

• Documentation format

Documentation Guidelines

Documentation is often overlooked, but it's crucial for long-term maintenance. Guidelines should specify:

• What needs documentation (functions, types, components)

• Documentation format (TSDoc, Markdown)

• Required sections and information

I use a three-level documentation approach that keeps different concerns properly separated:

1. Project-level documentation - Our guidelines contain high-level project rules, patterns, and architecture decisions. Additional project-level documentation lives in Markdown files at the repository root or in dedicated documentation directories.

2. Feature-level documentation - Each feature includes a prd.md file in its root directory that specifies business requirements, user stories, acceptance criteria, and scope boundaries. This serves as the single source of truth for what the feature should do. We call these "PRD" files (Product Requirements Document), though we're using this term for feature-level specifications rather than for entire product documentation.

A well-structured PRD file should include:

• Title and Feature Name: Clear identification of the feature

• Objective: A concise statement describing the purpose and business value

• User Stories: Written as "As a [role], I want [goal] so that [reason]"

• Requirements: Functional and non-functional requirements

• Acceptance Criteria: Specific, testable criteria that define when the feature is complete

• Out of Scope: Explicitly listing what's not included to prevent scope creep

3. Code-level documentation - We use TSDoc comments for all public functions, types, and components. This documentation focuses on implementation details, usage patterns, and technical considerations.

This multi-level approach ensures that developers (and AI assistants!) can find the right information at the right level of abstraction.

Code Formatting Guidelines

One especially important aspect of coding guidelines involves consistent code formatting. Tools like Prettier and EditorConfig help automatically format both human-written and AI-generated code to maintain consistency across your codebase. By defining these standards in configuration files, you eliminate formatting debates and ensure all code follows the same conventions regardless of its source.

3. Enforcement Tools

Guidelines are only effective if they're followed. This is where enforcement tools come in - they provide an objective way to ensure your codebase remains consistent even as it grows through AI assistance.

Linting Rules

ESLint is your best friend for enforcing coding standards. Configure it to catch violations of your guidelines, like the file organization rules.

The magic of linters in AI-assisted development is that you can simply ask the AI to "fix the linting errors" after generating code, and it will refactor its own work to match your standards.

Enforcing Module Boundaries

One of the most powerful tools in our linting arsenal is Sheriff, which enforces module boundaries and dependency rules. This is absolutely crucial for maintaining a clean architecture in AI-assisted development, as it prevents the AI from creating inappropriate dependencies that would violate your architectural principles.

In my boilerplate, I've set up these specific Sheriff rules:

• Features in the features/ directory can import from each other and from the shared/ directory

• Shared modules in the shared/ directory are forbidden from importing anything from the features/ directory

• Imports from features are only allowed from their root directory, not from their internal/ directory

This simple set of rules helps prevent circular dependencies and maintains proper encapsulation of internal implementation details. When the AI generates code that violates these boundaries, Sheriff will immediately flag the issue, allowing you to ask the AI to fix the architectural violation.

For larger projects, you can customize and refine these basic rules to match your specific architectural needs. You might define more granular boundaries between feature groups, create specialized rules for certain critical modules, or establish stricter constraints on how shared utilities can be used. The key is to start with these fundamental rules and then evolve them as your project's architecture matures.

These boundary rules are particularly effective because they're simple enough to explain to an AI assistant, yet powerful enough to maintain the structural integrity of your codebase as it grows.

Pre-commit Hooks

Git's pre-commit hooks provide a built-in mechanism to run checks before code is committed, creating a safety net that prevents guideline violations from making it into your repository.

A typical pre-commit configuration might:

• Run the linter

• Run the code formatter

• Run the unit tests

• Run madge to detect circular references before they cause issues

Automated Testing

One practice I've found particularly effective is directly mapping your test cases to the acceptance criteria in your PRD files. This creates a clear traceability between what was required and what was delivered. You can ask the AI to generate test cases based on the acceptance criteria, giving you a head start on comprehensive test coverage.

For example, if your acceptance criteria includes "On submit, disable all controls and show a loading spinner in the button" you'd have a corresponding test that verifies exactly that behavior. This approach ensures that your tests are focused on business requirements rather than implementation details.

4. Solid Boilerplate: Start Off on the Right Foot

The final piece of the puzzle is a well-crafted boilerplate - a minimal but complete starting point with all the necessary development tools pre-configured.

Your boilerplate should include:

• Project structure following your architectural guidelines

• Development tools (linters, formatters, etc.) with pre-configured rules

• Testing framework setup

• UI component library integration

• Authentication skeleton (if applicable)

• API client structure

• Build and deployment configurations

Example: AIBD React Template

To demonstrate how these concepts work in practice, I've created an AIBD React Template available on GitHub. This boilerplate implements all the principles we've discussed and provides a solid foundation for AI-assisted development.

Technical Stack

The template uses a modern, well-supported stack that AI tools understand well:

• React 19: The latest version with improved performance features

• TypeScript: For type safety and better AI assistance

• Vite: Fast, modern build tooling

• TailwindCSS: Utility-first CSS that AI excels at generating

• Shadcn UI: Pre-built components based on Radix UI

• React Router v7: Declarative routing

• React Hook Form: Flexible and extensible forms with validation

• Zod: TypeScript-first schema validation

• Supabase Client: Authentication and backend services

Project Structure

The boilerplate implements a feature-based architecture that maps directly to the AIBD guidelines.

The boilerplate comes pre-configured with a comprehensive set of enforcement tools:

• ESLint: Configured with strict TypeScript and React rules

• Sheriff: Enforces module boundaries between features and shared code, preventing inappropriate dependencies.

• Husky and lint-staged: Run validation before each commit:

  • Linting of staged TypeScript files

  • Automatic code formatting with Prettier

  • Checking for circular dependencies

  • Running unit tests to ensure nothing is broken

This enforcement setup creates guardrails that keep AI-generated code on track, even when you're moving quickly.

Putting It All Together: A 7-step Vibe Coding Workflow

Now that we've covered the four pillars, let's look at a practical workflow that brings them all together.

After each step in this workflow, always review and validate the AI's modifications. Remember that AI assistance should augment your judgment, not replace it. If you spot issues:

• Ask the AI to fix specific problems: "This component is missing error handling. Please add proper error states."

• Fix things manually when the AI struggles with complex corrections

• Use the AI to explain confusing generated code before making changes

At the end of the workflow, you'll have a clean import graph (generated by Madge) - a visual representation of your feature dependencies and module boundaries. While you can analyze these graphs in detail, a simple "squint test" is surprisingly helpful: a healthy codebase will have a tree-like structure rather than a chaotic, tangled web of dependencies, and should never contain red lines or nodes (which indicate circular dependencies that can cause runtime issues):

Here are the steps of the workflow:

1. Start with the AIBD React Template or similar boilerplate that already includes the right tech stack and all necessary enforcement tools.

1. Share your coding guidelines at the beginning of each session. With tools like Cursor, you can add these as persistent rules the AI will follow automatically.

2. Request features in architectural terms rather than implementation details. Start by asking the AI to create the directory structure and PRD documentation before implementation.
   

🧑: I'd like to design three features for our application using Supabase 
for authentication:

1. A sign-in feature
2. A dashboard with sidebar that displays the user's email and has a 
   sign-out button
3. A sign-out feature

Please follow our AIBD guidelines.

Could you please first create the directory structure for these features 
following our feature-based architecture, and draft the prd.md files for 
each one?

This approach ensures your AI assistant establishes the right foundation before diving into implementation details. The PRD files will serve as the blueprint for implementation while maintaining architectural consistency.

4. Let the AI generate the initial implementation based on your guidelines and existing patterns in the codebase:

🧑: Now please implement all the features based on their PRDs, 
following our AIBD guidelines.

5. Ask the AI to implement tests for the Acceptance Criteria listed in the PRDs:

🧑: Now let's make sure we have test coverage for our business 
requirements. Please implement unit tests for all the acceptance 
criteria in our sign-in feature's PRD.

6. Commit and trigger pre-commit hooks with AI to validate your code and fix any issues that arise:

🧑: Generate a conventional commit message from uncommitted changes. 
It should reference the directory structure: 
include (feature/user-management) or (shared/utils) based on which 
features or shared modules were modified. Commit the changes.

This approach ties your commit messages directly to your codebase's architecture, making it easier to track which features or shared modules are changing over time.

If your pre-commit hook catches any issues, use a separate prompt to get help fixing them:

🧑: The pre-commit hook failed with these errors.
Please help me fix them while maintaining our AIBD guidelines.

Having the AI fix linting or testing errors helps it learn from mistakes and reinforces your code standards.

7. Repeat for each feature or component, letting the AI build on its previous work.

Conclusion: Maintainable Vibe Coding

Vibe coding with AI assistance isn't just about writing code faster - it's about maintaining quality and consistency while accelerating development. By choosing the right tech stack, establishing clear guidelines, implementing enforcement tools, and starting with a solid boilerplate, you can benefit from the power of AI without sacrificing the long-term health of your codebase.

Remember:

• Choosing the right tech stack provides a solid foundation for AI-assisted development

• Guidelines communicate your standards to the AI

• Enforcement tools verify adherence to those standards

• Boilerplate encodes your best practices from the start

• Properly sharing guidelines with AI tools keeps everything consistent

With this framework in place, AI becomes more than just a speed boost - it helps you consistently produce maintainable, structured code that remains comprehensible as your project evolves.

Have you established guidelines for your AI-assisted development? What challenges have you faced with vibe coding? I'd love to hear about your experiences and what's worked for you.

About the Author

My name is Gergely Szerovay. I've worked as a data scientist and full-stack developer for many years, and I've been a frontend tech lead focusing on Angular development for the past three years. To closely follow the evolution of AI-assisted software development, I've decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular and how to build AI apps with AI, TypeScript, React, and Angular!

In this article, I will talk about something that's been a game-changer for my development workflow - combining VS Code Dev Containers with Claude AI. This setup lets your AI assistant to access and interact with your project files directly.

By using the Model Context Protocol (MCP), we create a connection that keeps Claude's access limited to just the files in your container, maintaining that important isolation and security we all want.

One thing I love about this approach is the full control it gives you over code generation. While there are many excellent dev tools available, many of them operate as black boxes with considerable functionality happening under the hood. With our MCP and Dev Container combination, your main IDE remains VS Code, but you gain the flexibility to use any chat client that supports MCP. Since these tools aren't VS Code plugins, they're typically easier to understand, tweak to your liking.

Here's another compelling advantage: there are no API costs associated with this setup! All you need is a monthly Claude Desktop subscription. This setup also works with Claude's free plan, though you'll encounter lower usage limits there.

To show you how this works in practice, we'll build a simple Tic-Tac-Toe game in both React and Angular. You'll see how Claude can help implement the game, identify bugs, and streamline your development process regardless of which framework you prefer.

Understanding Dev Containers

What Are Dev Containers?

Dev Containers allow you to encapsulate your entire development environment - including tools, libraries, and configurations - in a containerized setup that runs directly within Visual Studio Code.

Key Benefits

The advantages of using Dev Containers extend beyond just environment consistency:

• Isolation from your local system: Your projects and their dependencies exist in contained environments, preventing conflicts between different projects or with your host system.

• Portable configurations: Your development setup travels with your project, no matter who's working on it or where.

• Reproducibility: Every developer experiences the same environment, reducing debugging complexity.

If you want to dive deeper, the VS Code Dev Containers documentation provides excellent reference material.

Windows Setup with WSL2

I'm using Windows for my examples, but don't worry - Dev Containers work just as well on macOS and Linux.

For Windows users, I'd recommend using Docker with WSL2 the backend for optimal performance. This setup is particularly beneficial for development containers due to improved filesystem performance and better resource utilization.

If you haven't set this up before, check out the Docker Desktop WSL2 backend documentation - they've got great step-by-step instructions.

Setting Up the Dev Container

Let's start with a pre-configured Dev Container template that includes MCP server integration for Claude: @gergelyszerovay/aibd-base-devcontainer. This foundation saves significant time compared to creating the setup from scratch.

This dev container comes with all the essentials: Node.js, popular package managers (npm, yarn, and pnpm), and Git. One nice touch is that it automatically uses the Git credentials you've already set up on your host machine, so you can start pushing and pulling code right away without extra authentication steps.

Let's set up our development container with a few simple commands:

mkdir your-project-name
cd your-project-name
git clone https://github.com/gergelyszerovay/aibd-devcontainer.git ./
code .

Opening the Container

After opening the your-project-name directory in VS Code, you'll see a notification asking if you want to reopen the folder in a container—go ahead and accept this prompt. If you miss it, no worries! Just click the green button in the lower-left corner of VS Code and select "Reopen in Container."

VS Code will build and start your container, which might take a minute on the first run. Subsequent starts will be significantly faster.

The container creates a Docker volume named after your project directory (like your-project-name-volume) and mounts it at /workspaces/your-project-name/volume/ inside the container. This approach ensures your development files persist across container restarts and rebuilds.
Why use a Docker volume instead of a simple host directory mount? It makes a huge difference for file watching functionality, which you'll definitely appreciate when you want features like auto-recompiling to work properly.

Project Setup

Now that your container is running, let's add your project files. Open a terminal within VS Code, navigate to the volume directory, and clone your repository:

cd /workspaces/your-project-name/volume
git clone https://github.com/your-username/your-project.git ./
pnpm install

Your project files now live in a persistent volume that both VS Code and Claude can access.

For those looking to jumpstart development with modern frameworks, I've created two specialized boilerplate templates that work in this Dev Container setup:

Angular Template

The AIBD Angular Template provides a ready-to-use Angular 19.2 foundation with:

• PNPM package manager for faster, more efficient dependency management

• TailwindCSS 3

• Testing configuration with Jasmine and Angular Testing Library

React Template

If React is more your style, check out the AIBD React Template featuring:

• React 19 with Vite

• TailwindCSS 3

• Zustand for lightweight state management

• TypeScript configuration for type safety

• Vitest and Testing Library for comprehensive testing

Both templates integrate seamlessly with the Dev Container approach we're discussing.

Integrating Claude AI Assistant

To connect Claude Desktop to your container's MCP server, you'll need to update your Claude configuration. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "devcontainer": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://localhost:3100/sse"]
    }
  }
}

We're using Supergateway as a proxy between Claude Desktop and our container's MCP server. This proxy is necessary because Claude Desktop currently can't connect directly to an MCP server running in a container.

After updating your configuration, make sure to restart Claude Desktop so it can recognize the new settings and connect to the MCP server in your Dev Container.

File Operations

With the MCP server properly configured, Claude becomes much more than just a chatbot, it can now:

• Read your code to understand what you're working with

• Examine directory structures to understand your project organization

• Suggest code changes with proper context

• Write or edit files

• Run shell commands to test your code, install packages, or perform other operations

This direct access transforms Claude from a conversational assistant to a coding partner that actually understands your project in context.

Here's a handy tip: when you want Claude to work with a specific file or directory in your project, VS Code makes it easy - just right-click on any file or directory in the VS Code Explorer and select "Copy Path". Then you can paste that exact path when talking to Claude.

Real-World Examples (React and Angular)

Let's walk through a practical example of this AI-assisted setup. I'll show you how to build a simple Tic-Tac-Toe game, which works whether you're using Angular or React.

Imagine you want to quickly prototype this game in your framework of choice. Here's what the workflow might look like:

Clone a Framework-Specific Boilerplate

First, let's clone one of our specialized boilerplates into the volume directory. When setting up our project, make sure to run these commands inside the dev container (not on your host machine):

For Angular:

cd /workspaces/your-project-name/volume
git clone https://github.com/gergelyszerovay/aibd-template-angular.git ./
pnpm install
pnpm run start

For React:

cd /workspaces/your-project-name/volume
git clone https://github.com/gergelyszerovay/aibd-template-react.git ./
pnpm install
pnpm run start

This gives us a solid foundation with all the essential tooling already configured - much better than starting from scratch!

Let Claude Explore Your Project Structure

Now, let's ask Claude to get a feel for our project:

🧑: Could you analyze my project structure in /workspaces/your-project-name/volume/ 
and identify the main component files?

This gives Claude context about your codebase organization before making changes - just like you'd want to orient yourself before diving into a new codebase.

Request the Implementation

For Angular:

🧑: Create a Tic-Tac-Toe game by updating my app.component.ts file at 
/workspaces/your-project-name/volume/src/app/app.component.ts and any 
other necessary files.

For React:

🧑: Create a Tic-Tac-Toe game by updating my App.tsx file at 
/workspaces/your-project-name/volume/src/App.tsx and any 
other necessary files.

Test the Implementation

Let's ask Claude to verify the code works correctly and catch any compilation errors:

🧑: Can you run `pnpm run build` and tell me if there are any 
compilation errors? 
If you encounter any issues, could you help me fix them?

Refine the implementation

After Claude creates the initial version, you might want to enhance it:

🧑: Could you add a game history feature that lets players review 
previous moves?

Conclusion

Combining Dev Containers with Claude AI through MCP creates a powerful development environment that changes how you interact with AI assistance while coding. You're firmly in control of your workflow, but you get to leverage AI capabilities in a secure, isolated environment.

Looking ahead, I'm planning to publish coding guidelines specifically designed for LLMs to ensure consistent coding style across your projects. These guidelines will help Claude generate code that follows our standards automatically, without you having to rewrite or adjust everything afterward. By establishing a shared understanding of your preferred patterns and practices, we can make AI assistance feel like a natural extension of your development team rather than just another tool.

Have you tried using AI assistants in your development workflow? I'd love to hear what's worked well for you!

About the Author

My name is Gergely Szerovay. I've worked as a data scientist and full-stack developer for many years, and I've been a frontend tech lead focusing on Angular development for the past three years. To closely follow the evolution of AI-assisted software development, I've decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular and how to build AI apps with AI, TypeScript, React, and Angular!

If you're enjoying this article and have a Medium subscription, I'd greatly appreciate if you'd open and read it there — your support helps me continue creating quality content like this!

Update: New title (previously it was "RAG in Action: Advanced Retrieval Techniques with Claude Desktop").

In the first part of this series, we built the foundation of our RAG system by setting up Qdrant, processing our AI-friendly Angular documentation, and configuring the MCP server to connect with Claude Desktop. This built upon our earlier exploration of AI-friendly documentation, where we saw how properly structured technical documentation significantly improves LLM responses.

Now that our infrastructure is in place, it's time to put it to work and explore increasingly sophisticated techniques for retrieving and leveraging documentation with Claude. The true power of RAG isn't just in having access to documentation—it's in how effectively you retrieve and use that information.

In this article, we'll progress from basic queries to advanced techniques that improve the quality and relevance of Claude's responses. We'll explore:

1. Basic RAG Queries for straightforward questions

2. 2-Step Method with Improved Response Synthesizer for better focus and precision

3. 3-Step Method with Multi-Query Retrieval for comprehensive coverage

4. Best practices and optimization strategies based on real-world experience

Whether you're using our Angular documentation or applying these techniques to your own knowledge base, these methods will transform how you interact with technical documentation through Claude.

Basic RAG Queries: Your First Retrieval Example

Let's see our RAG system in action with a simple example that builds on our standalone components question from the previous article. We'll ask: "Are standalone components default in Angular?"

In Claude Desktop, we'll use the following prompt with Claude 3.5 Haiku model since its knowledge cutoff date is before the release of Angular 19:

🧑: Use qdrant_retrieve on angular-19.2.3 collection, retrieve documents matching for the question: "Are standalone components default in Angular?".
Retrieve 50 documents.

When you send this message, several things happen behind the scenes:

1. Claude recognizes the request to use the qdrant_retrieve provided by the Qdrant Retrieve MCP Server

2. It sends your question to the MCP server

3. The server converts your question to a vector embedding

4. Qdrant searches for the 50 most similar document chunks

5. The retrieved chunks are sent back to Claude

6. Claude incorporates this information into its response

Understanding the Retrieval Request and Response

The MCP server receives a request that looks something like this:

{
  "topK": 50,
  "query": ["Are standalone components default in Angular?"],
  "collectionNames": ["angular-19.2.3"]
}

Qdrant then performs a vector similarity search and returns the most relevant document chunks. These typically include sections from the Angular documentation discussing standalone components, their configuration options, and default settings.

Claude receives these chunks and now has the specific information needed to provide an accurate, version-specific answer.

Analyzing Document Relevance Scores

Each retrieved document comes with a relevance score indicating how closely it matches your query. These scores range from 0 to 1, with higher values indicating greater relevance.

For our question about standalone components, we might see results like:

1. Documentation section on component creation options (score: 0.92)

2. Guide section about standalone components (score: 0.89)

3. API reference for ComponentOptions interface (score: 0.87)

4. Migration guide mentioning standalone defaults in Angular 19 (score: 0.86)

5. ... (and so on)

The documents clearly mention that in Angular versions before 19.0.0, the standalone option defaulted to false, but starting with Angular 19, standalone components are the default.

How Claude Uses the Retrieved Context

With this information available, Claude constructs an accurate response:

🤖: Yes, standalone components are now the default in Angular.
This changed in Angular version 19.0.0, where the standalone
option began defaulting to true. In previous versions (before 19.0.0),
the standalone option defaulted to false, which meant components
needed to be part of an NgModule by default.

This change reflects Angular's gradual move toward a modular
architecture that doesn't require NgModules for basic functionality.
Standalone components can be directly added to the imports array of
other components without needing a module.

Notice how Claude's response incorporates specific details from the retrieved documentation, including the version number where the change occurred. This is the power of RAG in action—Claude is able to provide version-specific information that might not have been in its original training data.

2-Step Method with Improved Response Synthesizer

While basic retrieval works well for straightforward questions, we can implement a more sophisticated approach for complex queries. This 2-step method mimics how a human researcher might work: first gathering information, then focusing on what's most relevant.

Why the 2-Step Method Works Better

The 2-Step Method breaks the retrieval and response process into two key stages:

1. Initial retrieval with filtering: Gather relevant documents and immediately identify the most valuable ones

2. Focused response generation: Create a precise answer based only on the most relevant information

This focused approach often improves response quality through enhanced synthesis capability. By concentrating on the most pertinent information, the LLM can create more precise, authoritative answers.

Implementing the 2-Step Method

Let's apply this technique to our standalone components question:

Step 1: Initial retrieval with filtering

🧑: Use qdrant_retrieve on angular-19.2.3 collection, retrieve documents
matching for the question: "Are standalone components default in Angular?".
Retrieve 50 documents, then show me the 3 most relevant ones
for answering this question.

This first prompt retrieves documentation and immediately identifies the most valuable chunks. Unlike the basic method, this approach intelligently filters for relevance before the final response generation.

From the 50 retrieved documents, Claude would identify three key ones:

1. A section from the component creation guide that explicitly states: "Starting from Angular 19.0.0, the standalone option defaults to true."

2. API documentation for the Component decorator showing: "standalone?: boolean - If true, this Component is not part of any NgModule. Default is true starting from v19, default was false before v19."

3. A migration guide section explaining the change: "Angular 19 changes the default for components, directives, and pipes to be standalone by default. This makes the framework more approachable for new developers."

Step 2: Generating a precise, document-backed response

🧑: Based on these 3 most relevant documents, answer the question:
"Are standalone components default in Angular?"

With the filtered context, Claude produces a concise, accurate response:

🤖: Yes, standalone components are the default in Angular, but this
is a relatively recent change. According to the Angular documentation:

1. Starting from Angular 19.0.0, the standalone option defaults to true
2. Before Angular 19.0.0, the standalone option defaulted to false
3. This change was made to make the framework more approachable for new developers

This means that if you're using Angular 19 or newer, any new components
you create will be standalone by default unless you explicitly set
`standalone: false` in the component decorator.

Notice how this 2-step method yields a precise answer with specific version information and rationale for the change. The improved response synthesizer creates well-structured content directly tied to the most relevant documentation sources.

3-Step Method with Multi-Query Retrieval

Building on our 2-Step Method, the 3-Step Method with Multi-Query Retrieval takes result quality even further. By introducing query variation as a preliminary step, this technique addresses a fundamental limitation in RAG systems: the phrasing of your original query might not perfectly match how information is expressed in the documentation.

Why Query Generation Improves Results

A single query, no matter how well-formulated, can miss relevant documentation due to vocabulary mismatches or missing context. For example, when asking about "standalone components in Angular," relevant documentation might use phrases like:

• "Components without NgModules"

• "Self-contained components"

• "Components with standalone: true"

• "Module-less components"

By generating multiple alternative queries, we cast a wider net and increase our chances of finding all relevant information, even when it uses different terminology or approaches the concept from different angles.

Implementing the 3-Step Method

Let's apply this comprehensive technique to our standalone components question:

Step 1: Generate multiple query variations

🧑: Generate 9 RAG queries based on the question "Are standalone components
default in Angular?". Then use qdrant_retrieve on angular-19.2.3
collection for retrieving 50 documents.
Do not reply, just retrieve the documents.

In this first step, Claude creates multiple versions of the query, each phrased differently to maximize retrieval coverage. For example:

1. "Are standalone components the default option in Angular 19?"

2. "Did Angular change the default value of standalone in component configuration?"

3. "What is the default value of the standalone property for Angular components?"

Step 2: Retrieve and filter results across all queries

🧑: Show the 3 documents that help most for answering
the original question better.

This step consolidates the results from all queries, identifying the most relevant documents across the entire retrieval set.

Step 3: Enhanced response synthesis

🧑: Based on these 9 documents, answer the original question:
"Are standalone components default in Angular?"

With input from multiple angles combined with the improved response synthesizer, Claude produces a comprehensive answer that incorporates insights from diverse query perspectives, creating the most authoritative and complete response possible.

🤖: Yes, standalone components are the default in Angular.
Based on the documentation:

Components must be explicitly marked as standalone: false
to be declared in an NgModule, indicating that the default state
is standalone.

The Angular team officially recommends using standalone components
instead of NgModules for all new code.

When migrating existing code, the process involves removing
standalone: false flags and adding imports directly to components,
showing that standalone is now the standard approach.

Angular provides a strictStandalone compiler option that,
when enabled, reports errors if components aren't standalone,
reinforcing this as the preferred pattern.

The framework offers dedicated bootstrapping methods for
standalone components (bootstrapApplication), which is
recommended over the NgModule-based approach.

In summary, while Angular maintains backward compatibility
with NgModule-based applications, standalone components are
now the default and recommended approach for building Angular
applications.

Summary and Future Directions

Throughout this series on AI-friendly documentation and RAG systems, we've discovered that:

1. Documentation structure matters: As we saw in the first article, clear headers and well-organized content dramatically improve retrieval quality

2. Vector embeddings preserve meaning: Our LlamaIndex-powered pipeline converts documentation into semantic chunks that maintain their contextual relationships

3. Retrieval strategy is as important as infrastructure: The techniques you use to query your documentation can be even more important than the underlying technical setup

4. Multiple approaches yield better results: Combining different retrieval strategies provides more comprehensive coverage of complex topics

Future Directions

This is just the beginning of what's possible with RAG systems for documentation. Here are some exciting directions to explore:

• Multi-collection retrieval: Search across multiple documentation sources simultaneously (e.g., Angular, TypeScript, RxJS)

• Adaptive retrieval strategies: Automatically select the optimal retrieval technique based on question type. For example, we should use different approaches when searching inline comments in source code versus formal Angular documentation

• Automated evaluation: Measure the quality of responses against ground truth answers

• Token-based retrieval limits: Rather than retrieving a fixed number of documents, optimize retrieval by setting token limits. This balances relevance with cost efficiency, as token usage directly impacts API costs while ensuring you get the maximum relevant information.

• Hierarchical document retrieval: Build retrieval systems that understand document structure and can pull in related sections from the same document. This maintains the contextual continuity between retrieved chunks while still focusing on the most relevant information.

Beyond Documentation

While we've focused on Angular documentation in this series, the techniques we've explored apply to any domain with structured knowledge. Consider applying these approaches to:

• Internal company documentation and knowledge bases

• Product manuals and support documentation

• Legal documents and regulatory frameworks

By understanding and implementing these RAG techniques, you're not just improving how you interact with Angular documentation—you're developing skills that transform how you work with information across all domains.

About the Author

My name is Gergely Szerovay. I've worked as a data scientist and full-stack developer for many years, and I've been a frontend tech lead focusing on Angular development for the past three years. To closely follow the evolution of AI-assisted software development, I've decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular and how to build AI apps with AI, TypeScript, React, and Angular!

If you're enjoying this article and have a Medium subscription, I'd greatly appreciate if you'd open and read it there — your support helps me continue creating quality content like this!

In the previous article, Getting Better LLM Responses Using AI-Friendly Documentation, we explored how creating AI-friendly documentation can improve the quality of responses from Large Language Models (LLMs). We saw how properly structured Angular documentation helped ChatGPT provide more accurate answers about framework features. Let's advance our documentation strategy by implementing our own Retrieval-Augmented Generation (RAG) system, powered by Qdrant and designed to work hand-in-hand with Claude Desktop.

Introduction: Taking RAG from Concept to Implementation

Let's quickly revisit what makes documentation "AI-friendly." Remember those key principles? Clear headers, comprehensive single files, and focused feature-specific content. These organization techniques aren't just theoretical—they make a real difference in how LLMs understand our technical docs.

While the file upload approach we explored previously works reasonably well, it comes with limitations. Most notably, you're constrained by context window sizes, and you need to manually select which documentation to include in each conversation. This creates a frustrating cycle of starting new conversations whenever you need to reference different documentation sections.

Custom RAG systems solve these problems by automatically retrieving just the most relevant documentation fragments for any given question. Think of it as having a research assistant who instantly pulls exactly the right pages from your technical library without you having to specify which books to check.

In this guide, I'll walk you through:

• Setting up your own Qdrant vector database for documentation storage

• Processing and indexing your AI-friendly Angular documentation

• Configuring an MCP server that connects Qdrant to Claude

• Building a RAG pipeline for documentation retrieval

By the end, you'll have a RAG system that significantly enhances Claude's ability to assist with software development.

Understanding RAG Components for Documentation

Before diving into implementation details, let's explore the key components that make up our RAG system.

Vector Embeddings

At the heart of any RAG systems are vector embeddings. These are numerical representations of text that capture semantic meaning in a way that computers can process. When we convert text to vectors, we're essentially mapping the content into a mathematical space where similar concepts cluster together.

For example, the phrases "component initialization" and "component creation" would have vector representations that are close to each other in this space, even though they use different words. This allows us to find relevant documentation based on meaning rather than just keyword matching.

We create these vector embeddings using specialized embedding models, which transform text into these high-dimensional mathematical representations while preserving semantic meaning.

Qdrant is a vector database optimized for storing and searching these embeddings.

MCP: Standardized Tool Communication

The Model Context Protocol (MCP) is a standardized interface that allows external tools like our RAG system to communicate with Claude and other LLMs. Developed by Anthropic, MCP defines how Claude can interact with our custom qdrant-retrieve server, which in turn connects to our Qdrant vector database.

When you ask a question, the qdrant-retrieve MCP server:

1. Receives the query from Claude

2. Translates it into a vector search for Qdrant

3. Processes the search results

4. Returns the most relevant documentation fragments to Claude

This happens seamlessly in the background, giving Claude access to your entire documentation set without overloading its context window.

Architecture Overview

Our complete solution works like this:

Documentation Processing Pipeline:

• AI-friendly documentation is divided into semantic chunks

• Each chunk is converted to vector embeddings

• Embeddings are stored in Qdrant collections

Retrieval Process:

• User asks a question in Claude Desktop

• Question is sent to the qdrant-retrieve MCP server

• MCP server converts the question to a vector

• Qdrant retrieves the most similar documentation chunks

• Relevant chunks are sent back to Claude

• Claude generates an answer using the retrieved context

This architecture gives us the flexibility to handle complex questions while maintaining high accuracy and context relevance.

Setting Up Your RAG Environment

Now that we understand the theory, let's get our hands dirty and set up the environment. Don't worry if you're new to these tools — I'll guide you through each step.

Installing and Configuring Qdrant

Qdrant can be run as a Docker container, which makes setup relatively straightforward:

# Download the latest Qdrant image from Dockerhub
docker pull qdrant/qdrant

# Run the service
docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

This configuration stores all data in the ./qdrant_storage directory on your machine. Using this shared directory gives you two big advantages: your data persists even if you restart the container, and you can directly access your vector database files during development.

Once Qdrant is running, you'll have access to:

• REST API:

http://localhost:6333

• for programmatic interactions

• Web UI: http://localhost:6333/dashboard for visually exploring and managing your collections

If you prefer not to run Qdrant locally, you can also use Qdrant Cloud, which offers a free tier with 1GB of storage - more than enough for our documentation use case. Check out the official guides for more detailed setup instructions: Local Quickstart or Cloud Quickstart.

Preparing Angular Documentation for Qdrant with LlamaIndex.TS

Now that we have Qdrant running, let's create our vector collection. In Qdrant, a collection is a named container for related vector embeddings - like a database table but optimized for similarity search. We'll use LlamaIndex.TS, a powerful TypeScript framework that simplifies the entire RAG pipeline from document processing to retrieval.

To create your own collection of Angular documentation embeddings, I've prepared a ready-to-use project that handles all the heavy lifting. Here's how to get started:

# Clone the repository
git clone https://github.com/gergelyszerovay/ai-friendly-docs
cd ai-friendly-docs

# Install dependencies
pnpm install

# Generate Angular documentation and embeddings
pnpm run generate:angular

This script performs three key operations:

1. Repository Cloning: Automatically downloads the specific version of Angular documentation from GitHub

2. Documentation Generation: Transforms the official Angular docs into AI-friendly formats

3. Vector Embedding Creation: Creates and stores vector embeddings in your local Qdrant instance running at

http://localhost:6333

The AI-Friendly Documentation project includes a function that builds collections from the Angular documentation. Let's look at how this tool works to understand the underlying process.

The Collection Pipeline

Here's the high-level flow for creating a searchable vector collection from our AI-friendly Angular docs:

async function generateQdrantCollection() {
  // 1. Configure your embedding model
  Settings.embedModel = new HuggingFaceEmbedding({
    modelType: "Xenova/all-MiniLM-L6-v2",
  });

  // 2. Locate your documentation files
  const docsDir = "./ai-friendly-docs/angular-19.2.3/sections";
  const files = findMarkdownFiles(docsDir);

  // 3. Create the vector collection
  await createCollectionFromMarkdownFiles("angular-19.2.3", files);
}

Let's take a closer look at the code that processes our Angular documentation and creates embeddings:

async function createCollectionFromMarkdownFiles(collectionName, files) {
  // Initialize parser for smart document chunking
  const markdownNodeParser = new MarkdownNodeParser();
  let allNodes = [];

  // Process each documentation file
  for (const filePath of files) {
    const text = fs.readFileSync(filePath, "utf-8");
    const document = new Document({
      text,
      metadata: { originalFile: path.basename(filePath) },
    });

    // Convert document to semantic chunks
    const nodes = markdownNodeParser([document]);
    allNodes = [...allNodes, ...nodes];
  }

  // Connect to Qdrant and store the embeddings
  const vectorStore = new QdrantVectorStore({
    url: "http://localhost:6333",
    collectionName,
  });

  // Create and store the embeddings
  return await VectorStoreIndex.fromDocuments(allNodes, {
    vectorStores: { TEXT: vectorStore },
  });
}

The real power comes from how LlamaIndex processes our documentation. Rather than treating files as monolithic blocks or arbitrarily splitting text by character count, it intelligently chunks the content based on semantic structure.

The MarkdownNodeParser is what makes this possible. It analyzes the hierarchy of headers in our Markdown files (# for top-level, ## for second-level, etc.) and creates natural boundaries between content sections. For example:

• A section about component inputs under ## Inputs becomes its own chunk

• This chunk is separate from the ## Outputs section that might follow it

• Both chunks maintain metadata connecting them to their parent document

This semantic chunking means when Claude searches for information about "component inputs," it gets precisely the relevant sections, not the entire components guide.

Why This Matters for Retrieval Quality

The quality of document chunking directly impacts how relevant your search results will be. Each chunk in our system:

• Preserves its hierarchical context (parent headers, document source)

• Contains conceptually complete information (not cutting off mid-explanation)

• Has the right granularity for targeted retrieval

When LlamaIndex creates embeddings for these chunks and stores them in Qdrant, it maintains all this contextual information. This means when Claude asks Qdrant for the most similar documents to a query, it gets well-formed, semantically meaningful content – not random text fragments.

This approach works particularly well for technical documentation with consistent header structures, which is exactly what we created in our AI-friendly Angular docs.

Setting Up the MCP Server

The MCP server is the component that connects Claude to Qdrant. For our implementation, we'll use the @gergelyszerovay/mcp-server-qdrant-retrieve package, which provides a ready-to-use MCP server for Qdrant retrieval integration.

To integrate the MCP server with Claude Desktop, add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@gergelyszerovay/mcp-server-qdrant-retrieve"],
      "env": {
        "QDRANT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note that for a basic local Qdrant setup without authentication enabled, you can simply use an empty env object. If you're using Qdrant Cloud or have configured authentication on your local instance, you'll need to add your API key as an environment variable.

The server exposes a qdrant_retrieve tool that Claude can call to search for relevant documentation fragments based on your questions.

A Quick Test: Your First Retrieval

Before wrapping up, let's do a quick test to make sure everything is working. With your Qdrant server running and MCP configured, ask Claude this simple question about Angular:

Use qdrant_retrieve on angular-19.2.3 collection, retrieve documents matching for the question: "Are standalone components default in Angular?". Retrieve 3 documents.

If everything is set up correctly, Claude should make a request to your MCP server, which then searches Qdrant and returns the most relevant documentation fragments. You should see Claude incorporate information about standalone components becoming the default in Angular 19.0.0.

Note that the first vector database retrieval might be a bit slower, as the MCP server needs to download the required embedding model. Subsequent queries will be much faster.

This quick test confirms that:

1. Your Claude Desktop can communicate with the MCP server

2. The MCP server can successfully query your Qdrant collection

3. The retrieved documents contain meaningful, relevant information

Now that we've confirmed the basic functionality, we're ready to explore more sophisticated retrieval techniques in the next article.

Conclusion and Next Steps

In this first part of our RAG journey, we've laid the groundwork for a powerful documentation retrieval system. We've:

1. Explored the key components of a RAG system (vector embeddings, vector databases, and MCP)

2. Set up Qdrant for vector storage and understood how to create collections

3. Processed AI-friendly Angular documentation into semantically meaningful chunks

4. Configured the MCP server to connect Claude Desktop with our vector database

With these fundamentals in place, you now have a functioning RAG system ready to enhance your interactions with Claude. The infrastructure we've built provides a flexible foundation that can work with any documentation set, not just Angular.

In the next part of this series, we'll explore how to effectively use this system, including basic and advanced retrieval techniques that will significantly improve Claude's ability to answer technical questions. We'll walk through real-world examples and develop increasingly sophisticated approaches to get the most accurate and relevant information from our documentation.

Stay tuned for "How to Get Better Technical Answers from Claude Using Your Own Documentation - From Basic Queries to Expert Documentation Retrieval Applying Retrieval-Augmented Generation (RAG)" where we'll put this system to work!

About the Author

My name is Gergely Szerovay. I've worked as a data scientist and full-stack developer for many years, and I've been a frontend tech lead focusing on Angular development for the past three years. To closely follow the evolution of AI-assisted software development, I've decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular and how to build AI apps with AI, TypeScript, React, and Angular!

If you're enjoying this article and have a Medium subscription, I'd greatly appreciate if you'd open and read it there — your support helps me continue creating quality content like this!

Update (June 2025): Added reference to the Angular team's two official LLMs.txt files that help LLMs create better modern Angular code.

Have you ever felt that moment of frustration when a Large Language Model completely misunderstands your coding question? We've all been there. The truth is, LLMs are a lot like our developer colleagues - the quality of their help depends heavily on the context we provide.

Think of it this way: just as you wouldn't ask a teammate for help with a complex bug without sharing the relevant code, LLMs need proper context to give you their best advice. That's where AI-friendly documentation comes in, and I'd like to share what I've learned while creating some for Angular.

The Quest for Better Context

That's what inspired me to start collecting AI-friendly documentation. Here are some notable examples:

• Model Context Protocol: https://modelcontextprotocol.io/llms-full.txt offers complete documentation in a single file

• Daisy UI v5: https://daisyui.com/llms.txt provides both comprehensive docs and component-specific versions

There are several approaches to feeding this knowledge to your AI assistant:

• Sending documentation directly as a chat message to the LLM

• Uploading relevant files to your conversation

• Using a Retrieval-Augmented Generation (RAG) system to intelligently fetch information

As part of this exploration, I've created AI-friendly documentation for Angular, which you can find here: https://github.com/gergelyszerovay/ai-friendly-docs/

Update (June 2025):
The Angular team has developed two official LLMs.txt files to help LLMs and tools that use LLMs for code generation create better modern Angular code:

• llms.txt - an index file providing links to key files and resources.

• llms-full.txt - a more robust compiled set of resources describing how Angular works and how to build Angular applications.

Beyond Basic File Uploads

While most chat interfaces let you upload files, Claude Desktop takes this further with its Project Knowledge feature. It allows you to provide documents, code, and other materials that Claude can reference during conversations. With a massive context window of 200,000 tokens (roughly 500 pages of text), Claude can maintain a deeper understanding of complex projects, making its responses significantly more accurate.

A context window, by the way, is essentially how much information an LLM can "keep in mind" during a single conversation - think of it as the AI's working memory. It's measured in tokens, which are the basic units that LLMs process (roughly corresponding to word fragments). For example, the sentence "I love programming in TypeScript" might be broken down into tokens like ["I", "love", "program", "ming", "in", "Type", "Script"]. The larger the context window, the more information the LLM can consider when generating responses.

The Magic Behind RAG Systems

RAG (Retrieval-Augmented Generation) is what powers these context-aware AI interactions. Rather than simply dumping all information into the model, RAG systems intelligently retrieve the most relevant pieces for your specific question.

It's like having a helpful librarian instead of being handed a pile of books - the librarian knows exactly where to find the information you need. When your documentation has clear headers and organized sections, the retrieval system can pinpoint relevant information much more precisely.

Under the hood, RAG systems work by converting your documentation into vector embeddings—numerical representations that capture semantic meaning. When you ask a question, the system converts it to the same format and finds the most similar sections in your documentation. Pretty neat, right?

I'll be diving deeper into RAG systems in an upcoming article, so stay tuned if you're curious about setting up your own.

Building Better Angular Documentation

Here are the principles I've found most helpful when creating AI-friendly documentation:

1. Create a comprehensive single file containing the entire framework or library documentation for when you need broad knowledge

2. Develop separate, focused files for specific features that can be included individually when you need targeted information

3. Maintain clear header structures to help AI systems understand relationships between different documentation sections

I've applied these ideas to my Angular documentation project. Starting with the official Angular docs, I've created both a comprehensive angular-full.md file and individual feature-specific files in the sections directory. This approach gives you flexibility in how you provide context to your AI assistants.

The Importance of Clear Header Structures

That third principle (maintaining clear header structures) deserves special attention because it dramatically affects how well AI systems can navigate your documentation.

Let me show you what I mean with an example from the Angular documentation. The original file guide/components/inputs.md begins with:

# Accepting data with input properties

Tip: This guide assumes you've already read the [Essentials Guide](essentials). 
Read that first if you're new to Angular.

Tip: If you're familiar with other web frameworks, input properties 
are similar to _props_.

When you use a component, you commonly want to pass some data to it. 
A component specifies the data that it accepts by declaring **inputs**:

// ...

From the file's name and content alone, it's not immediately obvious that this document explains component inputs within Angular's component architecture.

In my AI-friendly version in guide-components.md, I've added an additional header that provides this crucial context:

# Guide Components

// ...

## Accepting data with input properties

Tip: This guide assumes you've already read the [Essentials Guide](essentials). 
Read that first if you're new to Angular.

Tip: If you're familiar with other web frameworks, input properties 
are similar to _props_.

When you use a component, you commonly want to pass some data to it. 
A component specifies the data that it accepts by declaring **inputs**:

// ...

This hierarchical structure helps AI systems understand that component inputs are a subtopic within Angular components. This context is especially valuable for retrieval systems that might pull just a section of documentation, as it helps the AI properly frame the information within Angular's component architecture.

Being Strategic About Context Size

One valuable lesson I've learned is to be thoughtful about what you include in your AI's context window.

Sending the entire angular-full.md file isn't always the best move. For instance, if you're working on Angular components, you'll get much better results by including just sections/guide-components.md and perhaps a few related files like guide-templates.md or guide-di.md.

This targeted approach helps the AI focus on what matters most without getting distracted by unrelated documentation. Sometimes less really is more when it comes to context.

Seeing It in Action: A Real Example

Let's look at a straightforward question: "Are standalone components default in Angular?"

This is an interesting case because before Angular 19.0.0, the standalone option defaulted to false, but in version 19 it changed to true. I tested this question with different LLMs, providing varying levels of documentation context.

ChatGPT (GPT-4o)

Test 1: No documentation provided

🧑: Are standalone components default in Angular?

🤖: No, standalone components are not the default in Angular. By default, 
Angular components are part of NgModules, meaning they must be declared 
inside an @NgModule.

However, Angular introduced standalone components in Angular 14 to allow 
components to work without being declared inside an @NgModule. Instead, 
they use the standalone: true flag in their decorator.

This response is outdated and lacks awareness of Angular 19's changes: a perfect example of why context matters.

Test 2: Full Angular documentation added

🧑: Are standalone components default in Angular?

🤖: No, standalone components are not the default in Angular, but they 
are encouraged as a simplified way to build applications. In Angular 
versions before 19.0.0, the standalone option defaults to false, meaning 
components are part of an NgModule by default​. However, newer Angular 
versions allow developers to migrate existing applications to standalone 
mode incrementally without breaking changes​.

Much better! The model correctly identifies the version cutoff, though
it's still a bit hesitant to clearly state they're now the default in v19+.

Test 3: Only guide-components.md added

🧑: Are standalone components default in Angular?

🤖: Yes, in Angular, components are standalone by default. This means 
you can directly add them to the imports array of other components without 
needing an NgModule. However, components created with older versions of 
Angular may have standalone: false in their @Component decorator, 
requiring them to be part of an NgModule.

Important Note: In Angular versions before 19.0.0, the standalone option 
defaulted to false​.

Perfect! With the targeted documentation, we get the most accurate and confident answer.

These examples highlight how crucial proper documentation context is for accurate AI responses. When asking different LLMs this question without providing documentation context, you'll often get responses that sound plausible but might not reflect the latest updates. The LLM is working from its training data, which might be outdated or incomplete.

However, when you provide the relevant section of Angular documentation, the response changes dramatically. It's like the difference between asking a developer who last used Angular a year ago versus one who's working with the latest version daily.

Adding Code Context to the Mix

Documentation is just one piece of the puzzle. For truly effective AI assistance with development tasks, you often need to provide code alongside documentation.

If you're looking to optimize source code for AI consumption, check out Repomix (

https://repomix.com/

). It's a great tool that helps consolidate entire codebases into a single, AI-friendly file.

Repomix handles token count management (crucial for staying within context limits), excludes sensitive information, and produces output in various formats. It's the perfect companion to AI-friendly documentation when you need to provide both docs and code context.

AI-Friendly Documentation vs. Web Retrieval

Why create AI-friendly documentation when many LLMs can now access the web?

While web access is undoubtedly valuable, it presents several limitations compared to carefully curated documentation:

1. Version Specificity: Web searches may return information about different versions of a framework or library than the one you're using. AI-friendly documentation can be created specifically for your exact version, eliminating confusion and inconsistencies.

2. Accuracy Control: Web content varies widely in quality and accuracy. Curated documentation ensures the LLM works with verified, reliable information rather than potentially outdated or incorrect sources.

3. Contextual Coherence: When an LLM retrieves information from multiple web sources, it must reconcile potentially conflicting information. Curated documentation provides a unified, coherent context that leads to more consistent responses.

4. Reduced Hallucinations: With clear, comprehensive documentation, LLMs are less likely to "fill in the gaps" with incorrect assumptions, reducing hallucinations and increasing accuracy.

For example, in our earlier test case about Angular standalone components, a web search might return outdated information from various sources. Our curated documentation, however, clearly indicated the version-specific change in Angular 19, resulting in a more accurate response.

Looking Forward

We've explored how AI-friendly documentation can significantly improve the quality of responses from LLMs. The key takeaway from my work with Angular documentation and tools like Repomix is that structuring information specifically for AI consumption yields dramatically better results.

Based on my experience, there are two key approaches for enhancing AI capabilities:

Context Enhancement: This is what we've discussed throughout this article - providing additional context through well-structured documentation and code. This approach works with existing models and gives them better information to work with.

Tool Integration: The next evolution in AI assistance comes through standardized integration methods, particularly the Model Context Protocol (MCP) developed by Anthropic. MCP is a specification that defines how AI models can communicate with external tools in a standardized way. Unlike earlier approaches where each AI service had its own custom integration methods, MCP provides a common language for tool definitions, invocations, and responses.

These approaches complement each other: better documentation helps LLMs understand what tools to use, while integrated tools expand their capabilities. I am currently developing RAG tools that leverage MCP and will share these developments in my upcoming articles:

• Building Your Own RAG System: Enhancing Claude with Your Documentation

• How to Get Better Technical Answers from Claude Using Your Own Documentation

About the Author

My name is Gergely Szerovay. I've worked as a data scientist and full-stack developer for many years, and I've been a frontend tech lead focusing on Angular development for the past three years. To closely follow the evolution of AI-assisted software development, I've decided to start building AI tools in public and publish my progress on AIBoosted.dev.

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular and how to build AI apps with AI, TypeScript, React, and Angular!

Subscribe now

This is the fourth part of my AI-Boosted Development series:

• The introduction summarized recent changes enabling easy AI app prototyping in TypeScript.

• The second article covered installing Jupyter Lab IDE and tools for rapid prototyping.

• The third part explained how to use JupyterLab and demonstrated basic coding workflow.

This article focuses on building the first part of the "Text Reviewer" app. As I explained in the introduction, the app works in two steps:

1. The user enters text, which an LLM model reviews and improves.

2. The tool compares the LLM's result to the original text and shows the changes.

We'll cover the first step here, showing a basic LangChain chain that reviews and improves text.

The second step doesn't use a language model. If we ask a language model to list changes compared to the original text, it often returns incorrect or incomplete results. These models can generate textual outputs or improve a text's quality, but they're not good at algorithmic tasks. They process prompts and try to predict the expected answer. They do not "think" or possess human-like logical capabilities. However, we can use a language model to generate the source code of a text comparison function. We'll use an LLM to generate code for text comparison in future articles.

Language models can respond in different formats, such as Markdown, JSON, or XML. In the examples below, we ask the models to provide JSON responses in a predefined schema. JSON responses work well if the schema is simple and the response doesn't contain many special characters.

This article is also available on dev.to with better source code syntax highlighting.

Prompt template + OpenAI model + JSON output

In the example below, we implement the reviewTextOpenAI function with the following signature:

/**
 * Reviews and corrects the input text using OpenAI's GPT-4o model.
 * 
 * @param instruction - Instructions to be given to the model.
 * @param inputText - The text to be reviewed and corrected.
 * @returns - The reviewed and corrected text, or undefined if the response is invalid.
 */
reviewTextOpenAI(instruction: string, inputText: string): Promise<string | undefined>

Example function call and output:

// Define the instruction and input text for the prompt
const instruction = "Fix the grammar issues in the following text.";
const inputText = "How to stays relevant as the developer in the world of ai?";

// Log the result of the review function (OpenAI version)
console.log(await reviewTextOpenAI(instruction, inputText));
// CONSOLE: How to stay relevant as a developer in the world of AI?

The reviewTextOpenAI function does the following:

• Creates a prompt template.

• Defines a JSON schema using Zod.

• Creates an language model (GPT-4o) wrapper, that returns the response in the format we defined with our JSON schema. We use the .withStructuredOutput method to get JSON output from the model.

• Connects the prompt template with the language model to create a chain.

• Calls the chain with the provided inputText and instruction

Here is the complete code for the function (you can download it in a Jupyter Notebook):

/**
 * Reviews and corrects the input text using OpenAI's GPT-4o model.
 * 
 * @param instruction - Instructions to be given to the model.
 * @param inputText - The text to be reviewed and corrected.
 * @returns - The reviewed and corrected text, or undefined if the response is invalid.
 */
async function reviewTextOpenAI(instruction: string, inputText: string): Promise<string | undefined> {
  // Create a prompt template using the provided instruction and input text
  const prompt = PromptTemplate.fromTemplate(
`{instruction}
---
{inputText}`);

  // Initialize the OpenAI chat model with specified options
  const llm = new ChatOpenAI({
    modelName: "gpt-4o", // Use the GPT-4 model
    verbose: false, // Disable verbose logging
  });

  // Define the schema for the model's output, it contains the reviewed text  
  const reviewedTextSchema = z.object({
    reviewedText: z.string().describe("The reviewed text.") // The reviewed text must be a string
  });
  type ReviewedTextSchema = z.infer<typeof reviewedTextSchema>; // Infer the TypeScript type from the Zod schema

  // We expect structured JSON output, we achieve this using OpenAI's function calling feature
  const llmWithStructuredOutput = llm.withStructuredOutput(reviewedTextSchema, {
    method: "functionCalling",
    name: "withStructuredOutput"
  });  

  // Create a processing chain combining the prompt and the LLM
  const chain = prompt.pipe(llmWithStructuredOutput);

  // Invoke the chain with the instruction and input text, and wait for the response
  const response: ReviewedTextSchema = await chain.invoke({ instruction, inputText });

  // Return the reviewed text if present in the response, otherwise undefined  
  return response?.reviewedText;
}

// Define the instruction and input text for the prompt
const instruction = "Fix the grammar issues in the following text.";
const inputText = "How to stays relevant as the developer in the world of ai?";

// show the reviewed text returned by the LLM
console.log(await reviewTextOpenAI(instruction, inputText));

Let's break down each part of the code. The function reviewTextOpenAI takes two parameters: an instruction and the input text. It returns a reviewed and corrected text or undefined if the response is invalid:

async function reviewTextOpenAI(instruction: string, inputText: string): Promise<string | undefined> {

We use the declarative LangChain Expression Language (LCEL) to compose chains. The first element of our chain is the prompt template that has two parameters: instruction and inputText. We assign values to these parameters when we execute the chain.

const prompt = PromptTemplate.fromTemplate(
`{instruction}
---
{inputText}`);

We initialize the OpenAI chat model wrapper. We use the gpt-4o model and disable verbose logging. Learn more about the ChatOpenAI model wrapper here.

const llm = new ChatOpenAI({
 modelName: "gpt-4o",
 verbose: false,
});

We define the schema for the model's output using the Zod library. The schema specifies that the output should have a property reviewedText, which must be a string. Then, we use z.infer to create a TypeScript type from this schema. This ensures our code knows exactly what type of data to expect.

const reviewedTextSchema = z.object({
 reviewedText: z.string().describe("The reviewed text.")
});
type ReviewedTextSchema = z.infer<typeof reviewedTextSchema>; // Infer the TypeScript type from the Zod schema

We configure the model to produce structured JSON output using Langchain's .withStructuredOutput() method:

const llmWithStructuredOutput = llm.withStructuredOutput(reviewedTextSchema, {
 method: "functionCalling",
 name: "withStructuredOutput"
});  

We create a processing chain that combines the prompt and the model configured for structured output. Learn more about Langchain's LCEL chains and the pipe() method here.

const chain = prompt.pipe(llmWithStructuredOutput);

Finally, we invoke the processing chain with the instruction and input text, then wait for the response. We return the reviewed text if it is present in the response. Otherwise, we return undefined.

const response: ReviewedTextSchema = await chain.invoke({ instruction, inputText });   
return response?.reviewedText;

The OpenAI API requires an API key. In JupyterLab, we provide this key with the OPENAI_API_KEY environment variable, so we have to create a .env file with an OpenAI API key:

OPENAI_API_KEY=[your OpenAI API key]

Then we use the import "https://deno.land/std@0.215.0/dotenv/load.ts"; statement for reading the .env file and set the environment variables.

Prompt template + Ollama model + JSON output

Ollama-based models need a different approach for JSON output. LangChain's .withStructuredOutput doesn't support Ollama yet, so we use the OllamaFunctions wrapper's function calling feature.

Example function call and output:

// Define the instruction and input text for the prompt
const instruction = "Fix the grammar issues in the following text.";
const inputText = "How to stays relevant as the developer in the world of ai?";

// Log the result of the review function (Ollama version)
console.log(await reviewTextOllama(instruction, inputText));
// CONSOLE: How to stay relevant as a developer in the world of AI?

The steps are like those of the OpenAI implementations, with one difference: the method used to get JSON the output. The reviewTextOllama function does the following:

• Creates a prompt template.

• Defines a JSON schema using Zod.

• Creates an LLM (Ollama / Codellama) wrapper that returns the response in the format defined by our JSON schema. We use function calling to get JSON output from the model.

• Connects the prompt template with the language model to create a chain.

• Calls the chain with the given inputText and instruction

Here is the complete code for the function (you can download it in a Jupyter Notebook):

/**
 * Processes a given text using a language model to review and correct it based on the provided instruction.
 * 
 * @param instruction - Instruction for the language model on how to process the text.
 * @param inputText - The text that needs to be reviewed and corrected.
 * @returns The reviewed text if successful, otherwise undefined.
 */
async function reviewTextOllama(instruction: string, inputText: string): Promise<string | undefined> {
  // Create a prompt template by combining the instruction and input text
  const prompt = PromptTemplate.fromTemplate(
`{instruction}
---
{inputText}`);

  // Define a schema for the expected output using zod
  const reviewedTextSchema = z.object({
    reviewedText: z.string().describe("The reviewed text.") // Define the structure and description of the reviewed text
  });
  type ReviewedTextSchema = z.infer<typeof reviewedTextSchema>; // Infer the TypeScript type from the zod schema

  // Initialize the language model with specific configuration
  const llm = new OllamaFunctions({
    baseUrl: "http://localhost:11434", // Base URL for the language model server
    model: "codellama:7b-code", // Specify the model to use
    verbose: false, // Disable verbose logging
  }).bind({
    functions: [
      {
        name: "storeResultTool", // Function name used in the language model
        description: "Gets the reviewed text", // Description of the function
        parameters: {
          type: "object", // Define the type of parameters expected by the function
          properties: zodToJsonSchema(reviewedTextSchema), // Convert zod schema to JSON schema
        },
      },
    ],
    function_call: {
      name: "storeResultTool", // Specify the function to be called
    },
  });

  // Create a processing chain: prompt -> language model -> JSON output parser
  const chain = prompt.pipe(llm).pipe(new JsonOutputFunctionsParser());

  // Invoke the chain with the instruction and input text
  const response = await chain.invoke({ instruction, inputText });

  // Return the reviewed text if available
  return response?.reviewedText;
}

// Define the instruction and input text for the prompt
const instruction = "Fix the grammar issues in the following text.";
const inputText = "How to stays relevant as the developer in the world of ai?";

// Log the result of the review function
console.log(await reviewTextOllama(instruction, inputText));

Let's see how we set up the Ollama wrapper to use the codellama model with JSON response in our code.

  // Initialize the language model with specific configuration
  const llm = new OllamaFunctions({
    baseUrl: "http://localhost:11434", // Base URL for the language model server
    model: "codellama:7b-code", // Specify the model to use
    verbose: false, // Enable verbose logging
  }).bind({
    functions: [
      {
        name: "storeResultTool", // Function name used in the language model
        description: "Gets the reviewed text", // Description of the function
        parameters: {
          type: "object", // Define the type of parameters expected by the function
          properties: zodToJsonSchema(reviewedTextSchema), // Convert zod schema to JSON schema
        },
      },
    ],
    function_call: {
      name: "storeResultTool", // Specify the function to be called
    },
  });

When we create the Ollama wrapper (OllamaFunctions) , we pass a configuration object to it with the model's name and the baseUrl for the Ollama server.
We use the .bind function on the created OllamaFunctions instance to define the storeResultTool function. This function's parameter has the reviewedTextSchema schema, the schema for our expected response. The function_call.name = 'storeResultTool' configuration option forces the model send the response to the storeResultTool function.

We create a processing chain that combines the prompt and the model configured for structured output. This chain has an extra step compared to the OpenAI implementation: using the JsonOutputFunctionsParser to convert the JSON output string to an object:

  // Create a processing chain: prompt -> language model -> JSON output parser
  const chain = prompt.pipe(llm).pipe(new JsonOutputFunctionsParser());

Summary

Congrats on completing this tutorial! In the fourth part of the AI-Boosted Development series, I showed how to create a basic LLM chain using LangChain.js. We used prompt templates, got structured JSON output, and integrated with OpenAI and Ollama LLMs. In the next article, I will show how to generate a function that compares two strings character by character and returns the differences in an HTML string. It is going to be exciting, so make sure to subscribe!

👨‍💻About the author

My name is Gergely Szerovay, I worked as a data scientist and full-stack developer for many years, and I have been working as frontend tech lead, focusing on Angular-based frontend development. As part of my role, I'm constantly following how Angular and the frontend development scene in general are evolving.

Angular has been advancing very rapidly over the past few years, and in the past year, with the rise of generative AI, our software development workflows have also evolved rapidly. In order to closely follow the evolution of AI-assisted software development, I decided to start building AI tools in public, and publish my progress on AIBoosted.dev , Subscribe here 🚀

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular, and how to build AI apps with AI, Typescript, React and Angular!

In the introductory part of this series, I summarized the recent changes that enable us to prototype and develop AI apps in Typescript easily.

Haven’t read the first part? Here is what this project is all about: my goal in the coming months, and probably years, is to experiment with the new AI models and tools and show you everything I learn along the way. I'm going to “build in public” a lot and show you the important milestones of my journey. As a result, you’ll be able to apply this knowledge in your own practice.

In the second article, I showed you how to install the Jupyter Lab IDE and all the necessary tools for our rapid prototyping environment:

• Jupyter Lab web-based interactive development environment

• Deno Typescript/Javascript kernel for Jupyter notebooks, which enables us to create Jupyter Notebooks in Typescript

• Ollama for running LLMs locally

• Langchain, a framework for developing applications powered by language models

If you’ve followed the steps in the second article, now you have a working Jupyter Lab environment with Typescript support, and a local Ollama installation for running LLMs locally.

In this article, I'll explain how to use Jupyter Lab, and show you a basic coding workflow in it.

You can download my sample Notebook with all the examples.

Jupyter Lab basics

Jupyter Lab is an integrated development environment (IDE) for working with Jupyter notebooks, code, and data. Jupyter Notebooks contain live code, outputs, visualizations, and narrative text.

Jupyter Lab's user interface is similar to VSCode or JetBrains IDEs. It has two main parts: a "File browser", and a main work area with opened files:

You can open and edit your source files from the "File browser". The root directory of the "File browser" is the directory, where you started Jupyter Lab.

The button with the plus icon above the "File browser" is the "Launcher". It provides shortcuts to create new notebooks, text files, terminals, consoles, and other tools:

The left sidebar contains these tools:

• File Browser: Navigate and manage files

• Running Terminals and Kernels: Lists currently running terminals and kernels

• Extension Manager: Manage extensions to enhance the functionality of Jupyter Lab

• Command Palette: Quick access to commands, open it with Ctrl+Shift+C

In the "Command palette" you can see all Jupyter Lab commands and their shortcuts:

Coding Workflow in Jupyter Lab

Creating a New Notebook

Click the + icon in the left sidebar to open the "Launcher". Under "Notebook" select "Deno" to create a new notebook for TypeScript (or JavaScript). Save your notebook with Ctrl+S. Rename the file in the "File browser" by right clicking on it and selecting "Rename" (or press F2)

Writing and Executing Code

In the new notebook, you can write and execute TypeScript code within code cells. Each code cell lets you to enter and execute a snippet of code. For example, to display message, write:

console.log('Hello Deno!')

Execute the code by pressing Shift+Enter. The output will appear below the cell immediately:

Kernels

A kernel executes the code in Jupyter Notebooks. It maintains the state of variables, imports, and other runtime information between cell executions. Each notebook has its own kernel.

Restarting a Kernel

The notebook's kernel memory can get cluttered with variables from previous executions. Restarting clears this memory, providing a clean slate. Restarting also reloads updated modules.

You can restart the kernel from the "Kernel" menu.

Markdown Cells

Markdown cells add text and documentation to your notebook, making it more informative. To add a Markdown cell, click the + button in the toolbar to insert a new cell, then change the cell type to "Markdown" using the dropdown menu or by pressing Esc + M. To create a heading and formatted text, write:

### Outputs

You can write to the output cells using JavaScript's standard output functions, such as `console.log`

To render the Markdown, press Shift+Enter:

Importing Packages in Deno

In Deno, package import uses a URL-based syntax:

import { escape } from "https://deno.land/std/html/mod.ts";

Deno has a standard library available at https://deno.land/std. The line above imports the escape() function from the std library. To specify the version, use:

import { escape } from "https://deno.land/std@0.224.0/html/mod.ts";

Deno also has a repository for third-party modules at https://deno.land/x. To import the html() function, use:

import { html } from "https://deno.land/x/display/mod.ts";

Deno can import npm modules with the npm: prefix. For example to import zod:

import { z } from "npm:zod";

Writing in Output cells

You can output from a Code cell by:

• Using console.* functions

• With the html function (HTML output)

• With the md function (Markdown output)

Example:

Environment variables

In Deno or Node, we use environment variables for settings. For example, Langchain's OpenAI wrappers get the key from OPENAI_API_KEY. Set it in a .env file:

OPENAI_API_KEY=[insert your key here]

Load this file with:

import "https://deno.land/std@0.215.0/dotenv/load.ts";

Show the value with:

console.log(Deno.env.get("OPENAI_API_KEY"));

Importing local files

Deno supports local file imports. After changing an external file, restart the kernel to reload it:

import { f1 } from './1.ts';

f1();

Deno also supports importing JSON files:

import jsonData from "./data.json" with { type: "json" };
console.log(jsonData);

Summary

Congrats on completing this little tutorial! We've covered the basics of Jupyter Lab, so in future articles, we can focus on AI-related topics. In the next article, I'll explain how I built the "Text reviewer app" prototype. It’s going to be exciting, so make sure to subscribe!

👨‍💻About the author

My name is Gergely Szerovay, I worked as a data scientist and full-stack developer for many years, and I have been working as frontend tech lead, focusing on Angular-based frontend development. As part of my role, I'm constantly following how Angular and the frontend development scene in general are evolving.

Angular has been advancing very rapidly over the past few years, and in the past year, with the rise of generative AI, our software development workflows have also evolved rapidly. In order to closely follow the evolution of AI-assisted software development, I decided to start building AI tools in public, and publish my progress on AIBoosted.dev , Subscribe here 🚀

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular, and how to build AI apps with AI, Typescript, React and Angular!

Intro

This is the 2nd part of my article series describing my journey in AI-assisted development.

In the introductory part of this series, I summarized the recent changes that enable us to prototype and develop AI apps in Typescript easily.

Haven’t read the first part? Here is what this project is all about: my goal in the coming months, and probably years, is to experiment with the new AI models & tools and show you everything I learn along the way. I'm going to “build in public” a lot and show you the important milestones of my journey. As a result, you’ll be able to apply this knowledge in your own practice.

In this article, I show you how to install the Jupyter Lab IDE and all the necessary tools for our rapid prototyping environment. You’ll only need to set up this once, and I’ll explain everything step by step. After having this setup, you’ll be able to follow along with me and build all my future experiments. (So it’s worth the effort :) ).

For example, in the next parts of the article series, I'm going to explain you in more detail how I built the "Text reviewer app":

My workflow and tools

I use the following workflow for AI tool development:

• a Typescript- and Jupyter Lab-based AI tool prototyping environment for quickly prototyping AI tools

• I extend the code of the prototype, create a store from it. In React apps I use the Zustand React store, in Angular I use NgRx's SignalStore, in Jupyter Lab, I use Zustand Vanilla stores. These store solutions have a lot in common, so I can reuse the same selector, effect and updater code.

• I build an Angular or React app or smart component that uses the store in an Nx monorepo. I use the Shadcn UI in React apps, and the Shadcn-based spartan/ui in Angular apps, so I can use almost the same app architecture both in Angular and React.

These are the most important tools of my Typescript-based AI tool prototyping environment:

• Jupyter Lab web-based interactive development environment

• Deno Typescript/Javascript kernel for Jupyter notebooks, it enables us to create Jupyter Notebooks in Typescript

• Ollama for running LLMs locally

• Langchain, a framework for developing applications powered by language models

I'm going to also explain how to install and what are the most important commands of the following package managers:

• Chocolatey Windows software management solution, we use this for installing Python and Deno

• Package installer for Python (pip), we use this for installing the Python-based packages, such as Jupyter Lab, and we'll use this for installing other Python-based tools like the Chroma DB vector database

If you follow the steps of this article, you'll be able to run the prototype of the “Text reviewer app” in your local Jupyter Lab IDE (downloadable Jupyter notebook), and you’ll also be able to start creating your own app prototypes based on my examples:

Sidenote: what are the benefits of using Jupyter notebooks with Typescript for prototyping?

Initially, when I started doing my experiments, I created a simple Angular app, and I wrote all the experimental AI code in the main component's constructor, and showed the output on the console. I found that this approach worked well with simple experiments, when I have a clear plan on how I want to build something, and I don't want to experiment with many different models, prompts or agent networks. However, in case of more complex experiments, this simple approach has its limitations:

• The whole experimental code runs all at once, if I would like to split it up into multiple parts and run the parts separately, I need UI controls, or I have to comment/uncomment parts of the code. In Jupyter, I can split the code into multiple cells, and run all the cells, or some of the cells separately

• Package management: in Deno, this is automatic, I just write an import statement, and Deno downloads and stores the NPM or Deno package automatically in the background. There is no need for the package.json or node_modules directory. Once a specific version of a package is downloaded by Deno, we can use it from all the Jupyter notebooks

• We can simply create a copy of a notebook in Jupyter. If I experiment with a new AI tool, I can just clone my notebook and change for example the prompt or the model. Then I can run my notebooks in parallel, and compare the results side-by-side

• In Jupyter, if I need customized agents with RAG (Retrieval-Augmented Generation, we use this technique for optimizing the output of an LLM by extending its knowledge by additional information external to its training source), I can directly access the local files containing the additional knowledge. We can also do this in an Angular / React app, but it's more challenging, as we need some kind of a server to access the local files.

• The Typescript code we create with Jupyter/Deno is portable: we can use it in a frontend project, but it's also possible to use the code in the backend.I believe that for experimenting purposes, Jupyter and Deno are perfect, while in the prototyping phase, we should create an Angular or React app. These prototypes can effectively support a single user's or smaller team's work. However, when our goal is to turn the prototype into a real service, we need to move at least some parts of the code to the backend in order to keep the resources and costs under control (e.g. API access and fees).

• And finally, the biggest benefit of using Jupyter notebooks in my opinion: it is like having an interactive article, you have the code itself, the output of the code and the explanations (in Markdown) in one place (next to each other), so it is perfect for e.g. communicating ML / AI concepts to other developers.

Now let’s get started with building our rapid prototyping environment! Remember, you’ll only need to set this up once :).

Setup: Chocolatey

Installing Chocolatey CLI (Windows)

As I mentioned, Chocolatey is a software management solution for Windows, we'll use this for installing Python and Deno. We need Python for installing and running the Jupyter Lab IDE, and Deno provides the Typescript language support for Jupyter Lab.

If you use Linux, skip these steps, and jump to the installing Python and Deno “On Linux" section.

To install Chocolatey, execute the following command from an elevated Command Prompt (source):

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

This command downloads and runs the remote install1.ps script on your computer, so you should check its contents to ensure safety before running it.

Related article: Chocolatey docs: Installing Chocolatey CLI

The most important Chocolatey CLI commands

• choco list -localonly: list the locally installed packages

• choco install PackageName: installs a package (you can browse the available packages in the Community Package Repository)

• choco upgrade PackageName: upgrades a package

• choco uninstall PackageName: uninstalls a package

• choco outdated: list the locally installed packages that have a newer version

Setup: Installing Python and Deno

On Windows

In the elevated Command Prompt, run choco install python for installing Python. Then run the refreshenv command for refreshing the PATH and other environment variables. Now if you run python --version, it returns the version of Python.

Run python -m pip install -U pip for upgrading the Python package manager (pip).

Then install the Deno Typescript Kernel:

choco install deno

On Linux

On Linux, you can use your distribution's package manager for installing Python. Then run python -m pip install -U pip for upgrading the Python package manager (pip).

Then install the Deno Typescript Kernel and the Pnpm package manager:

curl -fsSL https://deno.land/install.sh | sh

You should check the contents of these remote script files to ensure safety before running them.

Related article:

• Deno installation

Creating a Python virtual environment (venv)

From this point on, the installation steps are very similar on both Windows and Linux, just use /home/YourUser/ instead of C:\Users\YourUser\ as your home directory.

A virtual environment contains a set of installed packages. I suggest creating a separate virtual environment for each Python-based project on your computer, so we create a new virtual environment for JupyterLab and Deno. You can create additional virtual environments later.

Open a Command Prompt (non-elevated), and create a new directory for the virtual environments: mkdir C:\Users\YourUser\venv, then create the new virtual environment with the following command: python -m venv C:\Users\YourUser\venv\jupyter-deno

We have to activate the virtual environment before we install packages into it with the C:\Users\YourUser\venv\jupyter-deno\Scripts\activate command. After we executed this script, the prompt changed to (jupyter-deno) C:\.

Related article: Python documentation: Creation of virtual environments

The most important Python package manager (pip) commands

• pip list: list the locally installed packages

• pip install PackageName: installs a package (you can browse the available packages in the Python Package Index)

• pip install --upgrade PackageName: upgrades a package

• pip uninstall PackageName: uninstalls a package

• pip list --outdated: list the locally installed packages that have a newer version

Setup: Installing JupyterLab with the Deno Kernel

Inside the activated environment, we install Jupyter Lab: pip install jupyterlab, then we add the Deno kernel to Jupyter with the deno jupyter --unstable --install command.

Hidden files are not visible in Jupyter Lab by default, so for example we can't see the .env files in Jupyter Lab. We use the .env files e.g. for storing the key for OpenAI's API. To display these files in Jupyter Lab's file manager, we have to generate a new Jupyter config file with the following commands:

mkdir C:\Users\YourUser\.jupyter
cd C:\Users\YourUser\.jupyter
jupyter server --generate-config

The last command generates a C:\Users\YourUser\.jupyter\jupyter_server_config.py file. Open this file and set ContentsManager.allow_hidden = True. Restart Jupyter Lab, and now you can show or hide hidden files in Jupyter Lab using the Show Hidden Files menu item in the View menu.

As the last step of the installation process, create a directory for the Jupyter notebooks and start Jupyter Lab:

mkdir C:\Users\YourUser\jupyter
cd C:\Users\YourUser\jupyter
jupyter lab

Related articles:

• Bringing Modern JavaScript to the Jupyter Notebook

• JupyterLab docs: Displaying Hidden files

Setup: Installing and using Ollama

Installing Ollama and a model

As I mentioned before, I use Ollama for running local LLM models.

You can download Ollama for Windows here and find the model library here. After installing Ollama, I suggest you to download the codellama:7b-code model, it's great for testing purposes: ollama pull codellama:7b-code. This is a small model, requiring about 4 GB of RAM. I use this model on my older laptop that has only 16 GB RAM and a dual core CPU, and it gives responses with an acceptable speed. I use this local model in the prototype of the “Text reviewer app”, too.

The most important Ollama commands:

• ollama list lists the downloaded models

• ollama pull ModelName:version downloads an LLM model

• ollama serve runs the Ollama server in the background

Try out our first AI prototype with a local model

If you haven't started Jupyter Lab yet, activate your virtual env and start Jupyter Lab inside it with the jupyter lab command. You can open the UI in your browser: http://localhost:8888/. Start Ollama with ollama serve.

Download the notebook containing the app's prototype into the C:\Users\YourUser\jupyter directory. Select the downloaded notebook from JupyterLab's file browser (left panel on the screen), then select the "Clear Outputs of All Cells" from the "Edit" menu to remove all the saved outputs from the cell, then click on the "Run all cells" menu item from the "Run" menu. After some processing, the results of the comparison should be visible above the last cell:

What’s next

In the following parts of my article series, I'm going to show you:

• How to use the Jupyter Lab IDE and the Deno Javascript/Typescript runtime that executes the Typescript code in a notebook

• How the "Text reviewer app" prototype (screenshot above) works

• The basics of LLMs and LangChain.js. (LangChain enables us to easily switch between the different LLM models and provider APIs, like the OpenAI platform API or the local Ollama API.)

• How to create the state and store of the "Text reviewer app" based on the prototype, and using AI for code generation, and

• How to build a React and an Angular app that uses the above mentioned store

Summary

Congrats on completing this little tutorial! I know that it wasn’t the most exciting process you have ever followed along. But trust me, now you have a powerful prototyping environment for experimenting with building AI tools. It’s like getting all the ingredients needed for a great meal (and building a kitchen at the same time :D ). In the following articles, we are going to start cooking, so stay tuned for the fun part!

In the next two articles, I'm going to explain how to use the JupyterLab IDE and the Deno Javascript / Typescript runtime, and I’m going to show you in detail how the “Text reviewer app” prototype works.

👨‍💻About the author

My name is Gergely Szerovay, I worked as a data scientist and full-stack developer for many years, and I have been working as frontend tech lead, focusing on Angular-based frontend development. As part of my role, I'm constantly following how Angular and the frontend development scene in general is evolving.

Angular has advancing very rapidly over the past few years, and in the past year, with the rise of generative AI, our software development workflows have also evolved rapidly. In order to closely follow the evolution of AI-assisted software development, I decided to start building AI tools in public, and publish my progress on AIBoosted.dev , Subscribe here 🚀

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular, and how to build AI apps with AI, Typescript, React and Angular!

My background and why you should care

I've been a developer for more than 30 years now, and I've never been so excited about the newest technological advancements. We live in a day and age that opens up so many possibilities that I could have never imagined before. I'm talking about developing AI tools.

Let's start with a simple example. Are there any non-native speaker readers here? If yes, this scenario might be familiar to you: let’s say you write an article, and ask an LLM (large language models, for example ChatGPT) if your text is grammatically correct or not.

The LLM answers with an updated version of our text. Then, if we ask it to list out the changes compared to the original text, it returns wrong or incomplete results (in many cases). These models can generate textual outputs or improve a given text's quality, but they're not so capable of performing algorithmic tasks, since they merely process our prompts and try to predict what answer we’d expect. They do not "think", they have no human-like logical capabilities. In order to solve this issue, I created a small AI tool to perform this comparison task in two simple steps:

• In the first step, the user can enter a text, and then the tool asks an LLM model to verify and improve it, and

• In the second step, the tool compares the LLM's result with the original text, and visualizes the changes.

Nowadays, I can develop apps like this in Typescript easily, as the barrier is lower than ever before, much lower. We only need Typescript development skills for developing AI-tool prototypes, additionally, if you are an experienced frontend developer, you can easily convert your prototypes into real applications with a user interface. This is the prototype of the Text reviewer app in the Jupyter Lab IDE (downloadable Jupyter notebook):

Never heard of Jupyter Lab? No problem, let me explain.

Jupyter Lab applies so-called notebooks, the screenshot above contains the notebook of the Text reviewer app’s code. A Jupyter Notebook contains Typescript code cells and Markdown cells. We can execute Typescript code cells instantly by pressing Control+Enter, there is no building time. After the execution is completed, Jupyter Lab shows us the output, as you can see on the screenshot.

Based on this prototype, we can of course build a real app. I built both an Angular and a React app, this is how they look like:

Next to showing you a quick example, I do believe that this little app is actually useful: as a non-native speaker, my goal is to constantly improve my language skills. And this was just a very simple little app I built in some hours. I hope now you can better see the potential of building your own AI tools. The possibilities are endless.

Follow along my journey, let’s learn together

My goal with this article series is to show you how you can do similar experiments and apps. I'm going to show you all the tools and the mindset that's needed to build AI tools on your own.

In the next parts of the article series, I'm going to explain you how I built the Text reviewer app in more details.

Some of the next topics:

• How to install the Jupyter Lab IDE with all the required tools for quick AI prototyping in Typescript

• How to use the Jupyter Lab IDE and the Deno Javascript/Typescript runtime that executes the Typescript code in a notebook

• The basics of LLMs and LangChain.js

• How the Text reviewer app prototype works

• How to create the state and store of the Text reviewer app based on the prototype, and using AI for code generation, and

• How to build a React and an Angular app that uses the above mentioned store

After discussing these topics, I'm going to continue the series with building new, more complex AI apps. I'm also going to research and share AI-assisted software development workflows, and show you how to build custom AI tools that support these workflows. My goal in the coming months (probably in years) is to experiment with the new AI models and tools and document and show you everything I learn along the way. I'm going to build in public a lot, you should follow me on AIBoosted.dev or on my social media accounts (X or LinkedIn).

What changes have made it easier to build AI app prototypes quickly in TypeScript?

If you are curious about the tech background (or in other words, here is the answer to the “Why now?” question), these are the recent advancements that have made AI-boosted development so much easier.

The most popular programming language for data scientists has traditionally been Python, so many AI and ML tools had Python integration only. Therefore, if someone wanted to try out or learn AI or ML tools, first they had to learn Python. Today, this has changed significantly as more and more tools contain Javascript and Typescript support.

One of these tools is LangChain.js. LangChain is a framework for developing applications powered by language models. In 2023, they introduced the support of multiple JS environments, so now we can use LangChain.js in the browsers and with the Deno Javascript runtime.

Another one of these tools is Jupyter Lab. Jupyter Lab is an interactive development environment, and as of 2023, it supports Typescript and Javascript Notebooks with the help of Deno. It means that now we can use Jupyter Notebooks to speed up our software prototyping and development processes. Don’t worry, I’m going to explain how in the next article. At this point, you must believe me :)

So we can create Typescript prototypes in Jupyter Lab, for example, if we would like to create an AI tool, we don't have to create a full-fledged React or Angular application first. We can design and test the AI tool in Jupyter Lab, then move its source code into our React or Angular application.

What are the benefits of joining me on this journey?

• Along the way, we can closely follow the evolution of LLMs and the development workflows, and gain experience with using and building AI tools. This will give you a competitive advantage.

• AI-boosted development: with custom AI tools, you can create workflows that help you perform your daily development tasks more efficiently

The tech stack

In the second part of the series, we are going to get a bit more technical: we are going to install a Typescript-based AI tool prototyping environment. These are the most important parts of it:

• Jupyter Lab web-based interactive development environment

• Deno Typescript/Javascript kernel for Jupyter notebooks, it enables us to create Jupyter Notebooks in Typescript

• Ollama for running LLMs locally

• Langchain, a framework for developing applications powered by language models

I’m also going to explain how to install these package managers and what are the most important commands for them:

• Chocolatey Windows software management solution, we use this for installing Python and Deno

• Package installer for Python (pip), we use this for installing the Python-based packages, such as Jupyter Lab, and we're going to use this for installing other Python-based tools like the Chroma DB vector database

• Pnpm for install Javascript/Typescript packages, like LangChain.js

Summary

So welcome to the AI-boosted Development article series, dear reader! I hope you enjoyed this first chapter! I'm going to show you the important milestones of my journey, and along the way I'm going to teach you how you can apply this knowledge in your own practice.

👨‍💻 About the author

My name is Gergely Szerovay, I worked as a data scientist and full-stack developer for many years, and I have been working as frontend tech lead for three years, focusing on Angular based frontend development. As part of my role, I'm constantly following how Angular and the frontend development scene in general is evolving.

Angular has evolved very rapidly over the past few years, and in the past year, with the rise of generative AI, our software development workflows have also evolved rapidly. In order to closely follow the evolution of AI-assisted software development, I decided to start building AI tools in public, and publish my progress on AIBoosted.dev , Subscribe here 🚀

Follow me on Substack (Angular Addicts), Substack (AIBoosted.dev), Medium, Dev.to, X or LinkedIn to learn more about Angular, and how to build AI apps with AI, Typescript, React and Angular!