Getting started with Google Antigravity CLI and CircleCI
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 (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.
- Head over to the demo repo and click the Fork button
-
Clone your fork and change into its folder:
git clone https://github.com/<your-username>/dataforge-demo.git cd dataforge-demo - Run
circleci onboard --scan. The repository already has a.circleci/config.ymlfile, 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--orgwith 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). -
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 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.
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 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.
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.
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
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:
- Run
agy mcp listin your terminal. Ifcircleci-cliis missing, run theagy mcp addcommand from Step 1 again. If it’s listed asdisabled, runagy mcp enable circleci-cli. - Run
circleci versionto check that the CLI is installed and on yourPATH; you need version 1.15 or newer. If Antigravity still can’t start the server, remove it withagy mcp remove circleci-cliand add it again with the full path thatwhich circleciprints (where circlecion Windows), such as/opt/homebrew/bin/circleci. - Make sure you’re running
agyin a folder you trusted when Antigravity asked, then type/mcpand restart thecircleci-cliserver.
Antigravity can’t find your project
If Antigravity doesn’t recognize your project when you ask about pipelines:
- Check that the project is being followed in your CircleCI dashboard
- Verify your Git remote is configured correctly with
git remote -v - Run
circleci auth meto check that the CLI is logged in to the account that follows the project - Try specifying the project explicitly:
Get pipeline status for gh/my-org/my-repo
Authentication errors
If you’re getting authentication failures:
- Run
circleci auth meto check that the CLI is still logged in - If Antigravity can read builds but gets
403errors when it starts pipelines or reruns workflows, runcircleci auth loginagain and select Admin under Access level on the Authorize CircleCI CLI? page - Type
/mcpand restart thecircleci-cliserver 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.