Gemini CLI Astro: Practical Guide for Astro Developers

Gemini CLI is a terminal coding agent that can scaffold, edit, and debug an Astro project when you run gemini in the project folder. This guide shows a practical working setup for Astro: what to put in GEMINI.md, how to plan and review changes, and how to catch the content-collection and islands issues that break static builds. For orientation, see Gemini CLI.

Why Gemini CLI fits Astro’s file-driven workflow

Astro projects are file-driven and mostly static: routes map to src/pages, components to src/components, content to src/content, and configuration lives in astro.config.mjs. Gemini CLI works well in this environment because it can read those files directly, edit .astro templates, update frontmatter, and run the project’s own commands for immediate feedback. It handles content collections well when the schema is explicit, and it can reason about island hydration because it reads component code and integration config. It is not a replacement for the Astro build; it is best used as a fast editor and checker that you constrain with project-specific rules.

Configure GEMINI.md for an Astro project

Create a GEMINI.md file in the project root. Gemini CLI reads it at startup and uses it as the source of truth for commands, folder conventions, and constraints. Keep it short, command-first, and specific to the repository. Do not give generic AI rules; give the exact commands for package manager, build, lint, type checking, test, and preview. Include folder conventions and Astro-specific rules that prevent destructive or non-static changes.

A realistic GEMINI.md for an Astro project looks like this:

# GEMINI.md

## Commands
- Install: npm install
- Dev: npm run dev
- Build: npm run build
- Preview: npm run preview
- Lint: npm run lint
- Typecheck: npm run astro check
- Test: npm run test

## Folder conventions
- src/pages/**/*.astro are routes. Preserve file names unless asked.
- src/components/**/*.astro are reusable components. Keep props typed with TypeScript.
- src/content/<collection>/*.md or .mdx are content entries. Do not edit frontmatter fields that are not in the collection schema.
- src/layouts/**/*.astro are layouts. Changes there affect every page.

## Astro rules
- Before editing a content collection, read src/content.config.ts to see the schema.
- Do not add client:load to a component unless interactivity is required and the component uses browser APIs.
- Keep static pages static. If a route uses getStaticPaths, do not replace it with a dynamic route.
- After changing imports or components, run `npm run astro check` and `npm run build`.

If the project has no test script, set Test to npm run build or add astro check as the minimum gate. The key is that the agent must know the exact commands that prove a change is safe. If you are new to the agent workflow, the step-by-step guide at How to use Gemini CLI: a step-by-step guide covers the basics.

Use a tight review loop for Astro changes

Use small, reviewable steps instead of monolithic requests. A good loop is:

1. Define scope: one route, one component, or one content collection.
2. Ask the agent to read relevant files and propose a plan with a file list.
3. Review the plan and reject changes outside the scope.
4. Ask for implementation with minimal edits.
5. Run npm run astro check, npm run build, and project tests after the change.
6. Review the git diff before accepting.

This is essentially a stricter version of AI pair programming: how to work with a coding agent.

Example prompts for typical Astro tasks:

• Add a new blog post collection with title, date, description, and draft fields in src/content.config.ts. Keep the existing layout and create one sample post.
• Add a dark mode toggle to the header component. Use a small vanilla island and respect the existing CSS custom properties.
• Refactor the BaseLayout.astro props to use a TypeScript interface and update all layouts that pass partial props.
• Fix the failing static build: read the error log and tell me which page or import breaks the build before changing anything.
• Create a new /uses page that lists tools from a JSON file in src/data/tools.json using a static .astro component.

Where Gemini CLI shines and common Astro pitfalls

Gemini CLI handles structural, file-driven tasks well: adding content collections, moving components, updating imports, converting static HTML to .astro components, writing getStaticPaths, and fixing build errors. It is weaker when it guesses content schema or hydration needs. Watch for specific Astro pitfalls: it may add client:load to everything because it thinks interactivity is needed; it may change frontmatter fields not present in the schema; it may convert static pages to on-demand rendering without being asked; it may edit generated type files after running astro sync.

Verify Astro changes with the agent

Make the agent verify its own work, but review the output yourself. Start with npm run astro check for template and TypeScript errors. Then run npm run build to catch collection schema mismatches, invalid imports, and route problems. If the project has tests, run them too. For visual changes, run npm run preview and inspect the pages. Ask the agent to report the exact commands and their exit codes. Do not accept should work without a passing build. If there are no tests, treat astro check and a full build as the acceptance baseline. After astro sync, the agent may want to commit generated files; keep those out of the diff unless the project intentionally tracks them.

Parallel Astro work with AgentVera

When you need parallel work on an Astro project, AgentVera lets several coding agents run side by side in real terminal panels. The most useful parts for Astro are isolated git worktrees, so one agent can edit content collections while another fixes an island without overwriting files, automatic code review that points to file:line after each turn, and checkpoints that let you undo an agent’s changes in one click. Token budgets stop a runaway agent from burning time on a long build loop. This orchestration pattern is covered in AI coding agent orchestration for coding: 5 patterns and tools.

Final notes on using Gemini CLI with Astro

Gemini CLI is most useful on Astro when it has a tight GEMINI.md, works in small diffs, and must pass astro check and astro build before a task is considered done. Treat content collections and islands as the two places you inspect manually. With those guardrails, the agent becomes a reliable pair programmer for static-first Astro work.