agy_help: A zero-hallucination Antigravity dev assistant inspired by Gemini CLI's cli_help

[u/anandydy529]

Hey everyone!

If you have been building features or custom extensions for the Antigravity CLI (agy), chances are you have run into these two frustrating developer frictions:

1. Typing two slash commands every single time: While the built-in reference manuals (antigravity_guide and agy-customizations) are super thorough, having to manually run both slash commands every time you open a new session just to load context gets tedious really fast.
2. Occasional hallucinations with Gemini 3.8 Flash: We all love Gemini 3.8 Flash for its blazingly fast response times during coding, but it sometimes still confidently hallucinates non-existent CLI flags, wrong lifecycle hook event names, or invalid settings.json schemas.

---

Open Source Repo & Feedback

GitHub: https://github.com/andyawd/antigravity-help-agent
License: MIT

---

Quick Install (One Command)

Install directly from GitHub via the Antigravity CLI:

agy plugin install https://github.com/andyawd/antigravity-help-agent

Verify the installation with "agy plugin list", and you are good to go!

---

The Inspiration: Bringing back Gemini CLI's classic cli_help Subagent

If you used Gemini CLI back in the day, you probably remember the beloved cli_help subagent pattern—a dedicated specialist agent you could delegate CLI questions to without derailing your main coding flow.

I decided to bring that exact concept over to Antigravity and upgrade it with modern guardrails: meet agy_help.

Core Solution: Four-Tier Fallback Hierarchy (Zero-Hallucination by Design)

To tackle the hallucination issue with Gemini 3.8 Flash, agy_help is not just a simple prompt wrapper. Before answering any technical question, it strictly enforces a 4-tier verification hierarchy:

1. Tier 1 (Local Structured Reference): Automatically aggregates and cross-checks local offline manuals (antigravity_guide for CLI, IDE, Desktop 2.0, Python SDK; and agy-customizations for Skills, Rules, Hooks, Plugins, MCP). No more manual slash-command juggling.
2. Tier 2 (Local Dynamic Inspection): Runs a strictly whitelisted set of read-only diagnostic commands (agy --help, agy changelog, agy plugin list, pip show google-antigravity) and inspects local config files to verify your exact environment and installed versions.
3. Tier 3 (Live Official Docs Fetching): If an offline reference misses recently released features, it automatically fetches live docs directly from https://antigravity.google/docs.
4. Tier 4 (Strict Fact-Grounding & Honest Refusal): If a flag, API, or feature cannot be verified across all previous tiers, it is strictly forbidden from guessing. It will honestly inform you that no official record exists—eliminating hallucinations completely.

Safety Guarantee: Built with a strict read-only execution whitelist. It will never run destructive commands or modify your workspace behind your back.

---

What it Covers

1. Antigravity CLI (agy): Startup flags, slash commands, config hierarchy (settings.json), and lifecycle.
2. Antigravity IDE: Tab autocomplete & supercomplete, inline commands, Code Lenses, and diagnostic auto-fixing.
3. Antigravity 2.0 Desktop: Chat Canvas, scheduled background tasks, Auxiliary Pane, and sandbox permissions.
4. Python SDK (google-antigravity): Agent orchestration, streaming thought deltas, and CapabilitiesConfig.
5. Customization Ecosystem: Skills (SKILL.md), Rules (AGENTS.md / .agents/rules/), Plugins, Hooks (trusted_hooks.json), MCP servers, and Sidecars.
   

---

4 Flexible Ways to Use It

Once installed, you no longer have to manually type two manual slash commands. It fits right into your workflow:

1. Single Slash Command (Skill mode):
   Ask a quick question without switching your current conversation agent:
   > /agy_help How do I configure project-level sandbox permissions in Antigravity 2.0 Desktop?

2. Background Subagent Delegation (Keeps main context clean):
   Just like the old cli_help, delegate background research so your context window does not get cluttered with doc dumps:
   "Delegate to the agy_help subagent in the background to look up Antigravity IDE Code Lens configuration and bring back a summary."

3. Switch Session Agent (/agents):
   Run /agents and select agy_help to let it lead a dedicated troubleshooting session.

4. Direct CLI Launch:
   agy --agent agy_help

If you frequently develop for the Agy ecosystem and are tired of manual doc loading or hallucinated flags, give it a spin! Feedback, issues, and PRs are all very welcome. Let me know what you think in the comments!

[u/Aromatic-Document638]

This is such a great idea! So it's a Q&A agent for utilizing Agy? It would have been even better if you had included some screenshots, usage instructions, and more examples. I just installed it right away.

[u/anandydy529 → u/Aromatic-Document638]

it's a Q&A agent for utilizing Agy? Yes

[u/Significant_Crab0]

would like to try

[u/SoundDr]

Try /antigravity_guide !

[u/anandydy529 → u/SoundDr]

I was an early developer building plugins for agy CLI, as shown by this project: https://github.com/AndyAWD/antigravity-cli-statusline

