AI DevelopmentLast Updated Nov 18, 202616 min read

Getting started with Google Antigravity CLI and CircleCI

Roger Winter

Content Marketing Manager

AI coding assistants like Google Antigravity CLI are changing how developers write code. They can generate entire functions, debug tricky issues, and help you move faster than ever before. But with that speed comes a new challenge: how do you make sure AI-generated code actually works?

AI assistants are powerful, but they’re not perfect. They can introduce subtle bugs, miss edge cases, or generate code that breaks existing functionality. That’s where CI (continuous integration) comes in. CI automatically runs your tests and checks every time you push code, catching problems before they reach production. When you’re working with AI-generated code, this automated verification is essential.

The good news is that setting up CI takes just a few minutes, and once it’s running, you get an extra layer of confidence every time you accept an AI suggestion.

This tutorial will walk you through the complete setup: getting Antigravity CLI as your AI coding assistant, setting up CircleCI as your safety net, and then connecting the two so you can validate configs, trigger pipelines, diagnose failures, and analyze test results. All without leaving your terminal.

Prerequisites

Before we dive in, make sure you have the following ready:

  • A CircleCI account (free tier works great)
  • A GitHub account
  • A Google account to sign in to Antigravity CLI (a personal account works on the free plan)
  • The CircleCI CLI, version 1.15 or newer (installation is covered below)
  • Node.js 22 or newer, if you want Antigravity to run the demo project’s tests on your machine (optional)

Meet Google Antigravity CLI

Antigravity CLI start screen in the dataforge-demo folder, showing the CLI version, the Gemini 3.8 Flash model, and the prompt box.

Antigravity CLI (agy) is Google’s terminal-first AI agent, and it runs on Google’s Gemini models. It’s built for developers who prefer working from the command line and want a lightweight, terminal-first experience without the overhead of a full editor.

Note: If you used Gemini CLI before, Antigravity CLI is its successor for individual developers. Since June 18, 2026, Gemini CLI no longer works with a free Google sign-in and needs paid Gemini API or Gemini Code Assist access. If you have that access and want to stay on Gemini CLI, you can add the same CircleCI server described below with gemini mcp add --scope user circleci-cli circleci mcp start.

What makes it particularly useful is its support for MCP (Model Context Protocol), which lets you extend its capabilities with custom tools and integrations. It can read and edit files, run shell commands, search the web for real-time information, and—as we’ll see in this tutorial—interact with external services like CircleCI.

To install it on macOS or Linux, run Google’s install script:

curl -fsSL https://antigravity.google/cli/install.sh | bash

On Windows, run this in PowerShell:

irm https://antigravity.google/cli/install.ps1 | iex

The installer puts the agy command in ~/.local/bin (%LOCALAPPDATA%\agy\bin on Windows) and adds it to your PATH. Open a new terminal window so the change takes effect, then check the install with agy --version.

Once installed, just run agy in your terminal to get started. The first time you run it, you’ll pick a color scheme, confirm that you trust the folder you’re in, and sign in with your Google account in the browser. Free accounts get a weekly usage quota for Gemini models. You can type /model to switch models and /usage to see how much of your quota you’ve used.

Antigravity starts in Auto mode, which approves file edits and safe commands on its own and asks before anything riskier. Press Shift+Tab to switch modes if you’d rather approve every change yourself.

Why you need CI with your AI coding assistant

AI coding assistants can write code impressively fast, but they don’t have full context about your project’s requirements, existing test coverage, or production constraints. This means AI-generated code should always be verified by automated tests before it ships.

Here’s what can go wrong without CI in the loop:

  • Silent breakages: AI might refactor a function in a way that breaks callers elsewhere in your codebase. Without tests running automatically, you won’t know until something fails in production.
  • Security oversights: AI models can generate code with vulnerabilities—SQL injection, improper input validation, exposed secrets. CI pipelines with security scanning catch these before they become problems.
  • Dependency conflicts: AI suggestions might introduce or update dependencies in ways that conflict with your existing stack. CI ensures your full application still builds and runs.
  • Test regressions: Even well-intentioned changes can cause existing tests to fail. CI runs your entire test suite on every push, so you know immediately if something broke.

Think of CI as your automated code reviewer that never sleeps, never gets tired, and checks every single change. When you’re moving fast with AI assistance, that safety net becomes even more valuable.

