Build a Spotify Clone with Antigravity

Ship a queue feature for a Spotify clone using Google Antigravity's AI agent.

Introduction

30 Second Summary

Imagine being able to describe a feature you want and having an AI build it for you. No syntax memorization, no Stack Overflow rabbit holes. Just you directing an intelligent agent that writes, runs, and fixes code on your behalf.

In this project, you will use Google Antigravity to build a queue feature for a Spotify clone web app called NextSound. You will direct an AI agent to understand the codebase, plan the feature, and implement it without writing a single line of code yourself.

What You'll Build

A locally running Spotify clone with a fully functional queue sidebar, built entirely through AI agent collaboration in Google Antigravity.

By the end of this project, you'll have:

  • A working Google Antigravity setup connected to your Google account.
  • A complete queue feature (add, reorder, remove songs) built entirely by an AI agent.
  • Experience iterating on bugs using error messages and screenshots as feedback for the agent.
  • Secret Mission: Create an AGENTS.md file that teaches the agent your project's conventions and improves its output quality.

Are there any prerequisites?

None. This guide walks you through setting up everything from scratch, including Google Antigravity, Git, and Node.js. All you need is a Mac and a Google account.

Install Google Antigravity and Git

To build the NextSound queue feature, you need three tools installed on your machine.

In this step, you'll install Google Antigravity (the AI-powered IDE where you'll talk to the agent), Git (for downloading the project code), and Node.js (for running the web app locally).

In this step, get ready to:
  • Install and set up Google Antigravity.
  • Install Git on your Mac.
  • Install Node.js to run the web app.
Download and install Google Antigravity

Antigravity is an agent-first IDE built on VS Code. You'll use its AI agent to build the entire queue feature through conversation.

  • Open your browser and go to antigravity.google/download.
  • Under the MacOS section, click Download for Apple Silicon or Download for Intel depending on your Mac's chip.

Which chip do I have?

Click the Apple menu in the top left of your screen, then About This Mac. If you see "Apple M1" or "Apple M2" (or higher), choose Apple Silicon. If you see "Intel", choose Intel.

  • Open the downloaded .dmg file.
  • Drag the Antigravity icon into the Applications folder.
  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Antigravity and press Enter to open it.

When Antigravity launches for the first time, it opens a setup wizard.

  • Sign in with your Google account when prompted.
  • The wizard will ask if you want to import settings from VS Code or Cursor. If you don't have either installed, click Skip.
  • Choose a theme you like (you can change this later).
  • Accept the defaults for keybindings.

You should see the Antigravity Editor open with a welcome screen. The interface looks similar to VS Code with a file explorer on the left and an editor area in the center.

Is Antigravity free?

Yes. Antigravity is free during the public preview. You don't need a credit card or API key. Your Google account is all you need to access the AI agent.

Seeing a security warning on macOS?

macOS may block apps from unidentified developers. If you see a warning, go to System Settings then Privacy & Security, scroll down, and click Open Anyway next to the Antigravity message.

help me open Antigravity on my Mac

Install Git

Git is the version control tool you'll use to download the NextSound project code. Many Macs already have Git installed.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal and press Enter to open it.
  • Check if Git is already installed by running this command:
git --version

✔️ I see a version number

You're all set. Git is ready to use. Move on to the next substep.

ⓧ Command not found

Git isn't installed yet. Install it by running this command:

xcode-select --install

A dialog will pop up asking you to install the Xcode Command Line Tools. Click Install and wait for it to finish. This may take a few minutes.

  • Once the install finishes, verify Git is working by running:
git --version

You should see a version number like git version 2.54.0 (your exact number may differ).

Still seeing command not found?

Make sure the Xcode Command Line Tools installation completed successfully. If it failed, try running xcode-select --install again. A stable internet connection is required for the download.

help me install Git on my Mac

Install Node.js

Node.js runs the NextSound web app on your machine. This project requires version 24 or higher.

  • Check if Node.js is already installed by running this command in your Terminal:
node --version

✔️ I see version 24 or higher

Your Node.js version starts with v24 (for example, v24.15.0). You're good to go.

ⓧ I see an older version

