hera-agent-unity AGENTS.md

hera-agent-unity — Guide for AI Agents

You are an AI coding agent operating in a Unity project that has hera-agent-unity available as a CLI. This document tells you how to use it efficiently. It is meant to be loaded into your project's rules file so every session has it without spending tokens to discover it.

Where to put this content. AGENTS.md at the project root is the canonical cross-tool agent rules file, standardized by the Agentic AI Foundation (AAIF) under the Linux Foundation (Dec 2025) and adopted by 60,000+ open-source repositories. OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, and 30+ tools read this file by default.

For multi-tool projects, the cleanest pattern is AGENTS.md as the single source of truth plus a one-line stub in tool-specific paths. Tool-specific files only matter when a tool requires a different format (Cursor's .mdc YAML frontmatter is the main case).

Recommended layout — multi-tool projects:

1. Drop the full guide (or its lean subset) into AGENTS.md at the project root.
2. For tools that need their own format, drop a short stub that defers to AGENTS.md:
   • CLAUDE.md → > See AGENTS.md. (Claude Code reads AGENTS.md natively since late 2025)
   • .cursor/rules/hera-agent-unity.mdc → frontmatter + the same body (Cursor also supports plain AGENTS.md as a fallback)
   • .github/copilot-instructions.md → repository-wide pointer to AGENTS.md (Copilot uses nearest-file precedence; .github/skills/ is for Agent Skills)
   • GEMINI.md + .agents/agents.md + .agents/skills/hera-agent-unity/SKILL.md → AntiGravity project entry + workspace handoff + on-demand skill
   • .continuerules → identical body

Per-tool target paths (2026-current):

Tool	Canonical path	Notes
OpenAI Codex / AGENTS.md-aware tools	AGENTS.md	Cross-tool standard. Supports layering: ~/.codex/AGENTS.md → repo root → subtree → AGENTS.override.md.
Claude Code	AGENTS.md (or CLAUDE.md)	Reads AGENTS.md natively. CLAUDE.md still works for path-scoped rules and imports.
Cursor	.cursor/rules/*.mdc	YAML frontmatter required for activation. .cursorrules (single-file) is deprecated and ignored by Agent mode.
GitHub Copilot	.github/copilot-instructions.md	Nearest-file precedence. Optional: .github/instructions/*.instructions.md with applyTo frontmatter; .github/skills/ for Agent Skills.
Google AntiGravity	GEMINI.md, .agents/agents.md, .agents/skills/*/SKILL.md	.agents/ is the native workspace extension directory for agents, workflows, and skills.
Continue.dev	.continuerules	Plain markdown.
Other	Tool-specific rules file	Most accept plain markdown.

Two ways to populate the target file:

1. Static — copy the matching stub from examples/rules/ (one file per tool, already formatted).
2. Dynamic — let the CLI generate it from this guide:

   # AGENTS.md / CLAUDE.md / Copilot / Continue.dev — compact always-loaded rules
   hera-agent-unity doctor --agent-rules --compact >> AGENTS.md
   
   # Cursor — compact rules with activation frontmatter
   hera-agent-unity doctor --agent-rules --compact --format cursor > .cursor/rules/hera-agent-unity.mdc
   
   # AntiGravity — compact project entry + full on-demand skill
   hera-agent-unity doctor --agent-rules --compact >> GEMINI.md
   hera-agent-unity doctor --agent-rules --format antigravity > .agents/skills/hera-agent-unity/SKILL.md
   

hera-agent-unity is a CLI that drives a running Unity Editor over HTTP. Common uses: execute C# inside the Editor, read console logs, query the active scene, run tests, capture screenshots, batch several commands in one round-trip. Each call is a tool round-trip; response bytes become your input tokens, so reads cost as much as your own writes.

Quick links:

• Full command catalog → docs/COMMANDS.md
• Architecture → docs/ARCHITECTURE.md
• Custom tool authoring → hera-agent-unity help custom-tools
• Setup / install → README