The workflow is simple: write code with AI help, push your changes, and let CI verify everything works. If something breaks, you find out in minutes instead of days.

Getting started with CircleCI

Setting up CircleCI takes just a few minutes, and you can do all of it from your terminal with the CircleCI CLI. If you don’t have a CircleCI account yet, sign up for free. You can sign up with your GitHub account for faster setup.

Install the CircleCI CLI

Install the CLI with your platform’s package manager:

# macOS or Linux (Homebrew)
brew install circleci

# Windows
winget install --id CircleCI.CLI

For other install options, see the CircleCI CLI install page. If you still have the legacy CLI (version 0.1.x), uninstall it first.

Then log in:

circleci auth login

This opens an Authorize CircleCI CLI? page in your browser. Under Access level, select Admin, then click Allow. The default, Read, isn’t enough for the CLI to set up your project or start pipelines.

Using the demo repository

If you want to follow along with a project that already has CircleCI configured, you can fork our demonstration repository. It’s a small Node.js data-processing app with a test suite, and its main branch has a deliberate bug in the phone number validator, so your first build will fail. That’s on purpose: you’ll ask Antigravity to diagnose and fix it later.

  1. Head over to the demo repo and click the Fork button
  2. Clone your fork and change into its folder:

    git clone https://github.com/<your-username>/dataforge-demo.git
    cd dataforge-demo
    
  3. Run circleci onboard --scan. The repository already has a .circleci/config.yml file, so onboard uses it: it creates the CircleCI project, follows it, and adds a trigger that runs the pipeline on every push. If you belong to more than one CircleCI organization, add --org with the one to use. Prefer the web app? Click Create Project on the CircleCI home page and connect your fork instead (Create a project has the steps).
  4. Push a commit to start a pipeline. (Onboard may already have started one; either way, you’ll see a failed run in CircleCI.)

    git commit --allow-empty -m "Trigger CircleCI"
    git push
    

Once that initial build fails, you’ll have some pipeline data to explore with Antigravity.

Want to use your own project instead? Run circleci onboard in its folder. If the project doesn’t have a CircleCI config yet, onboard can generate a starter config for it. For more setup options, see the CircleCI Quickstart Guide.

Setting up the CircleCI MCP server

Now for the interesting part. The CircleCI MCP server is what enables Antigravity to actually communicate with CircleCI’s APIs, giving it the ability to fetch build logs, trigger pipelines, analyze test results, and more. It’s built into the CircleCI CLI you installed earlier: circleci mcp start runs the server on your machine, and it uses your login from circleci auth login, so there’s no API token to create or paste.

Step 1: Add the server to Antigravity

Antigravity CLI has a command for adding MCP servers. Run this in your terminal:

agy mcp add circleci-cli circleci mcp start

This adds a circleci-cli entry to Antigravity’s MCP configuration file, ~/.gemini/config/mcp_config.json, which every Antigravity session on your machine reads. Check that it’s there:

agy mcp list

circleci-cli should be listed with the type stdio, the status enabled, and the command circleci mcp start.

Note: If you set up the older CircleCI MCP server for Gemini CLI, which ran with npx and a personal API token, Antigravity may have imported it into mcp_config.json the first time it started. Run agy mcp list, and if you see an entry that runs npx with @circleci/mcp-server-circleci, remove it with agy mcp remove <name> and keep only circleci-cli.

Step 2: Verify everything is connected

Open your terminal, navigate to your project directory, and start Antigravity CLI:

cd /path/to/your/project
agy

Once Antigravity starts up, check that the MCP server is loaded by typing:

/mcp

This opens the MCP manager. circleci-cli should be listed with a check mark next to it, followed by the names of its tools. If it’s there, you’re all set. Press Esc to close the manager.

The Antigravity CLI MCP manager lists the circleci-cli server with a check mark and the start of its tool list.

The server exposes the CLI’s commands as tools, so the list is long (181 tools in CLI 1.15). You don’t need to turn any off: Antigravity loads each tool’s details only when it needs that tool.

To really confirm everything is working, try asking Antigravity to list your projects:

List my followed projects on CircleCI

The first time Antigravity calls a CircleCI tool, it asks Allow calling this tool? and shows the tool’s name, such as circleci-cli/circleci_project_list.