You have Node.js installed, but it's an older version. You need v24 or higher for this project.

  • Open your browser and go to nodejs.org/en/download.
  • Download the macOS .pkg installer for the LTS version (v24).
  • Open the downloaded file and follow the installer prompts. Click Continue through each step, then Install.
  • Close and reopen your Terminal, then run node --version again to confirm it now shows v24.

Why do I need to reopen Terminal?

Terminal loads your system paths when it starts. After installing a new version of Node.js, the old Terminal session still points to the previous version. A fresh Terminal window picks up the new installation.

ⓧ Command not found

Node.js isn't installed yet. Download it from the official website.

  • Open your browser and go to nodejs.org/en/download.
  • Download the macOS .pkg installer for the LTS version (v24).
  • Open the downloaded file and follow the installer prompts. Click Continue through each step, then Install.
  • Close and reopen your Terminal, then verify with:
node --version

You should see v24.15.0 or similar.

Node version not showing up?

Make sure you closed and reopened Terminal after the install. If it still doesn't work, try opening a brand new Terminal window from Spotlight search.

help me install Node.js on my Mac

  • Confirm that npm (Node's package manager) was installed alongside Node.js by running:
npm --version

You should see a version number printed. This means both Node.js and npm are ready.

npm command not found?

npm is bundled with Node.js. If node --version works but npm --version does not, try reinstalling Node.js from the .pkg installer. Make sure you complete all steps in the installer without skipping any.

help me fix npm not found

Your tools are installed and ready. Next up, you'll clone the NextSound project into Antigravity and explore its codebase with the AI agent.

Clone the NextSound Repository

Your tools are installed and ready to go. Now it's time to get the actual project onto your machine.

The NextSound app is a Spotify clone that already has a working music player. You'll clone it from GitHub and then use Antigravity's AI agent to understand what's inside before making any changes.

In this step, get ready to:
  • Clone the NextSound repository to your Desktop.
  • Open the project in Antigravity and explore the file structure.
  • Use the Agent Sidebar to understand the codebase.
Clone the repository using the Command Palette

Antigravity has a built-in Git clone feature that works just like VS Code's. You'll use the Command Palette to tell Antigravity which repository to download.

  • Open Google Antigravity by pressing Cmd+Space to open your search bar, then typing Antigravity and pressing Enter.
  • Open the Command Palette by pressing Cmd+Shift+P.
  • Type Git: Clone and select the option that appears.
  • Paste the following URL into the repository URL field:
https://github.com/itsnextwork/nextsound.git
  • Antigravity will ask you to choose a folder to clone into. Select your Desktop.
  • When prompted to open the cloned repository, click Open.

What just happened?

Antigravity used git clone behind the scenes to download the entire NextSound project from GitHub onto your Desktop. The project now lives in a folder called nextsound.

You should now see the project's files in the left sidebar (the file explorer). This is the same sidebar layout you'd see in VS Code.

Clone failed or you don't see the project?

Make sure you're connected to the internet. If the URL shows an error, double-check you copied it exactly as shown above (no extra spaces).

If Antigravity didn't ask where to save the clone, try again from the Command Palette. Make sure you selected your Desktop folder, not a subfolder.

help me troubleshoot cloning a Git repository in Antigravity

Explore the codebase with the Agent Sidebar

Before building anything new, it's important to understand what already exists. Instead of reading every file yourself, you can ask Antigravity's AI agent to summarize the project for you.

  • Look at the left sidebar (the file explorer) to see the project's folders and files.
  • Open the Agent Sidebar by pressing Cmd+L. A chat panel appears on the right side of the editor.
  • Type the following prompt into the chat and press Enter:
Explain this web app's file organization and purpose in 4 sentences or fewer.

What is the Agent Sidebar?

The Agent Sidebar is a built-in AI chat panel that lives on the right side of Antigravity's editor. You can ask it questions about your code, request changes, or instruct it to run commands.

It understands the files in your project automatically. You can also use @ mentions to point the agent at specific files or folders for more focused answers.

Read the agent's response and check context usage

The agent will respond with a brief summary of the project structure. Take a moment to read through it.

  • Read the agent's response. You should learn what the app does, what framework it uses, and how the files are organized.
  • Look below the chat input for the context usage indicator. This shows how much of the agent's context window your conversation has used so far.

What is a context window?

A context window is the total amount of information an AI model can "see" at once during a conversation. It includes your messages, the agent's responses, and any file content the agent reads.

The indicator helps you know when you're running low on space. If a conversation gets too long, the agent may forget earlier details. Starting a new chat resets the window.

You now have a solid understanding of the NextSound codebase without reading a single file manually. Next up, you'll install the project's dependencies and see the app running in your browser.

Install Dependencies and Run the App

You explored the NextSound codebase with Antigravity's agent and now have a clear picture of how the project is organized.

Before you can see the app in action, you need to install its packages and start a local server. You will use the Agent Sidebar to handle both tasks without touching the terminal yourself.

In this step, get ready to:
  • Install the project dependencies using the AI agent.
  • Start the development server.
  • Verify the app loads in your browser.
Install the project dependencies

The NextSound project relies on packages listed in its package.json file. These packages need to be downloaded before the app can run.

  • In the Agent Sidebar (which should still be open from the previous step), type this prompt and press Enter:
Install the project dependencies

What is the agent doing?

The agent runs npm install in the integrated terminal. This command downloads all the packages listed in package.json into a node_modules folder.

You did not need to open a terminal or type the command yourself. The agent figured out the right command and executed it for you.

  • Look at the file explorer in the left sidebar. You should see a node_modules folder appear in the file tree.

Don't see node_modules?

  • Try clicking the refresh icon at the top of the file explorer, or collapse and re-expand the nextsound folder.
  • If the agent reported an error, copy the error text and paste it back into the chat asking it to fix the issue.
  • Help me troubleshoot why npm install failed in my Antigravity Agent Sidebar.
Start the development server

With dependencies installed, you can start the app locally. The development server watches your files and serves the app to your browser at a local URL.

  • In the same Agent Sidebar chat, type this prompt and press Enter:
Run the development server

What happens next?

The agent runs npm run dev in the terminal. This starts a Vite development server. You should see a local URL appear in the terminal output (typically http://localhost:5173).

  • Hold Cmd and click the URL in the terminal (e.g. http://localhost:5173) to open the app in your browser.

The NextSound Spotify clone should load in Google Chrome. You should see a music app interface with song tiles and a player at the bottom.

Seeing a blank page or error?

  • Make sure the terminal still shows the server running. If it stopped, prompt the agent again with "Run the development server" in a new chat.
  • Check that you are opening the correct URL. The terminal output shows the exact address.
  • If the browser shows errors in the console, copy them into a new Antigravity chat and ask the agent to diagnose the problem.
  • Help me figure out why my NextSound app isn't loading in the browser.

Your NextSound app is live and running locally. Next up, you will plan and build a brand new queue feature using the agent to do all the coding.

Plan and Build the Queue Feature

Your NextSound app is running, but it is missing a key feature every music player needs: a queue. Without one, users can only play whatever song they click on. There is no way to line up tracks for later.

In this step, you will direct Antigravity's AI agent to plan and build a complete queue feature. You will describe exactly what you want, review the agent's proposed approach, then give it the green light to execute.

In this step, get ready to:
  • Prompt the agent with detailed queue feature requirements.
  • Review the agent's plan for red flags before any code changes.
  • Execute the plan and verify the queue feature works in your browser.
Start a new chat and describe the queue feature

The agent's context window is the amount of information it can hold in one conversation. Starting a fresh chat clears the old context so the agent can focus entirely on your new request.

  • Open the Agent Sidebar by pressing Cmd+L.
  • Click the New Chat button at the top of the sidebar to start a fresh conversation.

Why start a new chat?

Your previous chat was about installing dependencies and running the server. That context is no longer relevant. A fresh chat gives the agent maximum room to focus on your feature request.

The quality of what the agent builds depends on how clearly you describe what you want. A vague prompt produces vague results. A detailed prompt with specific requirements produces exactly what you need.

  • Copy and paste this prompt into the Agent Sidebar chat:
Plan a queue feature for this music app. Do NOT edit any files yet - just explain your plan.

Requirements:
- An "Add to Queue" button on each song tile
- A slide-in panel from the right side showing the queue
- The currently playing song shown prominently at the top of the queue
- The ability to reorder songs in the queue by dragging
- The ability to remove songs from the queue
- Only use packages already in package.json (do not install new ones)

What makes this prompt effective?

This prompt includes three things that improve agent output. First, it sets a boundary (plan only, do not edit files). Second, it lists specific UI requirements. Third, it includes a constraint (no new packages).

The "Do NOT edit any files yet" instruction is critical. Without it, the agent would immediately start making changes. Asking it to plan first gives you a chance to review before anything is modified.

  • Press Enter to send the prompt.
  • Wait for the agent to finish its response. You should see a structured plan listing which files it intends to create or modify, and how it will implement each requirement.
Review the agent's plan for red flags

Before letting the agent edit your code, you need to check its plan makes sense. This is agent-first development in action: you are the decision-maker, and the agent is the builder.

  • Read through the agent's plan carefully.
  • Check for these red flags:

Give feedback before executing

If something in the plan looks off, type your feedback directly in the chat. For example: "Don't replace the existing player component, add the queue alongside it." The agent will revise its plan based on your input.

Execute the plan

Once you are satisfied the plan covers all your requirements without red flags, it is time to let the agent build.

  • Type this in the Agent Sidebar chat and press Enter:
let's go!

The agent switches to execution mode. You will see it editing files, creating new components, and wiring everything together in real time.

  • Watch the agent work. It will open files in the editor, make changes, and may run terminal commands.
  • When the agent asks you to accept changes, click Accept to confirm each set of edits.
  • Wait for the agent to report that it has finished implementing the feature.

What is happening behind the scenes?

The agent reads your project files, decides which ones to modify, writes new code, and tests that its changes fit together. It is doing in seconds what might take a developer an hour or more to build from scratch.

  • Once the agent finishes, switch to Google Chrome and check your app at http://localhost:5173.
  • Look for the queue feature in the interface. You should see an "Add to Queue" button on song tiles and a way to open the queue panel.

Don't see any changes in the browser?

If the app looks the same as before, try a hard refresh with Cmd+Shift+R. If the page shows an error, that is okay. You will fix issues in the next step.

If the agent's execution seemed to stop midway, go back to the Agent Sidebar and type "continue" to resume.

Help me troubleshoot why the queue feature isn't showing up in my browser after the agent finished building it.

Your queue feature is live. In the next step, you will learn how to iterate on bugs and visual issues using error messages and screenshots as feedback to the agent.

Iterate and Fix Issues

The AI agent just built your queue feature from scratch. AI-generated code rarely works perfectly on the first try, though.

In this step, you'll learn the core iteration loop of agent-first development: feed the agent error messages and screenshots, and let it fix its own work. This is the skill that separates someone who uses AI tools from someone who ships with them.

In this step, get ready to:
  • Check for terminal and browser console errors.
  • Fix visual bugs by sharing screenshots with the agent.
  • Verify the queue feature works end-to-end.
Check for errors in the terminal and browser console

When AI agents write code, they sometimes produce syntax errors, missing imports, or broken references. These show up as error messages in two places: the integrated terminal in Antigravity, and the browser's developer console.

  • Look at the integrated terminal in Antigravity (the panel at the bottom of the screen). Check if any red error messages appeared after the agent made its changes.
  • Switch to Google Chrome where your app is running.
  • Open the browser's developer console by pressing Cmd+Option+J.
  • Look for any red error messages in the Console tab.

✔️ No errors in terminal or console

Nice. Your agent wrote clean code on the first pass. Skip ahead to checking for visual bugs below.

ⓧ I see red error messages

This is normal. The agent needs to see the error to fix it.

  • Select and copy the full error message from the terminal or browser console.
  • Switch back to Antigravity and open a new chat in the Agent Sidebar with Cmd+L.
  • Paste the following prompt along with the error message you copied:
I'm getting these errors in my project. Can you explain why and fix them?

[paste your error message here]
  • The agent will analyze the error, explain what went wrong, and edit the relevant files to fix it.
  • Accept the changes when prompted.
  • Check the terminal and browser console again. Repeat this process if new errors appear.

Include the full error

Copy the entire error message, not just the first line. Stack traces and file paths give the agent the context it needs to pinpoint the problem.

Fix visual bugs with screenshots

Sometimes code runs without errors but produces visual problems. The queue panel might have wrong colors, overlapping text, or elements that don't match the app's dark theme.

  • In Google Chrome, look at the queue feature carefully. Check for wrong colors, overlapping elements, unreadable text, or anything that looks off.

✔️ Everything looks good visually

Great. Your agent nailed the styling. Move on to the final verification below.

ⓧ I see visual issues

Screenshots are the fastest way to communicate visual bugs to an AI agent. The agent can see exactly what you see and fix the styling.

  • Take a screenshot of the visual issue by pressing Cmd+Shift+4 and dragging to select the problem area. The screenshot saves to your Desktop.
  • Switch back to Antigravity and open a new chat in the Agent Sidebar with Cmd+L.
  • Drag your screenshot into the chat input area to attach it.
  • Type a description of what is wrong and what it should look like instead. For example:
The queue panel text is white on a light background, making it unreadable. It should use light text on a dark background to match the rest of the app's theme.
  • The agent will analyze the screenshot, identify the CSS or styling issue, and make corrections.
  • Accept the changes when prompted, then refresh your browser to see the fix.
  • Repeat this process for any other visual issues you spot.

Why start a new chat for each issue?

Each new chat resets the agent's context window. A fresh context means the agent reads the current state of your files from scratch, instead of relying on its memory of what it changed before.

This avoids confusion when previous fixes have already altered the code.

Verify the queue feature works end-to-end

Now that errors and visual bugs are resolved, it is time to confirm the entire queue feature works as expected.

  • In Google Chrome, find the Add to Queue button on any song tile and click it.
  • Confirm the queue sidebar slides in from the right side of the screen.
  • Add 2-3 more songs to the queue.
  • Verify the currently playing song is displayed prominently at the top of the queue.
  • Try reordering a song by dragging it to a different position in the queue.
  • Remove a song from the queue and confirm it disappears.

Something still not working?

If any of the above checks fail, open a new Agent Sidebar chat (Cmd+L) and describe exactly what you expected versus what happened. The more specific your description, the better the agent's fix will be.

For example: "When I click Add to Queue, nothing happens. The button should add the song to the queue panel on the right."

Help me debug my queue feature in Antigravity

Once all checks pass, your queue feature is complete. You should see a fully functional queue sidebar with songs listed, the current track highlighted, and working reorder and remove controls.

You just shipped a full feature without writing a single line of code by hand. The iteration loop you practiced (error messages, screenshots, clear descriptions) is how professional developers work with AI agents every day. Next up, you'll learn how to make the agent even smarter by giving it permanent project rules.

Secret mission

Create an AGENTS.md File

Every time you start a new chat in Antigravity, the agent starts fresh. It forgets your preferences, your coding standards, and the mistakes you told it to avoid. What if there was a way to teach the agent your rules once and have it follow them automatically every single session?

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • Running development server (local, free).
  • Cloned nextsound repository on your Desktop.

Keep everything running

No action needed. Choose this if you're still actively building or plan to continue experimenting with Antigravity and the queue feature.

  • The dev server runs until you close the terminal window.
  • Restart anytime by opening the nextsound folder in Antigravity and running npm run dev in the integrated terminal.
  • Google Antigravity, Git, and Node.js remain installed on your machine for future projects.

Pause - I'll come back to this later

Shut down running processes to free up memory. Your project files stay on your machine so you can pick up where you left off.

  • In the Antigravity terminal where the dev server is running, press Ctrl+C to stop the server.
  • Close Antigravity.
  • Your nextsound folder and all your changes (including the queue feature and AGENTS.md) remain on your Desktop.

Delete - I don't want to use this again

Remove all project resources and start fresh. This deletes everything you built in this project.

  • In the Antigravity terminal where the dev server is running, press Ctrl+C to stop the server.
  • Close Antigravity.
  • Delete the nextsound folder from your Desktop by running this command in Terminal:
rm -rf ~/Desktop/nextsound

Google Antigravity, Git, and Node.js remain installed on your machine. These are general-purpose development tools useful for future projects.

That's a Wrap!

That's a Wrap!

You just shipped a feature using agent-first development. No code written by hand.

You've learned how to:

  • Used Google Antigravity's Agent Sidebar to explore and understand an unfamiliar codebase.
  • Built a complete queue feature (add, reorder, remove songs) through AI agent collaboration.
  • Iterated on bugs using error messages and screenshots as feedback to the agent.
  • Created an AGENTS.md file that teaches the agent your project's rules and conventions.

Ready to quiz yourself?