opencode and Astro: practical workflow for content sites

opencode is a coding agent that works from the terminal with whatever model provider you configure. In an Astro project, start opencode in the folder that contains package.json and astro.config.mjs, give it a clear task, and it will edit files, run commands, and explain its changes. The best results come from an explicit AGENTS.md, small steps, and a build/typecheck after each pass.

A strengths match: opencode and the Astro compiler

Astro is mostly a compiler and file-based framework rather than a heavily stateful runtime. That makes it a good fit for an agent: the source of truth is plain .astro, Markdown, and JSON or TypeScript config, so opencode can read and edit directly. Content collections are especially friendly because each entry is a file with frontmatter; the agent can add posts, validate against src/content.config.ts, and leave the static pipeline untouched.

Astro also punishes small mistakes that are easy to review: a missing client:* directive turns an interactive island into a dead component, a bad glob in import.meta.glob produces an empty list, and a content frontmatter mismatch fails the build. opencode works well as a pair programmer for these mechanical, well-defined edits, as long as the project instructions describe the conventions. Integrations such as MDX, sitemap, or image optimization usually require only config changes, which the agent can handle if you pin them in AGENTS.md.

Project instructions that keep opencode on track

Astro projects vary: some use content collections heavily, others are mostly static pages, and still others mix islands from React, Vue, Svelte, or Solid. opencode reads project instructions from AGENTS.md in the root. Write it for this specific repo, not a generic AI prompt. The file should include the actual commands for install, dev, build, typecheck, lint, and tests, plus folder conventions and Astro-specific rules.

Example AGENTS.md:

# AGENTS.md

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Production build: `npm run build`
- Preview built site: `npm run preview`
- Typecheck Astro: `npm run astro check`
- Lint: `npm run lint`
- Test: `npm run test`

## Layout
- `src/content/` holds content collections. Do not move or rename entries.
- `src/pages/` is for file-based routes.
- `src/components/` is for reusable `.astro` components and islands.
- `src/layouts/` wraps pages.

## Rules
- Keep all routes static unless an adapter is already configured.
- Any island that needs JavaScript must have one `client:*` directive, for example `client:load`, `client:visible`, or `client:idle`.
- Match content frontmatter exactly to `src/content.config.ts`.
- Do not change `astro.config.mjs` unless the task explicitly requires an integration change.
- After editing any `.astro`, collection, or config file, run `npm run astro check` and `npm run build`.

A short, specific AGENTS.md prevents the most common failures: opencode won’t invent a test command, won’t move content files into src/pages, and won’t quietly add an SSR adapter. If you use pnpm or bun, replace the npm commands. If the project uses a content layer with glob loaders or an external CMS, describe the loader and the expected fields in the same file. You can find more general setup guidance in How to use opencode: a step-by-step guide.

Plan, edit, verify: a small-step loop

Treat each opencode session like a small code review: plan, edit, verify, inspect the diff. Start a task with the command opencode in the project root. Give one bounded task, not a whole roadmap. Ask opencode to run the relevant command before it claims the task is done. Then use git diff to review only what changed. Astro changes are usually small, but a one-line mistake in a glob or frontmatter can break the build.

A good flow is:

1. Ask for a short plan first, and confirm the files it will touch.
2. Allow only one file group at a time: collection, route, component, or config.
3. Require command output in the final message: astro check, build, or tests.
4. Review the diff yourself before moving on.

Example prompts for Astro:

• “Add a new entry to the blog content collection titled Content collections with Zod using the existing frontmatter schema. Run npm run astro check and fix any schema errors.”
• “Convert the newsletter signup form in src/pages/index.astro into a React island with client:load. Keep the existing markup and classes, and wrap the state in a small client component.”
• “Create a /tags/[tag].astro route that lists all posts from the blog collection with a matching tag. Use getCollection and return static paths with getStaticPaths.”
• “Update the navigation in src/components/Nav.astro to use Astro.url.pathname for active link highlighting. Do not add a client-side framework.”
• “Fix all build warnings reported by npm run build that relate to content collection frontmatter or unused imports.”

After opencode finishes, run npm run build yourself, and look at git diff. Do not rely on the agent’s own summary. If the diff touches an island, check that the directive is present; if it touches content config, check that existing entries still build.

Where opencode shines and where Astro trips it up

opencode handles repetitive Astro work well once the conventions are written down. Content collection entries, static routes, data queries with getCollection, and simple island conversions are usually good tasks. The risk areas are the places where Astro’s compile-time behavior differs from a normal JavaScript app.

| Task | Good prompt pattern | Watch for | | Add a collection entry | “Add a new post with frontmatter matching src/content.config.ts” | Missing or extra fields; slug not generated | | Add a dynamic route | “Use getStaticPaths and getCollection to list all entries” | Path params mismatch; invalid return shape | | Add an island | “Convert this section to an island with client:visible” | Missing client:*; importing server module into island | | Edit .astro template | “Keep the component static and prop-drill the data” | Accidental client:load; runtime script added | | Change astro.config.mjs | “Add the integration and explain the setting” | Unneeded adapter; changed render mode |

The most common Astro-specific mistake is adding a framework component without a hydration directive. The second is treating import.meta.glob like a runtime glob: if the path is wrong, the build simply returns an empty object, so a missing page can pass a typecheck but fail in preview. Third, content collection schemas can break many files at once; after any schema edit, run astro check on the whole project.

Check every change before you trust it

Astro has two fast signals: npm run astro check for types and schemas, and npm run build for the static output. Make both part of every task. For content collections, opencode should run astro check because it validates frontmatter against the schema. For route generation, astro build catches missing getStaticPaths return values, bad imports, and adapter mismatches.

For visual or interactive behavior, start the dev server with npm run dev and inspect the changed pages. You can also ask opencode to write or update a small end-to-end test with a browser automation tool if your project already has one. Do not ask the agent to test by reading the terminal output alone; Astro’s compile errors are clear, but hydration and island behavior need a real browser.

Run the project’s own test suite when it exists. A useful final prompt is: “Run npm run astro check, npm run build, and npm run test, and include the output of each command.” If the project uses a package manager other than npm, keep the commands in AGENTS.md and ask opencode to follow that file.

Parallel agents and worktrees for larger Astro projects

For larger Astro work, running opencode alongside another agent in AgentVera is useful. Because each agent can work in its own git worktree, one can add content collection entries while another refactors .astro components without overwriting files. Checkpoints let you undo a broken hydration or schema change in one click. Automatic code review when a turn ends catches missing client:* directives or glob import mistakes at file:line, which are the exact Astro pitfalls that usually slip through. Token budgets prevent an agent from burning a whole day on a single collection migration.

Final thoughts on using opencode with Astro

opencode is most useful with Astro when you treat it like a careful junior teammate: give it precise conventions in AGENTS.md, keep tasks small, and always verify with astro check and astro build. For a deeper look at how opencode compares with other CLI agents, see opencode vs Claude Code: an honest comparison. With those habits, the agent can handle the repetitive Markdown, collection, route, and island plumbing while you stay in control of the site’s architecture.