codex-agy-worker

Use the local Antigravity CLI (agy) as a supervised OpenAI Codex worker for code review and implementation.

Codex remains in control: it chooses a live High/Thinking model, bounds the task, reviews AGY's output and diff, independently runs tests, and integrates isolated work only after verification.

Features

• Read-only review mode with repository mutation detection.
• Direct mode for small, localized edits in the current worktree.
• Isolated mode with a dedicated worker branch and git worktree.
• Runtime model discovery through agy models; no static model inventory.
• Ranked multi-attempt fallback with per-attempt artifacts and quota-aware skips.
• Trusted local AGY execution by default: no Antigravity sandbox prompt loop in headless mode.
• Review prompts allow repository source, installed skills, MCP tools, Internet/web documentation, and external source code references when useful for evidence.
• Optional user-opted-in AGY subagents for evidence-heavy review or heavy isolated implementation, capped by contract at three.
• Optional Gemini /teamwork authorization for complex review or isolated implementation when the user asks for Gemini.
• Optional strict AGY permission/sandbox mode when the user wants Antigravity prompting back.
• Separate stdout/stderr artifacts and an external process timeout.
• File-backed JSON manifests for inspection and recovery.
• Verification-gated, fast-forward-only integration and safe cleanup.
• Read-only Git command guards that block AGY from committing, merging, pushing, or using GitHub/GitLab CLIs.
• Sanitized worker environments that omit unrelated parent-process tokens and secrets.

Requirements

• Codex with plugin support.
• Python 3.10 or later.
• Git.
• An installed and authenticated AGY CLI with --print, --print-timeout, --model, and --mode support.
• A trusted local repository. AGY and its model provider may receive repository contents.

Check the local runtime:

agy --version
agy models

Install from GitHub

codex plugin marketplace add toan203/codex-agy-worker --ref main
codex plugin add codex-agy-worker@codex-agy-worker

Start a new Codex task after installation so the skill is loaded.

Use

Ask Codex naturally:

Use AGY to review the current diff.

Delegate this small implementation to AGY and verify the result.

Use an isolated AGY worker for this refactor, run the tests, then integrate it.

Codex invokes the shipped runner. To inspect it manually:

python3 plugins/codex-agy-worker/scripts/agy_worker.py doctor --repo . --json
python3 plugins/codex-agy-worker/scripts/agy_worker.py --help

Execution modes

review uses AGY planning controls and fails if the repository changes.

direct is limited to clean, explicit target paths. It never commits automatically. Codex reviews the resulting diff and runs tests independently.

isolated creates codex/agy/... in a linked worktree. After Codex records passing verification, the runner commits the worker change and fast-forwards only when the target worktree is still on the recorded target branch and commit. Cleanup removes the integrated worktree and branch. Failed or unsafe workers are preserved for inspection.

Model policy

The runner calls agy models for each run. Small and normal tasks use Gemini Flash High; complex tasks prefer Opus Thinking. Sonnet is explicit-only. Medium and Low are never used, including explicit requests. Model family names and High/Thinking labels are matched case-insensitively, including lowercase AGY model IDs such as gemini-3.6-flash-high, so new AGY model versions do not require a runner update.

Safe nonzero failures before workspace mutation use a live ranked chain: Opus/Sonnet to Gemini Pro High to Gemini Flash High, or Gemini Pro High to Gemini Flash High. Opus quota exhaustion skips the shared Sonnet pool, while Gemini Pro quota exhaustion still permits Flash. Timeout, interruption, guard violation, or mutation stops fallback. Schema-v2 manifests record requested_model, the final selected_model, every item in attempts, and skipped_models with file-backed stdout/stderr paths.

AGY may have its own skills installed. The delegated prompt tells it to use execution-focused skills such as TDD, systematic debugging, and verification, while skipping a new brainstorming/PRD/spec/plan cycle for an already-approved worker task. Process documents are created only when the delegated task explicitly asks for them.

The delegated prompt explicitly says: Read repository source code and project-local instructions directly when needed for evidence. Review and verification may use installed skills, MCP tools, Internet/web documentation, and external source code references when materially useful. AGY must report which evidence sources it used and distinguish repository evidence from external references.