Antigravity CLI asks "Allow calling this tool?" before it calls circleci_project_list on the circleci-cli server, with options to allow the call once, for the conversation, or permanently.

Choose Yes, allow tool call to approve it once, or Yes, and always allow tool … in this conversation so Antigravity stops asking about that tool until you start a new conversation. Antigravity asks about each CircleCI tool separately. To allow every CircleCI tool at once, add "mcp(circleci-cli/*)" to the permissions.allow list in ~/.gemini/antigravity-cli/settings.json. In Auto mode, commands such as git remote -v that only read your project run without a prompt.

Antigravity will reach out to CircleCI through the MCP server and display your projects, grouped by organization. If you see your projects listed, congratulations—you’re ready to start using the integration.

Use case 1: Validate your CircleCI config

Start with something simple but incredibly valuable: validating your CircleCI configuration before you push it. There’s nothing worse than pushing a commit only to have the pipeline fail immediately because of a YAML syntax error or a typo in an orb name.

With Antigravity connected to CircleCI, you can catch these issues before they waste your time. Just ask:

Validate my CircleCI config

Antigravity CLI reports that the project's CircleCI config is valid after calling circleci_config_validate.

Antigravity uses the CircleCI MCP server’s circleci_config_validate tool to check your .circleci/config.yml file with CircleCI’s config compiler. It tells you whether the config is valid and reports any errors it found, often with a summary of your workflows and jobs and suggestions for improvements.

This is especially handy when you’re making changes to a complex configuration or experimenting with new orbs and features. You get instant feedback without needing to commit and push just to see if your syntax is correct.

Use case 2: Trigger a pipeline without leaving your terminal

Here’s a workflow improvement that might seem small but really adds up: triggering pipeline runs without leaving your development environment. Instead of opening CircleCI in a browser, finding your project, and clicking buttons, just ask:

Run the pipeline for my current branch

Antigravity detects your Git remote and current branch, then uses the circleci_pipeline_run tool to kick off a build. Because this starts a real pipeline, Antigravity asks you to approve the call first, unless you’ve already allowed that tool. You’ll get a confirmation message with the new pipeline’s number and ID, and the status of each job.

You can also be more specific about what you want to run:

Run the pipeline for the develop branch

Or if you’re working with multiple projects and want to trigger a build on a different one:

Run the pipeline for gh/my-org/my-other-repo on the main branch

The ability to trigger pipelines without context-switching might seem like a minor convenience, but when you’re in the flow of debugging an issue and need to run multiple test iterations, staying in your development environment makes a real difference.

Use case 3: Diagnose failed builds

This is where the integration really pays off. When a build fails, the traditional workflow involves opening CircleCI, navigating to the failed pipeline, expanding the failed job, scrolling through logs to find the error, and then switching back to your editor to fix it. With Antigravity, you can shortcut all of that.

Just ask:

Why did my last build fail?

Antigravity uses the circleci_run_get tool to fetch a failure report for the run and presents you with a clear explanation of what went wrong: which job failed, which tests failed, and the error messages. It can also look at your recent commits to find the change that most likely caused the failure.

Antigravity CLI explains the failed CircleCI build: six phone validator tests failed in the test job because of an inverted length check.

But Antigravity doesn’t just show you the error—it analyzes the failure and suggests specific fixes. Since you’re already in your project folder with your code available, you can immediately act on those suggestions. Need to update a dependency? Fix a test? Change a configuration value? You can do it right there.

Iterate until the build passes

Here’s where things get really powerful. Instead of manually checking back after each fix, you can ask Antigravity to handle the full cycle:

Fix the issue, then run the pipeline and let me know when it passes

Antigravity will make the necessary code changes, run the tests on your machine, commit the fix, and ask you to approve the push. The push starts a new pipeline, and Antigravity watches it and reports back with the outcome. If the build fails again with a different error, you can continue iterating. All without opening a browser or breaking your focus.

The CircleCI pipelines page for dataforge-demo shows a successful pipeline on main after Antigravity's fix, above the earlier failed pipeline.

Investigate specific runs

Sometimes you need to look at a particular pipeline run, maybe one that a teammate mentioned or one from earlier in the day. Give Antigravity the run’s ID. Antigravity includes run IDs when it lists your recent runs, and the first eight characters are enough:

