# Codex Astro: Practical Guide for Astro Projects

URL: https://agentvera.dev/en/blog/codex-for-astro/ · Published: 2026-11-01

Use Codex effectively in Astro projects: set up AGENTS.md, manage content collections and islands, run builds and tests, and scale with multi-agent worktrees.

**In short:**

- Start Codex with codex and an Astro-specific AGENTS.md so builds, content collections, and component rules stay consistent.
- Break Astro work into small steps around astro check, astro build, and precise git diffs to catch island hydration issues early.
- Use parallel worktrees and automatic code review to let several Codex agents edit one Astro repo safely.

Codex can be a productive pair programmer on an Astro repo when you give it clear project-specific instructions and keep changes small. Start it with `codex` in the project folder and use AGENTS.md to teach it your build, check, content-collection, and component conventions. This guide focuses on the workflow, prompts, and verification steps that make that pairing reliable.

## Why Codex suits Astro work

Astro has a small, explicit surface area: `.astro` files, `src/pages`, `src/components`, `src/content`, `astro.config.mjs`, and integrations. Codex handles that well because most jobs are local edits with clear static/dynamic boundaries. It can add content collection schemas, generate routes from collections, refactor layout slots, and wrap interactive parts as islands without forcing the whole page client-side. The value is biggest when you ask for one Astro concern at a time: type content, update a component, add an integration, verify the build. For the general CLI workflow, see [How to use Codex CLI: a step-by-step guide](/en/blog/how-to-use-codex-cli/).

## Setting up the project for Codex

Codex reads project instructions from AGENTS.md in the repo root. Keep it short enough that the agent actually follows it. For Astro, include commands, folder conventions, and rules that prevent common mistakes around islands, content collections, and public assets.

```
# AGENTS.md

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

## Folder conventions
- src/components/ for reusable Astro and framework components
- src/layouts/ for page layouts
- src/pages/ for routes
- src/content/ for content collections
- public/ for unprocessed static assets only

## Astro rules
- Keep .astro files strict TypeScript; no `any` without an explanatory comment.
- Content collections must have a schema in src/content.config.ts. Do not edit generated .astro/types.d.ts.
- Add a `client:*` directive only where hydration is actually needed; prefer static HTML otherwise.
- Never import server-only modules or Node built-ins into hydrated islands.
- Run `npm run check` and `npm run build` after any change to content collections, integrations, or astro.config.mjs.
```

## A working loop

Use a tight loop with Codex: ask for one small change, wait for the diff, run Astro’s checks, inspect the changes, then either ask for a fix or move on. Do not ask for a whole site redesign in one prompt. After any config or collection change, run `npm run check` and `npm run build` before the next prompt.

Example prompts for typical Astro tasks:

- Read AGENTS.md, then add a blog content collection for Markdown posts with title, date, tags, and draft fields. Create `src/pages/blog/[slug].astro` to render each post and a `src/pages/blog/index.astro` list page.
- Convert only the interactive search input in the header into a Preact island with `client:visible`. Keep the rest of the header static, and do not change other components.
- Add the official sitemap integration, configure it for the public routes, and verify `npm run build` completes without warnings.
- Refactor the base layout to use named slots for page title and meta description. Update three pages to demonstrate the slots, then run `npm run check`.
- Change all Markdown post images to use Astro’s `astro:assets` Image component where local images are referenced. Preserve existing alt text and do not move files out of `src/assets`.

## Typical Astro tasks and pitfalls

Codex is reliable for mechanical Astro work: adding pages, updating content schemas, converting static markup into islands, adding integrations, and moving styles into scoped `.astro` styles. It is less reliable at global decisions such as choosing adapters, changing rendering modes, or deciding whether an island should load on the client at all. Review those changes closely.

| Task | Good prompt | Watch for |
| --- | --- | --- |
| Content collections | `Add a draft field to the posts collection and update the post layout to hide drafts.` | Schema changes break `getCollection()` queries; run `npm run check` and ensure the generated types are up to date. |
| Islands | `Make the mobile menu a client:visible island and leave the rest of the page static.` | Adding `client:load` everywhere hydrates static markup; importing `Astro.url` or Node modules into an island fails. |
| Integrations | `Add the sitemap integration and include only public, non-draft routes.` | It may place the integration after incompatible plugins or forget `npm install`; check `astro.config.mjs` and `package.json`. |
| Images | `Use Astro image optimization for blog cover images in src/assets.` | It may copy assets to `public/` and lose optimization, or create broken paths in frontmatter. |

Specific Astro traps to review in diffs: `.astro` templates are not JSX, so expressions and comments can look subtly wrong; `set:html` without sanitizing user content; `prerender` vs server routes in the same page; and import aliases such as `@components` that are configured in `tsconfig.json` but break if moved.

## Testing and verification in Astro with the agent

Treat every Codex turn as a pull-request candidate. Run `npm run check`, `npm run lint` if configured, `npm run build`, and the project test suite. For content-heavy sites, add a quick `npm run build` plus `npm run preview` smoke test. Inspect `git diff` for accidental edits to `astro.config.mjs`, `package.json`, and generated types. For island work, look specifically for `client:*` directives and imports inside `.astro` frontmatter. Use a second model to review the diff if available; the goal is to catch Astro-specific issues before they reach main. See [AI code review: check what your agents write](/en/blog/ai-code-review/) for that review pattern.

## Running several agents on one Astro project with AgentVera

AgentVera runs several coding agents' real CLIs side by side in one window, each in its own terminal panel. For Astro work, the most useful mode is giving each agent its own git worktree, so one can add a content collection while another refactors islands without overwriting files. Automatic code review links findings to file:line, which catches hydration and schema mistakes early, and checkpoints let you undo a bad `astro.config.mjs` experiment in one click and replay the session step by step. Token budgets keep long Astro builds and multiple agents from consuming the full account unexpectedly.

## Wrap-up

Codex becomes a reliable Astro agent when you constrain the work to small, verifiable changes and keep a tight build-check loop. Put the commands and Astro-specific rules in AGENTS.md, review diffs with an eye for islands and content collections, and use parallel worktrees when you need more throughput. The agent is not a substitute for `astro check`; it is a faster way to get to the next failing check.

## Frequently asked questions

**What is Codex Astro?** Codex is OpenAI’s coding agent used in the terminal; Codex Astro refers to running codex from an Astro project root and asking it to edit Astro components, content collections, and configuration. It works well when you define project-specific rules in AGENTS.md and review each change with Astro’s checks and build.

**How do I set up Codex for an Astro project?** Add an AGENTS.md file in the project root with build, check, lint, and test commands plus Astro folder conventions. Start Codex with codex in that folder and ask it to read AGENTS.md before making changes.

**Can Codex handle Astro content collections and islands?** Yes. Codex can create or update content collection schemas, generate pages from collections, and convert sections into framework islands with client directives. Always run astro check and astro build afterward, because mismatched schemas or island imports break quickly.

**How do I review and test Codex changes in Astro?** Run npm run check, npm run build, and your test suite, then inspect git diff for hydration boundaries, config changes, and generated type updates. For small edits, use git diff --check and preview with npm run preview before merging.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/