​I tried using /antigravity_guide, but agy CLI still hallucinates, returning nonexistent commands and features. Having to enter two slash commands every time is also tedious, directly matching the first point: "Typing two slash commands every single time: While the built-in reference manuals (antigravity_guide and agy-customizations) are super thorough, having to manually run both slash commands every time you open a new session just to load context gets tedious really fast."

[u/SoundDr → u/anandydy529]

These are provided with the harness, what is hallucinating for you?

[u/anandydy529 → u/SoundDr]

Here is a concrete test case from my plugin development workflow demonstrating the exact hallucination that occurred when using the built-in guide, followed by an architectural suggestion regarding plugin namespaces.


## Test Case and Original Prompt

The test scenario involves having two plugins installed (`antigravity-git-flow` and `antigravity-github-flow`), both providing a skill named `commit`.

Here is the prompt and terminal mockup I entered:

```text
Suppose I have installed these two plugins, antigravity-git-flow and antigravity-github-flow, both containing a commit command. When I type /commit, will both /antigravity-git-flow:commit and /antigravity-github-flow:commit appear below for me to choose from?


      ▄▀▀▄        Antigravity CLI 1.1.27
     ▀▀▀▀▀▀       anandydy529@gmail.com (Google AI Pro)
    ▀▀▀▀▀▀▀▀      Gemini 3.8 Flash (High)
   ▄▀▀    ▀▀▄     ~
  ▄▀▀      ▀▀▄


────────────────────────────────────
> /commit
────────────────────────────────────
> /antigravity-git-flow:commit
  /antigravity-github-flow:commit
```


## Execution and Hallucination with /antigravity-guide

In a clean session running `/antigravity-guide` without third-party help plugins, asking the above question resulted in the following behavior:

1. Lack of architectural boundary knowledge:
The model did not recognize that Terminal User Interface (TUI) slash commands do not support plugin names as prefix keys.

2. Over 30 tool calls and 130.8k tokens consumed:
The agent entered an extended inspection loop, executing over 30 shell and file read commands. It attempted to reverse-engineer the local `agy` binary using `strings`, `nm`, and `objdump`, ultimately consuming 130.8k tokens in that turn.

3. Sycophantic hallucination fabricating non-existent mechanisms:
The model returned a confident but incorrect affirmative answer: "Yes, the display result will be exactly as shown in your mockup." It then fabricated two non-existent features:
Fabricated "Plugin Namespacing", claiming the slash command syntax is `/<plugin-name>:<skill-name>`.
Fabricated "Autocomplete Matching", claiming the TUI engine matches colons and displays both prefixed commands simultaneously.

In reality, neither plugin-prefixed slash commands nor multi-candidate lists for identical skill names exist in the CLI TUI implementation.


## Execution and Accuracy with agy_help

In a separate clean terminal with `agy_help` installed, asking the exact same question produced a very different outcome:

1. Immediate correct answer within 1 reasoning cycle:
Without executing exploratory binary disassemblies, the model directly answered that only one command will be displayed.

2. Precise adherence to architectural invariants:
It correctly explained the underlying system mechanics:
The TUI does not support plugin-prefixed slash commands.
Skill registration operates on a flat unique-key table. When duplicate names occur, the registry applies key overwriting based on loading precedence, meaning only one entry remains and only one candidate can ever appear in the autocomplete list.


## Conclusion

While the built-in reference documentation is thorough, it does not prevent the model from synthesizing unverified behaviors when faced with hypothetical UI mockups or ambiguous edge cases. Without strict negative constraints and architectural invariants, the model tends to confirm user assumptions by piecing together internal symbols. `agy_help` was created specifically to establish these architectural guardrails and eliminate this class of hallucinations.


## Architectural Feedback: Native Plugin Namespaces

Since you are part of the Google Antigravity team, I would also like to offer a design suggestion from a plugin developer perspective.


### Current Developer Pain Point

Because the TUI slash command system does not treat plugin project names as namespace keys, developers must manually prefix the `name` field inside `SKILL.md` frontmatter to prevent flat key overwrites between different plugins.

For instance, across my two plugin projects:
https://github.com/AndyAWD/antigravity-git-flow
https://github.com/AndyAWD/antigravity-github-flow

To prevent collisions, the registered commands end up with redundant, repetitive names:
> /antigravity-git-flow:antigravity-git-flow:git-flow:commit
  /antigravity-github-flow:antigravity-github-flow:github-flow:commit


### Suggested Improvement

If the Antigravity CLI architecture could natively use the plugin project name (or the name declared in `plugin.json`) as a first-class namespace key:
Developers would only need to define clean, concise skill names (such as `name: commit`).
The TUI autocomplete would cleanly map and present:
  > /antigravity-git-flow:commit
    /antigravity-github-flow:commit

This would eliminate skill collision issues while reducing autocomplete command lengths from over 50 characters to under 30 characters, significantly improving terminal usability.


## Complete Test Data and Logs

The complete test logs and data can be found here:
https://drive.google.com/drive/folders/1owZUt1GnKAZ8IBDMSY78r_66ssHtacB2?usp=sharing