# Codex Go: How to Use the Codex CLI Agent on a Go Project

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

A practical guide to using Codex on Go projects: setup, AGENTS.md, prompts, testing, common pitfalls, and running parallel agents via AgentVera.

**In short:**

- Codex works best on Go projects when you define build, test, and lint commands in AGENTS.md.
- Keep prompts small and verification-driven: run go test, go vet, and gofmt after each change.
- Watch Codex closely around interfaces, goroutines, and module boundaries; use go test -race after concurrency changes.

Codex is a capable coding agent for Go when you treat it like a fast junior engineer: clear instructions, small diffs, and verification after every step. This guide covers project setup, AGENTS.md, prompt loops, common pitfalls, and testing workflows so you can use [Codex](/en/agents/codex/) on Go projects without fighting the language.

## Go-friendly agent behavior
Go’s toolchain gives Codex fast, unambiguous feedback. A single command such as `go test ./...` compiles and tests the whole module, while `gofmt -l .` and `go vet ./...` give formatting and correctness signals that are easy for the agent to act on. Because Go has explicit interfaces, table-driven tests, and a small standard library, Codex can often produce idiomatic changes without external context. The module system also makes dependency boundaries visible: Codex can stay inside the project layout when you tell it which folders are off-limits. Codex’s ability to run commands and read compiler errors means many Go mistakes get caught before you review the diff, and gofmt removes formatting debates.

## Project prep: AGENTS.md that keeps Codex on track
Codex reads project instructions from AGENTS.md. Keep the file short and operational: commands the agent should run, folder conventions, and rules that prevent common Go mistakes. A realistic AGENTS.md for a Go project looks like this:

```text
# AGENTS.md

## Commands
- Build: `go build ./...`
- Test: `go test ./...`
- Lint: `go vet ./...` and `gofmt -l .`
- Generate: `go generate ./...`

## Folder conventions
- Library code that is not part of the public API lives in `/internal`.
- Generated code lives in `/gen`; do not edit it by hand.
- One package per directory; tests live next to the source.

## Go rules
- Always run `gofmt -w` on changed files before finishing.
- Do not add new dependencies without asking first.
- Prefer table-driven tests for new behavior.
- Keep `context.Context` as the first parameter in functions that accept it.
- Use `go test -race ./...` when touching goroutines or shared state.
```

Do not turn AGENTS.md into a style guide. The agent needs to recall commands and constraints, not read a book. If the project uses `make` or a specific linter, put the exact invocation there. If your CI runs `go test -race` or `staticcheck`, include that command too, because Codex will use it before you merge.

## A short feedback loop with prompts that work
Work in small steps and verify each one. A useful loop is: describe the desired change and its tests, let Codex edit the files, run `go test ./...`, `go vet ./...`, and `gofmt -l .` to check formatting, then review the diff. If the agent changes more than expected, reset or ask it to split the change. Review the diff with `git diff --stat` and `git diff --check` to catch whitespace and broad changes.

For CLI details outside this guide, [How to use Codex CLI: a step-by-step guide](/en/blog/how-to-use-codex-cli/) covers the basics.

Example prompts for common Go tasks:

- Add a `GetUser` method to the `UserStore` interface and implement it for the postgres and memory stores. Update the generated mocks and add a table-driven test for missing users.
- Fix the timeout in `worker.go` so it respects the caller context. Use `ctx.Done()` and `sync.WaitGroup`, and add a test with a canceled context.
- Refactor `main.go` to move HTTP handlers into `internal/api`. Keep public behavior unchanged and update all imports.
- Run `go test ./...` and `go vet ./...`, then fix any failures you introduced.
- Review the diff for error handling: wrap errors with `%w`, do not use `panic` in library code, and close response bodies where needed.

The important part is that each prompt names a file, package, or test target. Vague instructions such as improve the code produce broad diffs and more review work.

## Good fits and Go-specific pitfalls
Codex is useful for interface updates, test generation, refactors, and concurrency fixes, but Go has specific failure modes.

