Codex Goals: Automate Complex Development Tasks with AI Agents

Introduction

Codex Goals provide a powerful mechanism for AI agents to tackle complex, multi-step software development tasks. By setting a persistent objective, the agent can autonomously iterate through work, verify its progress against defined criteria, and self-correct until the goal is achieved, significantly reducing the need for constant human intervention.

Configuration Checklist

Element	Version / Link
Language / Runtime	JavaScript / TypeScript
Main library	Codex
Required APIs	GitHub API (for PR checks), Vercel API (for deployments)
Keys / credentials needed	GitHub credentials, Vercel credentials

Step-by-Step Guide

Step 1 — Define Your Goal

Clearly articulate your objective using the /goal command. This includes the desired outcome, how to verify it, and any constraints.

/goal je veux que tous les checks de ma pull request soit vert, sans tricher. Commit et push les changements jusqu'à que ce soit vert.
# English interpretation by the agent:
# Make all checks on the current pull request green without bypassing checks, committing and pushing fixes until the PR is actually green.

Step 2 — Agent Works and Verifies

The agent will begin working on the task. It will execute commands, make code changes, and then attempt to verify its progress based on the 'evidence' provided in the goal. This process is iterative.

# Example commands the agent might run during its work and verification phases:
pnpm ts # Checks TypeScript compilation
pnpm lint # Runs ESLint for code quality
git diff --check # Verifies changes against the repository

# For a more specific goal like fixing TypeScript/ESLint errors:
/goal je veux plus aucune erreur / warning typescript et eslint. Tu dois tout corriger, sans tricher et sans désactiver les règles afin de ne plus avoir d'erreur.
# The agent might then run specific linting commands:
pnpm exec eslint src/routes src/components src/lib/actions src/router.tsx src/providers.tsx convex/auth convex/betterAuth convex/app.ts convex/http.ts convex/migrations/schema.ts convex/testHelpers.ts convex/convex.config.ts convex/utils scripts/migrate-prod-to-convex.ts vite.config.ts --max-warnings 0

Step 3 — Iteration and Completion

If the verification fails, the agent will return to the 'Work' phase, making further changes and re-verifying. This loop continues until the goal's conditions are met. Once satisfied, the agent will report completion.

# Example of a goal to update a favicon with specific constraints and verification steps:
/goal update the favicon of the app using /Users/melvynx/Documents/Figma/NowStack-SaaS.png. You should generate the variants (of size) in order to have the logo everywhere. update also the logo in the app and everywhere needed.

# Verification steps provided to the agent:
Verify:
* commit and push your change, fetch nowstack.melvynx.dev and verify the favicon is updated

# The agent might then use tools like `curl` and `shasum` for verification:
# (until [ "$(vercel inspect https://nowstack-saas-k600631e8-codelynx.vercel.app 2>&1 | grep -i 'status' | head -1 | grep -oE 'READY|ERROR|CANCELED')" != "" ]; do sleep 10; done; vercel inspect https://nowstack-saas-k600631e8-codelynx.vercel.app 2>&1 | grep -i 'status' | head -1)
# [Editor's note: This command waits for Vercel deployment to complete]

# (curl -s https://nowstack.melvynx.dev/favicon.ico -o /tmp/live-favicon.ico && \
# echo "Local:" && shasum -a 256 /Users/melvynx/Developer/saas/nowstack-saas/public/favicon.ico)
# [Editor's note: This command fetches the live favicon and compares its hash with the local file]

# Upon successful completion, the agent reports:
# Goal achieved (5m - 1 turn - 9.5k tokens)

Comparison Tables

Criteria	Ne pas utiliser /goal (Do not use /goal)	Utiliser /goal (Use /goal)
Task Complexity	One-line fix or small fix, simple questions	Performance optimization / test etc... (measurable), complete feature (testable), refactor (lint, typescript), big refactor
Verification	Updates without possible verification	Measurable, testable outcomes with clear evidence
Iteration	Not designed for iterative self-correction	Designed for continuous work and self-correction

⚠️ Common Mistakes & Pitfalls

1. Vague Goal Definition: Beginners often provide unclear objectives, making it difficult for the AI to understand what needs to be done. Fix: Define a precise, measurable outcome for the goal.
2. Lack of Verifiable Evidence: Without concrete ways to check progress (e.g., running tests, checking deployment status), the AI cannot confirm completion. Fix: Specify commands or tools the AI can use to verify the result.
3. Missing Constraints: Failing to set boundaries can lead to the AI taking shortcuts (e.g., disabling lint rules to pass checks). Fix: Explicitly state what the AI should NOT do (e.g., "sans tricher et sans désactiver les règles").
4. Using for Simple Tasks: /goal is overkill for one-shot fixes or simple questions. Fix: Reserve /goal for complex, iterative tasks that benefit from persistent state and self-correction.
5. Ignoring Thread-Scoped Nature: Goals are tied to a specific conversation thread and do not have global memory. Fix: Understand that each goal operates within its own context, and previous goals or external instructions might not be automatically carried over.

Glossary

Codex Goals: Persistent objectives in Codex that keep a conversation thread working toward a defined outcome, continuously iterating and verifying until the condition is met.
Orchestrator: An agent (like Harness) that manages the execution and verification of a goal, ensuring the AI follows the defined steps and constraints.
Evidence: Measurable criteria or methods (e.g., test results, deployment status, code diffs) used by the AI to objectively verify if a goal has been successfully met.

Key Takeaways

• /goal transforms one-off prompts into persistent, self-correcting workflows for AI agents.
• Effective goals require a clear, measurable résultat attendu (expected outcome).
• Specify vérifier par <evidence> (verify by ) to guide the AI on how to check its work.
• Add tout en respectant <contraintes> (while respecting ) to prevent undesirable shortcuts or behaviors.
• Ideal use cases include large refactoring efforts, performance optimizations, and complete feature implementations that are testable.
• Avoid using /goal for trivial tasks or questions that don't require iterative problem-solving.
• Codex Goals maintain a durable state within the thread, allowing the AI to pick up where it left off across turns.
• The feature is available in Codex and integrated into environments like Cloud Code, enhancing AI-assisted development.

Resources

• AI Coding Mastery Course: https://mlv.sh/formation-ai
• OpenAI Developers - Using Goals in Codex: https://developers.openai.com/codex/using-goals-in-codex
  *)

)