Show me what happened in run 3f9c1a2b

Antigravity finds the full run, then reports what happened in each job and why it failed. You can paste a pipeline URL instead, but the CircleCI tools look up runs by ID, so Antigravity has to work out which run the URL’s pipeline number points to, which takes much longer.

Use case 4: Analyze test results

Antigravity CLI shows the test results from the last pipeline: 70 tests, 64 passed and 6 failed, with the failed phone validator tests in a table.

When tests fail, you often need more detail than just “3 tests failed.” You want to know which tests, what the error messages were, and where in your code the failures occurred. Antigravity makes this easy:

Show me the test results from the last pipeline

The circleci_testresult_list tool pulls detailed test data for the job, including the name and file of each test, its pass/fail status, and the full failure messages.

If you just want to focus on what broke, you can filter the results:

Show me only the failed tests from the last build

Hunt down flaky tests

Flaky tests are one of the most frustrating problems in any test suite. They pass sometimes and fail other times, eroding your confidence in the build and wasting time when you have to re-run pipelines. Antigravity can help you identify them:

Has CircleCI detected any flaky tests in this project?

The circleci_testresult_flaky tool checks CircleCI’s flaky test detection, which lists tests that failed and then passed within the same pipeline, giving you a starting point for improving your test suite’s reliability. Ask about CircleCI by name: a plain “find flaky tests” can send Antigravity to read and run your test files instead of checking your CircleCI history.

More things to ask Antigravity

The MCP server you set up is the CircleCI CLI, so Antigravity can use any of its commands, not just the ones in this tutorial. Here are a few more requests to try:

Ask Antigravity to… CLI command it runs
Rerun only the failed jobs in my last failed build circleci workflow rerun --from-failed
List the environment variables on this project circleci envvar list
Show how much CPU and memory the test job used in my last build circleci job resource-usage

For every command Antigravity can call, see the CircleCI CLI reference.

Troubleshooting

The MCP server doesn’t appear

If you run /mcp and don’t see the CircleCI server listed or connected, here are some things to check:

  1. Run agy mcp list in your terminal. If circleci-cli is missing, run the agy mcp add command from Step 1 again. If it’s listed as disabled, run agy mcp enable circleci-cli.
  2. Run circleci version to check that the CLI is installed and on your PATH; you need version 1.15 or newer. If Antigravity still can’t start the server, remove it with agy mcp remove circleci-cli and add it again with the full path that which circleci prints (where circleci on Windows), such as /opt/homebrew/bin/circleci.
  3. Make sure you’re running agy in a folder you trusted when Antigravity asked, then type /mcp and restart the circleci-cli server.

Antigravity can’t find your project

If Antigravity doesn’t recognize your project when you ask about pipelines:

  1. Check that the project is being followed in your CircleCI dashboard
  2. Verify your Git remote is configured correctly with git remote -v
  3. Run circleci auth me to check that the CLI is logged in to the account that follows the project
  4. Try specifying the project explicitly: Get pipeline status for gh/my-org/my-repo

Authentication errors

If you’re getting authentication failures:

  1. Run circleci auth me to check that the CLI is still logged in
  2. If Antigravity can read builds but gets 403 errors when it starts pipelines or reruns workflows, run circleci auth login again and select Admin under Access level on the Authorize CircleCI CLI? page
  3. Type /mcp and restart the circleci-cli server so it picks up the new login

Antigravity asks before running a command

In Auto mode, Antigravity runs safe commands on its own, but it asks Run this command? before commands that reach outside your project, such as git push, and gives a reason for each one. Approve it if it’s a command you expect.

Wrapping up

By connecting Antigravity CLI with CircleCI’s MCP server, you’ve given yourself a powerful new workflow that keeps you in your flow state. You can now validate configurations before pushing and catch errors early, trigger pipelines with a simple question instead of clicking through a dashboard, diagnose failed builds using natural language and get actionable suggestions, and analyze test results and track down flaky tests without leaving your terminal.

Every time you don’t have to open a browser tab, navigate to a dashboard, and hunt for information, you save a little bit of mental energy. Those savings add up over a day, a week, a project.

Ready to try it yourself? Sign up for a free CircleCI account and see how much smoother your CI/CD workflow can be.