Each AGY invocation is a single bounded worker by default. After user opt-in, Codex may enable AGY-internal subagents for evidence-heavy review or heavy isolated implementation that splits into independent, low-overlap work with known verification. The main AGY process manages at most three subagents in the same repository or shared worktree; nested delegation is forbidden. Codex selects the main model, but AGY owns internal roles and any per-subagent model/reasoning choice its current CLI supports. Codex verifies the combined output or diff as one worker result.

For complex review or isolated work where the user asks Gemini to handle the task, Codex may authorize AGY /teamwork. The runner requires user opt-in, a nonempty Codex reason, and a selected Gemini High model. /teamwork is still capped by prompt contract at three internal teammates, with no nested delegation and no expanded file scope.

Manual opt-in uses:

python3 plugins/codex-agy-worker/scripts/agy_worker.py start \
  --repo . --execution isolated --task-class complex \
  --allow src/ --allow tests/ --prompt "Implement the bounded task." \
  --subagents-user-opt-in --allow-subagents \
  --subagents-reason "three independent implementation areas"

Evidence-heavy review opt-in uses the same subagent flags with --execution review; no files may be modified, and review mode fails if AGY changes the repository.

Gemini /teamwork opt-in uses:

python3 plugins/codex-agy-worker/scripts/agy_worker.py start \
  --repo . --execution isolated --task-class complex \
  --model "Gemini Flash (High)" \
  --allow src/ --allow tests/ --prompt "Implement the bounded task." \
  --teamwork-user-opt-in --allow-teamwork \
  --teamwork-reason "user requested Gemini teamwork for independent areas"

By default the runner passes --dangerously-skip-permissions and does not pass --sandbox. This matches the local-trusted setup where Codex and AGY both run on the user's machine, while avoiding headless Antigravity permission prompts that cannot be answered interactively. The runner still keeps the sanitized environment, Git and remote command guards, allowed-path checks, independent verification, mutation detection, and fast-forward integration gate.

Manifests record the effective AGY permission state. In the default trusted-local path, agy_permissions_mode is trusted_local, skip_agy_permissions is true, and dangerous_permissions_allowed is true because the runner really did authorize AGY's --dangerously-skip-permissions flag. Strict runs record agy_permissions_mode as strict_prompts.

Strict AGY prompting is still available when desired:

python3 plugins/codex-agy-worker/scripts/agy_worker.py start \
  --repo . --execution review --task-class normal \
  --prompt "Review the bounded task." \
  --require-agy-permissions --agy-sandbox

Run artifacts

Run state is stored outside tracked project files:

<git-common-dir>/codex-agy-worker/runs/<run-id>/
  manifest.json
  prompt.txt
  stdout.txt
  stderr.txt
  stdout.attempt-N.txt
  stderr.attempt-N.txt

Large AGY responses remain file-backed until Codex needs them. Empty stdout, timeouts, scope violations, test failures, and target movement block integration.

If AGY exits without stdout because headless mode auto-denied a tool permission, the runner writes a structured permission request into stdout.txt for both zero and nonzero exits, records headless_permission_denied in attempts[].classification, and does not fall back to another model. That stdout is for Codex/user action, not a successful review result; the run remains failed.

Safety boundaries

• The plugin uses trusted local AGY permissions by default: it adds --dangerously-skip-permissions and omits --sandbox unless strict AGY prompting is explicitly requested.
• The plugin preserves proxy environment variables so trusted AGY web/MCP evidence gathering can work behind proxy-configured networks.
• AGY receives a guarded PATH: local read-only Git inspection is allowed, while Git mutations and gh/glab commands are blocked. The supervising runner performs verified commit, fast-forward, and cleanup operations outside that guard.
• Git pager, external-diff, and text-conversion command hooks are blocked for allowlisted inspection commands.
• AGY's mode, sandbox, and permission flags are not the security boundary; Codex supervision and runner guards are.
• Review findings and claimed test results are untrusted until Codex verifies them.
• The runner never automatically reverts user changes, rebases verified work, resolves conflicts, pushes branches, or deletes failed workers.
• A failed isolated worker can be deleted only with the explicit cleanup --force-failed recovery command.
• Direct mode refuses target files that already contain uncommitted work.
• Verification uses a canonical fingerprint that is stable across staging; nested Git repository directory entries are rejected as unverifiable.
• --allow . covers the full repository, and custom worktree roots are resolved once to absolute paths.

Development

scripts/validate.sh
scripts/validate-install.sh

Live tests use disposable repositories only:

scripts/test-live.sh all

License

MIT