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.
• Optional user-opted-in AGY subagents for heavy isolated implementation, capped by contract at three.
• Optional Gemini /teamwork authorization for complex 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.

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.

Each AGY invocation is a single bounded worker by default. After user opt-in, Codex may enable AGY-internal subagents only for heavy isolated implementation that splits into independent, low-overlap work with known verification. The main AGY process manages at most three subagents in the 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 diff as one worker output.

For complex 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"

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.

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 and records headless_permission_denied in attempts[].classification. 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.
• 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