Google Jules and AGENTS.md: The Complete 2026 Setup Guide

Google Jules automatically looks for a file named AGENTS.md in the root of your repository — that’s the exact wording from Jules’s own documentation, under a section literally titled “Include AGENTS.md file.” Jules is Google’s asynchronous coding agent: you describe a task, it clones your repo into a Cloud VM, writes a plan, executes multi-file changes, and opens a pull request for you to review. AGENTS.md is how you tell it the things a human-facing README doesn’t need to carry — build commands, conventions, and code it shouldn’t touch.

Jules isn’t an IDE plugin or a terminal REPL you drive interactively. That distinction changes what AGENTS.md is doing for it, and it’s the part most tool-specific AGENTS.md coverage skips over. This is what’s actually confirmed, what isn’t, and how Jules compares to the other cloud-async agents already covered on this site.

What Jules’s Own Docs Say About AGENTS.md

Per the getting-started guide at jules.google/docs/, under “Include AGENTS.md file”:

“Jules now automatically looks for a file named AGENTS.md in the root of your repository. This file can describe the agents or tools in your codebase, such as what they do, how to interact with them, or any input and output conventions. Jules uses this file to better understand your code and generate more relevant plans and completions.”

The docs add one piece of maintenance advice: “Keep AGENTS.md up to date. It helps Jules and your teammates work with your repo more effectively.” That’s the entire scope of what’s documented — support was confirmed, and a changelog entry from June 2025 (“Jules reads from AGENTS.md if it’s in your repo”) marks roughly when it shipped.

What the docs don’t say is worth flagging directly: there’s no mention of nested or per-directory AGENTS.md files, no monorepo precedence rules, and no fallback filenames like AGENT.md or CLAUDE.md. Every sentence about the feature specifies “the root of your repository.” Tools like Amp and Factory’s Droid CLI document explicit hierarchical search paths (see the comparison below); Jules’s public docs don’t currently describe one. If you’re running a monorepo, a single root AGENTS.md covering everything is the only behavior that’s actually confirmed — don’t assume a packages/api/AGENTS.md gets picked up just because that pattern works elsewhere.

Jules Runs in a Cloud VM, Not Your Terminal

This is the detail that changes how you should think about writing an AGENTS.md for Jules versus for a CLI tool like Claude Code or Droid.

Per Jules’s product page, the flow is: “Jules fetches your repository, clones it to a Cloud VM, and develops a plan utilizing the latest [Gemini 3 Pro model].” You review and can edit that plan before execution. Once it runs, “Jules creates a PR of the changes. Approve the PR, merge it to your branch, and publish it on GitHub.” There’s no local file system Jules is reading from mid-session the way a CLI agent tails your working directory — it’s operating inside a disposable VM that only exists for the duration of the task.

Three things follow from that, and they’re the parts of AGENTS.md guidance that are specific to Jules rather than generic AI-agent advice:

1. Gemini 3 Pro is the model, not a configurable choice per task. Jules’s Pro and Ultra plans both list “Gemini 3 Pro” as the model with “priority access to the latest models” — there’s no per-repo model override the way some multi-model tools support. An AGENTS.md written to steer model selection (a pattern that shows up in tool-comparison guides for other agents) has nothing to act on here.
2. The VM is provisioned fresh, so setup instructions matter more than usual. Jules supports an environment setup script (documented separately from AGENTS.md, under “Environment setup”) that installs dependencies before the agent starts working. AGENTS.md tells Jules how to work; the setup script tells the VM what to install. Conflating the two — putting npm install instructions inside AGENTS.md instead of the setup script — means Jules reads it as guidance rather than something it executes.
3. Output is always a PR, never a live edit you watch happen. Anything in AGENTS.md about “ask before making destructive changes” doesn’t map cleanly onto Jules’s model — there’s no live session to interrupt. The actual control point is the plan review step before execution starts, and the PR review after it finishes.

Environment Variables Live in Repo Settings, Not in AGENTS.md

Jules added repository-level environment variables in an October 2025 update. Per that changelog entry: “You can now provide Jules with environment variables at the repository level,” configured by navigating “to your repository’s settings page to add your environment variables.” They’re opt-in per task — “when you start a new task with Jules, you’ll have the option to make these environment variables available to it” — and that choice locks in once the task begins: the setting “cannot be changed after the task has begun.”

This matters for anyone tempted to just paste an API key into AGENTS.md so the agent “has access to it.” AGENTS.md is Markdown that gets read as context and — depending on how a repository is shared — can end up visible to anyone who can view the file, including in a public repo’s git history. Jules’s repo-level environment variables are the documented mechanism for anything that needs to be a credential rather than an instruction, and they’re deliberately kept out of the plain-text instruction file.

The same separation applies to Jules’s GitHub Actions integration, jules-action. To trigger Jules from a workflow — on a schedule, an issue, or a PR event — you generate a JULES_API_KEY from Jules’s settings and store it as a GitHub Actions secret, never inline in the workflow file. The README is direct about it: “Never commit JULES_API_KEY — always use GitHub Actions secrets.” A minimal trigger looks like this:

