Google Antigravity Setup
Google's agent-first IDE for FFC website development
Antigravity is a free, agent-first code editor built on the VS Code foundation. Its built-in Gemini agents can plan work, write code, run our tests, and open pull requests for you. This guide gets you from zero to opening your first FFC pull request.
This is an advanced environment. If you are new to development, start with Claude Desktop — most charity website work never needs more. Come here when you want local builds, browser debugging, or larger refactors. Antigravity ships Gemini agents, but you can also run Claude or Codex as the agent. See the setup hub to compare options.
On this page
1. What Antigravity Is
Google Antigravity reuses the open-source VS Code foundation, so the layout will feel familiar, but it puts an AI agent at the center instead of the text cursor. You describe a task in plain English and a Gemini-powered agent plans it, edits files, runs commands, and reports back. FFC already maintains an Antigravity static-site agent repository, so this editor is a first-class part of our toolchain.
Why we like it for volunteers: the free public preview signs in with an ordinary Google account, and the agent can do almost everything in this guide for you once it is connected. When in doubt, ask the agent.
2. Download and Install
- Go to antigravity.google and download the installer for your operating system (Windows, macOS, or a supported Linux distribution).
- Run the installer and accept the defaults.
- Make sure you also have Google Chrome installed — Antigravity uses it for the browser-driving agent features.
- Launch Antigravity.
Tip: Because Antigravity is a VS Code fork, when it offers to import settings or asks about a color theme and keybindings, the VS Code defaults are a safe choice.
3. Sign In with Google
- On first launch, Antigravity prompts you to sign in. Choose to sign in with Google.
- Your browser opens. Sign in with your personal Gmail/Google account — the free preview does not require a credit card or a paid plan.
- After authentication, the browser shows a success message and hands you back to the Antigravity app.
If sign-in stalls(“unexpected issue setting up your account”), close Antigravity completely, make sure Chrome is your default browser or is at least installed, and try again. This is a common preview hiccup and usually resolves on a second attempt.
4. Tour: Editor and Agent Manager
Antigravity has two primary surfaces. Knowing which is which saves a lot of confusion.
📝 The Editor
The familiar VS Code-style window: file tree, open files, terminal, and source control. Use it to read code, review the agent's changes, and run commands yourself when you want to.
🤖 The Agent Manager
Where you give the agent tasks and watch it work across plans, edits, and test runs. This is where most of your FFC work happens: describe the issue, approve the plan, and review the result.
Newer builds may be branded Antigravity 2.0 and ship a companion Antigravity CLI. They share the same agent harness and settings, so this guide applies to both.
5. Install Git, Node, and pnpm
FFC sites are Next.js projects, so you need Git, Node.js 20+ and pnpm 9 (our repos pin pnpm 9). Do not look up install commands — let the agent do it for you. Open the Agent Manager and ask:
“Set up my machine for Free For Charity Next.js development. Check whether Git, Node.js 20 LTS or newer, and pnpm 9 are installed, install anything missing using the right method for my operating system, and confirm the versions when you are done. Our repositories pin pnpm 9, so match that.”
6. Connect to GitHub
You connect to GitHub in two complementary ways: once for Git (so you can push branches) and once for the GitHub MCP server (so the agent can manage issues and PRs — covered in the next section).
6.1 — Confirm org membership
Make sure a maintainer has added you to the FreeForCharity GitHub organization. Accept the email invitation before continuing.
6.2 — Sign in to GitHub in the editor
Use the built-in GitHub sign-in (Accounts / Source Control panel) and authorize in the browser. This stores credentials securely so Git can push without pasting passwords. The agent can set up your Git identity and confirm everything for you — just ask.
“Help me connect this editor to GitHub. Set my Git name and email, confirm I am signed in, and verify I have access to the FreeForCharity organization. Walk me through any browser authorization that is needed.”
Prefer the editor's built-in GitHub sign-in over a raw Personal Access Token where possible. If a token is ever required, scope it narrowly and never commit it.
7. Enable MCP Servers
MCP (Model Context Protocol) servers give the agent extra abilities. For FFC work you need at least GitHub (issues and PRs) and Playwright (browser testing). Antigravity ships an MCP Store where these are available as one-click installs — you do not assemble any configuration by hand. The easiest path is to let the agent enable them:
“Enable the GitHub and Playwright MCP servers for me — install them from the MCP Store or wherever they live in this version, walk me through any sign-in, then reload and confirm the new tools are available. I'll use them to work on FreeForCharity's repositories.”
The first Playwright run downloads a browser — that is expected.
Let the agent handle the particulars.Store entries and config formats change between versions, so we keep this prompt-driven. The GitHub server needs a token — provide it through the editor's secure prompt or an environment variable, and never paste a token into a file, an issue, or chat.
8. Clone a Template Repo
Practice on a real FFC repository. The FFC_Single_Page_Template is the starting point for new charity sites and ships the full toolchain.
Let the agent clone it, install dependencies, and run the checks — it knows the commands for the current toolchain, so you do not have to:
“Clone FreeForCharity/FFC_Single_Page_Template, open it, install dependencies, then run our full set of checks in the order our AGENTS.md describes (formatting, linting, build, tests, and end-to-end tests). For an example of a finished Free For Charity site, also pull up FreeForCharity/FFC-IN-ffcadmin.org. Do not cancel long-running commands; tell me if anything fails and how to fix it.”
In the Editor you can also choose Open Folder to open the cloned directory. The build and end-to-end tests can take a minute — let them finish.
9. Your First Issue to Merge
With the agent, GitHub MCP, and Playwright MCP connected, you can run the full FFC contribution loop. Try a small, safe change such as fixing a typo.
Step 1 — Pick or open an issue
Ask the agent to list open issues on the repo, or to open a new one describing your change.
“Using the GitHub MCP server, list the open issues on this repository. If there is no issue for the small change I want to make, open a new issue titled ‘<short title>’ describing it.”
Step 2 — Branch and edit
Tell the agent to create a branch (never commit to main) and make the change. Review the diff in the Editor.
“Create a new branch for issue #<number> (do not commit to main) and make the change it describes. Follow the repo's AGENTS.md conventions, and use FreeForCharity/FFC-IN-ffcadmin.orgas an example of how a finished site is built. When you are done, show me the full diff so I can review it before we go further.”
Step 3 — Run the checks
Have the agent run our full set of checks — formatting, linting, build, unit tests, and end-to-end tests — in the order our AGENTS.md specifies (build before tests, to match CI). You do not need to remember the exact commands; the agent reads them from the repo.
“Run our full pre-commit checklist in the order documented in this repo's AGENTS.md(formatting, linting, build, unit tests, then end-to-end tests). Do not cancel anything. Fix any failures and re-run until everything passes.”
Step 4 — Open a PR and merge
Using the GitHub MCP server, the agent commits with a Conventional Commit message, pushes the branch, and opens a PR linked to the issue with Fixes #NNN. Once CI passes and a maintainer approves, the PR merges into the repository.
“Commit the changes with a Conventional Commit message, push the branch, and open a pull request that links the issue with ‘Fixes #<number>’. Then watch the CI checks and fix anything that fails until they are green.”
That is the whole loop. Every future change — on any FFC charity or website repo — follows these same four steps.
10. Security and Good Habits
- ✕Never paste tokens, passwords, or API keys into chat, code, commits, or the MCP config file.
- ✓Use the editor's secure credential prompts or a local
.envfile (already git-ignored). - ✓Always review the agent's diff and the commands it wants to run before approving.
- ✓Work on a branch and open a PR — never push directly to main.
See the FFC security rules for the full policy.
11. Troubleshooting
| Symptom | Fix |
|---|---|
| Sign-in fails or loops | Fully quit and reopen; ensure Chrome is installed; retry. It usually works on the second attempt. |
| MCP tools not showing | Reload the agent after enabling a server; if it still does not appear, ask the agent to re-enable it and confirm it started. |
| Playwright cannot launch a browser | Ask the agent to install the Playwright browsers once. |
| Push rejected | Confirm FreeForCharity org membership and that you are on a branch, not main. |