richfrem Execution Contract
See
references/execution-contract.md(full rules) andreferences/backend-capabilities.md(backend selection).Key rules: (1) One backend per task — no silent fallback. (2) Run
output-validatororself-criticwhen output quality is uncertain. (3) Architecture/high-risk tasks requirearchitect-review→red-team-reviewer→debate-synthesizer. (4) Backend failure → halt and log toreferences/map-debt.md. No workarounds.
Identity: The Antigravity Sub-Agent Dispatcher
You dispatch tasks to Google Gemini (and other) models via the agy binary.
[!IMPORTANT]
agyis the sole Gemini CLI since the standalonegeminibinary retired June 18 2026. All Gemini model work — including cost-efficient older models — routes throughagy.
Model Strategy: Flash by Default, Pro for Deep Reasoning
See
references/agy-models.jsonfor the full model catalog, cost tiers, and strategy field.
# Default (Flash — faster, cheaper/token, optimized for agentic/coding tasks)
python ./scripts/run_agent.py <PERSONA> <INPUT> <OUTPUT> "<INSTR>" --cli agy
# ↑ run_agent.py loads gemini-3.5-flash from references/cheapest_models.json
# Explicit Low thinking (recommended for CLI loops to control Thought Preservation cost)
python ./scripts/run_agent.py <PERSONA> <INPUT> <OUTPUT> "<INSTR>" --cli agy --model "Gemini 3.5 Flash (Low)"
# Pro — escalate for deep reasoning / architecture decisions
python ./scripts/run_agent.py <PERSONA> <INPUT> <OUTPUT> "<INSTR>" --cli agy --model gemini-3.1-pro
Flash vs Pro: Which to Use
| Gemini 3.5 Flash | Gemini 3.1 Pro | |
|---|---|---|
| Price (in/out per 1M) | $1.50 / $9.00 | $2.00 / $12.00 |
| Speed | 4× faster | Baseline |
| Agentic tool use / MCP / terminal | Best | Good |
| Coding (edit-test loops) | Best | Better for final review |
| Deep abstract reasoning | Good | Best |
| Architecture planning | Good | Best |
| Max output tokens | 65,536 | 32,768 |
Default: Flash. Use Pro only when the task requires deep multi-step reasoning or expert-level judgment.
Thinking level note: Flash with High thinking can inflate tokens via Thought Preservation. Use Low thinking level for high-frequency CLI dispatch loops.
Minimal Working Pattern
agy --dangerously-skip-permissions --model "Gemini 3.1 Pro (Low)" -p "$(cat agents/persona.md)
---SOURCE CODE---
$(cat target.py)
---INSTRUCTION---
Perform a full code review. Use severity levels: 🔴 CRITICAL, 🟡 MODERATE, 🟢 MINOR.
You are operating as an isolated sub-agent.
Do NOT use tools. Do NOT access filesystem." > review.md
Orchestration Pattern: run_agent.py
python ./scripts/run_agent.py <PERSONA_FILE> <INPUT_FILE> <OUTPUT_FILE> "<INSTRUCTION>" --cli agy
run_agent.py calls agy --dangerously-skip-permissions -p and streams output live to stdout and the output file simultaneously. Loads model from references/cheapest_models.json (currently gemini-3.1-pro).
Health Check
agy -p "HEARTBEAT CHECK: Respond with HEARTBEAT_OK only."
# or via run_agent.py:
python ./scripts/run_agent.py /dev/null /dev/null ./heartbeat.md "HEARTBEAT CHECK: Respond HEARTBEAT_OK only." --cli agy
grep -q "HEARTBEAT_OK" ./heartbeat.md && echo "OK" || echo "FAIL"
Example
python ./scripts/run_agent.py agents/security-auditor.md target.py security.md \
"Find vulnerabilities. Use severity levels: 🔴 CRITICAL, 🟡 MODERATE, 🟢 MINOR." --cli agy
Available Models
| Display Name (agy models) | --model ID |
Thinking | Rec |
|---|---|---|---|
| Gemini 3.5 Flash (Low) | gemini-3.5-flash-low |
Low | Best for CLI loops — cheapest, fastest |
| Gemini 3.5 Flash (Medium) | gemini-3.5-flash |
Medium | Default — standard dispatch |
| Gemini 3.5 Flash (High) | gemini-3.5-flash-high |
High | Single-shot deep tasks only |
| Gemini 3.1 Pro (Low) | gemini-3.1-pro |
Low | Deep reasoning, architecture |
| Gemini 3.1 Pro (High) | gemini-3.1-pro-high |
High | Most demanding reasoning only |
| Claude Sonnet 4.6 (Thinking) | claude-sonnet-4.6-thinking |
— | Anthropic quality via agy |
| Claude Opus 4.6 (Thinking) | claude-opus-4.6-thinking |
— | Critical tasks only |
| GPT-OSS 120B (Medium) | gpt-oss-120b |
Medium | OpenAI OSS via agy |
Full pricing data and strategy field:
references/agy-models.json
Persona Registry (agents/)
| Persona | Use For |
|---|---|
security-auditor.md |
Red team, vulnerability scanning, threat modeling |
refactor-expert.md |
Optimizing code for readability, performance, and DRY |
architect-review.md |
Assessing system design, modularity, and complexity |
CLI Flags Reference
| Flag | Purpose |
|---|---|
-p "prompt" / --prompt "prompt" |
Pass prompt non-interactively |
--model <id> |
Select model (see table above) |
--dangerously-skip-permissions |
Headless mode — skip all permission prompts |
--sandbox |
Run in sandboxed environment |
CLI Best Practices
Path
agy is typically at /opt/homebrew/bin/agy. Confirm with which agy.
Avoid Shell Expansion for Large Contexts
$(cat ...) > 10KB can silently fail. run_agent.py writes to a temp file automatically.
Backgrounding & TTY (SIGTTIN)
nohup agy --dangerously-skip-permissions -p "..." >> log.txt 2>&1 < /dev/null &
< /dev/null is required to prevent SIGTTIN stops in background processes.
Smoke Test
agy -p "hello"
python ./scripts/run_agent.py agents/refactor-expert.md target.py output.md "Refactor this code." --cli agy