| Task | Good prompt | Watch closely |
|---|---|---|
| Add an interface method | Add `Update` to `Store` and implement it for all current implementations. | Every implementation and mock must be updated; the compiler catches missing methods but not semantic drift. |
| Fix a goroutine leak | Make `process` exit when the context is canceled and wait for spawned goroutines. | Check `ctx.Done()`, `sync.WaitGroup`, channel closure, and run `go test -race`. |
| Move code between packages | Move `handler` from `main` to `internal/api`. | Import cycles, exported names, and whether the package remains testable. |
| Change a dependency | Upgrade `golang.org/x/sync` and adjust call sites. | Changes in `go.mod` and `go.sum`, license and API compatibility, and transitive dependency bloat. |

Go-specific pitfalls to watch: Codex may overuse `interface{}` / `any` when a concrete type or constrained generic would be clearer. It may wrap errors inconsistently or forget `%w` when you need callers to inspect the original error. It may add a dependency for something already in the standard library. It may introduce a data race by sharing a slice or map across goroutines. It may create an import cycle when refactoring packages. When Codex adds an interface, check that it does not over-abstract; an interface with one method and one implementation is often premature. Always ask the agent to run `go test -race ./...` and `go vet ./...` after touching concurrency or imports.

## Verification beyond compile: race, vet, fmt
Use Go’s own test output as the acceptance signal. Prefer table-driven tests because they give Codex a clear pattern to follow and make failures pinpoint a specific case. After each change, run:

```text
go test ./...
go test -race ./...
go vet ./...
gofmt -l .
```

If Codex writes a test, review it for false confidence: a test that only checks `err == nil` or uses a fixed sleep is weak. Ask Codex to use contexts, timeouts, and table cases instead of sleeps. For HTTP handlers, ask Codex to use `httptest`; for time-dependent code, inject a clock or use timers with contexts rather than `time.Sleep`. For a second pass over Codex diffs, automated review can catch issues you would otherwise miss; the workflow is described in [AI code review: check what your agents write](/en/blog/ai-code-review/).

## Parallel agents on a Go codebase
AgentVera is a desktop app that runs Codex and other coding agents' real command line tools in separate terminal panels. For Go projects, the most useful parts are parallel agents in their own git worktrees so they don’t overwrite each other’s files, automatic code review with file:line links when a turn ends, token budgets per agent/turn/day that stop runaway work without losing the conversation, and checkpoints that let you undo a bad refactor or replay a session step by step. This fits Go work because package boundaries make independent changes easy to split, and a second review pass catches interface or concurrency mistakes before they reach your branch.

## Final thoughts
Codex works well on Go projects when you give it a tight AGENTS.md, small prompts tied to files or tests, and a verification loop built around `go test`, `go vet`, and `gofmt`. Watch it most closely around interfaces, goroutines, and module boundaries, and use AgentVera when you need several agents working in parallel without stepping on each other.

## Frequently asked questions

**How do I start Codex in a Go project?** Run the codex command in the project folder after adding an AGENTS.md file. Codex will read project instructions and can execute Go commands such as go test ./... and go vet ./... as it works.

**What should I put in AGENTS.md for a Go project?** Keep it short: build, test, and lint commands, folder conventions such as /internal and /gen, and Go rules like always running gofmt, using table-driven tests, and passing context.Context first. Avoid long style guides.

**Can Codex run go test and go vet automatically?** Yes, Codex can run shell commands, so you can ask it to run go test ./..., go test -race ./..., go vet ./..., and gofmt -l . and then fix the failures. It works best when you include the exact commands in AGENTS.md.

**How do I prevent Codex from introducing Go concurrency bugs?** Tell it to use go test -race ./... before finishing any change that touches goroutines, channels, or shared state. In AGENTS.md, require context.Context as the first parameter and forbid shared access to slices and maps without synchronization.

---

**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/