name: Daily Security Scan

on:
  schedule:
    - cron: '0 6 * * *'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: google-labs-code/jules-invoke@v1
        with:
          prompt: |
            Review recent commits for security issues and open a PR with fixes.
          jules_api_key: ${{ secrets.JULES_API_KEY }}

Between the API key, the repo-level environment variables, and whatever secrets your build itself needs at runtime, a Jules-driven repo can end up with credentials scattered across GitHub Secrets, Jules’s own settings page, and local .env files your setup script reads — three places to rotate a key when it changes, and three places someone can forget to check when auditing what has access to what. 1Password’s CLI (op run) collapses that into one source: secrets stay in a vault, and op run -- <command> injects them into the process environment at execution time — for the setup script Jules runs inside its VM, or for a GitHub Actions step, without a plaintext key living in either place.

How Jules Compares to Other Async Coding Agents

Jules isn’t the only agent that clones a repo, works unsupervised, and returns a PR. Here’s how its AGENTS.md handling and execution model line up against the other cloud-async agents covered on this site:

The pattern worth noticing: tools built around a persistent, interactive session (Droid, Amp) have invested in wide, hierarchical AGENTS.md discovery, because a developer is likely to be working several directories deep in a large repo. Jules’s task-based, single-VM-per-run model doesn’t have that same “which directory am I in right now” problem — a task starts once, against a known root — which may be part of why root-only discovery is what shipped first. Whether that expands to nested files as monorepo usage grows isn’t something the current docs commit to either way.

A Minimal Jules-Ready AGENTS.md

Nothing here is Jules-specific syntax — it’s the same Markdown format every AGENTS.md-reading tool uses — but written with what actually matters for a VM-cloned, PR-producing agent in mind:

# AGENTS.md

## Project overview
Node.js API service. Postgres via Prisma. Deploys to Cloud Run.

## Setup
Do not run `npm install` here — handled by the environment setup script.
Use `npm run dev` to start the service locally inside the task VM.

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- All new endpoints need a corresponding test in `tests/api/`.
- Do not modify files under `infra/` — deployment config is reviewed separately.

## PR expectations
Keep changes scoped to one concern per PR. Reference the task description
in the PR body. Do not merge migrations without a rollback note.

FAQ

Q1. Does Google Jules officially support AGENTS.md? Yes. Jules’s own documentation states under “Include AGENTS.md file”: “Jules now automatically looks for a file named AGENTS.md in the root of your repository.” Support shipped and was confirmed in a changelog entry dated June 2025.

Q2. Where does Jules look for AGENTS.md — root only, or nested directories too? The documented behavior is root only. Jules’s docs describe checking “the root of your repository” and don’t mention per-directory or monorepo-style nested files, unlike tools such as Amp or Factory Droid CLI that document explicit hierarchical search paths.

Q3. Which AI model does Jules use? Gemini 3 Pro. Jules’s product page states it “develops a plan utilizing the latest Gemini 3 Pro model,” and both paid plans list Gemini 3 Pro as the starting model with priority access to newer models as they ship.

Q4. Should I put API keys or secrets in AGENTS.md? No. Jules has a separate, dedicated mechanism for this: repository-level environment variables configured on the repository’s settings page, opted into per task. AGENTS.md is a plain-text instruction file Jules reads as context, not a secure credential store.

Q5. How do I trigger Jules automatically from GitHub Actions? Use Google’s official jules-action (google-labs-code/jules-action). Generate an API key from Jules’s settings, store it as a JULES_API_KEY GitHub Actions secret, and reference ${{ secrets.JULES_API_KEY }} in your workflow — the README explicitly warns against committing the key directly.

Q6. Does Jules run an npm install or build step automatically? Jules supports an optional environment setup script, documented separately from AGENTS.md, that installs dependencies before a task starts. AGENTS.md is for instructions and conventions; the setup script is what actually gets executed to prepare the VM.

Q7. Is Jules an IDE extension like Antigravity or GitHub Copilot? No. Jules has no editor surface — it’s a fully async agent that works in a cloned Cloud VM and returns a pull request. Google’s separate product, Antigravity, is the IDE that reads AGENTS.md and GEMINI.md as in-editor Rules; the two products solve different problems and aren’t interchangeable despite both being from Google.

Related Reading on The Prompt Shelf

• Google Antigravity and AGENTS.md: The Complete 2026 Guide
• Devin AI vs Claude Code: How Each Handles Project Configuration and Rules Files (2026)
• How Factory Droid CLI Discovers AGENTS.md (2026)
• Amp’s AGENTS.md Discovery: The System-Wide Paths (2026)
• Goose and AGENTS.md: Hierarchical Context Loading (2026)

Browse real AGENTS.md examples from open-source repositories in our gallery.