Projects & Conversations

Antigravity 2.0 introduced Projects as the core organizational primitive. Before Projects, every conversation was a flat list in the sidebar -- manageable for five sessions, unworkable for fifty. Projects solve this by grouping conversations, scoping permissions and settings, and letting agents operate across multiple workspace folders. A Project declares what an agent can do, where it can work, and who can review its output.

What you'll learn

• Projects group conversations with shared settings, workspace folders, and permission scopes
• Each Project can expose multiple local folders to agents, not just one repository
• Standalone conversations (no Project) use global defaults and are best for one-off tasks
• Git worktree support lets agents work in isolated branches without polluting the active workspace

The problem

Without Projects, every agent session is isolated. Agent A working on the auth module does not know Agent B is refactoring the database layer. Permissions are global: either an agent can run destructive terminal commands everywhere, or it cannot run them anywhere. Conversations pile up in a flat list, with no way to find "that session where we fixed the login race condition last week."

This is the chaos of agent sprawl. Projects are the structure that prevents it.

Options & when to use each

Structure	What it is	When to use it
Project	A named group of conversations with shared settings, permissions, and workspace folders	Any sustained work on a codebase. Feature work, team projects, multi-service applications
Standalone conversation	A one-off agent session not tied to any project; uses global permissions	Quick questions, experiments, exploring a new repository you have not decided to commit to
Multi-workspace Project	A Project exposing multiple local folder paths to its agents	Monorepos, microservice stacks, any situation where agents need to see more than one directory
Git worktree	An isolated branch checked out to a separate directory, used by an agent	Parallel work on the same repo without conflicts; agents working on different branches simultaneously

Build it: create a Project

In the Antigravity UI:

1. Click "New Project" in the sidebar (or use the + button next to Projects)
2. Name it. Choose a name that describes the codebase, not the task:
   - Good: "payments-service", "frontend-dashboard", "infra-configs"
   - Bad: "fix-bug-342", "monday-experiment"

3. Select the workspace folders the Project's agents can access.
   You can add multiple folders. For a monorepo:
     /home/user/monorepo/packages/api
     /home/user/monorepo/packages/frontend
     /home/user/monorepo/packages/shared

4. Configure settings for this Project:
   - Model preference (Gemini 3.5 Flash is default)
   - Permission level (what the agent can execute without asking)
   - Context files (GEMINI.md, project-specific instructions)

5. Start a new conversation inside this Project.

Each Project gets its own settings file. The Project-level permissions augment (restrict or relax) your global permissions. For example, you might allow terminal commands globally but restrict a specific Project to read-only filesystem access.

Multi-workspace Projects

One Project can span multiple directories. This matters when your application is split across several folders, a common pattern in microservice architectures and monorepos:

Project: "full-stack-app"
  Workspaces:
    - ~/code/backend        (Python/FastAPI)
    - ~/code/frontend       (React/TypeScript)
    - ~/code/infra          (Terraform)

An agent in this Project can read the frontend's API call definitions, cross-reference them with the backend's route handlers, and flag mismatches. Without multi-workspace support, you would need to copy the relevant types back and forth manually, or run separate agents and coordinate their findings yourself.

Scheduled Tasks within Projects

Antigravity 2.0's Scheduled Tasks run inside Projects. You set a cron schedule, a prompt, and a Project. The agent launches in the background according to the schedule, and its conversation appears in the Project's sidebar group.

# Example scheduled task ideas:
# "Every morning at 8 AM: Check for dependency updates and create a summary"
# "On push to main: Run the full test suite and flag regressions"
# "Weekly on Monday: Audit security vulnerabilities in dependencies"

Scheduled tasks currently use Gemini 3.5 Flash by default.

What goes wrong

Mistake	How you notice it	The fix
Using standalone conversations for everything	Sidebar is a flat list of 40 conversations with no organization; cannot find past sessions	Create a Project for any codebase you work on more than once. Move existing conversations into Projects
Giving a Project overly broad permissions	Agent makes changes you did not intend and you did not catch in review	Set Project permissions to the minimum needed. You can always grant more during a session if the agent requests it
Creating one Project per task instead of per codebase	Dozens of Projects with one or two conversations each; settings duplicated across Projects	A Project is for a codebase or domain, not a ticket. Use conversations within a Project for individual tasks
Forgetting to add secondary workspaces	Agent cannot find files it needs in related services or shared libraries; asks you to copy them	When setting up a Project, add every folder the agent might need to read. Multiple folders are cheap

Confirm it worked

1. Create a Project with at least two workspace folders (even if one is empty)
2. Start a conversation and ask the agent: "Look at both workspace folders and tell me what they contain"
3. The agent should list the contents of both directories, confirming it can see across workspaces
4. Start a second conversation in the same Project about a different topic
5. Verify both conversations appear under the same Project in the sidebar

If the agent can see both workspaces and both conversations are grouped under one Project, the Project structure is working.

Next: Artifacts & Codebase Understanding