Lifecycle Hooks (hooks.json)

Hooks are hardcoded shell commands triggered automatically by the CLI at specific points in the agent lifecycle. They run outside the model’s discretion and consume 0 tokens.

---

The Kitchen Analogy: Skills vs. Hooks

Why do developers frequently say: “Don’t write a Skill for that, use a Hook instead!”?

Think of kitchen hygiene:

• The Skill Way (AI Thinking):
  You tell the cook: “Please remember to run the linter and format code with Prettier after every single edit.”
  Because AI is probabilistic, the cook might get distracted, forget, or write a syntax error. Plus, the AI burns tokens thinking about formatting rules every turn.
• The Hook Way (Zero-Thinking Automation):
  You install an automated sensor on the sink: the instant a knife hits the dish station, hot water turns on and sterilizes it.
  It requires zero human thought, happens 100% of the time, and costs zero tokens because your computer is simply executing a bash command.

---

The Golden Rule

• Use a Skill when the task requires creative AI reasoning (e.g. debugging a novel crash, designing a component architecture, writing a feature).
• Use a Hook when the task is deterministic and mechanical (e.g. auto-formatting code with Prettier, blocking dangerous shell commands, verifying tests before allowing the agent to exit).

---

Core Lifecycle Events

Event	When It Runs	Common Use Case
PreToolUse	Before a tool executes	Security gate (blocks commands like rm -rf / or drop database).
PostToolUse	After a tool step finishes	Auto-formatter / linter (runs prettier or black immediately after file edits).
PreInvocation	Before the model is called	Injects ephemeral reminders or dynamic context into the prompt.
Stop	When the agent tries to exit	Test gatekeeper (runs pytest; forces agent to keep working if tests fail).

---

Example: .agents/hooks.json

Save in .agents/hooks.json (workspace) or ~/.gemini/antigravity-cli/hooks.json (global):

{
  "auto-formatter": {
    "PostToolUse": [
      {
        "matcher": "replace_file_content|write_to_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ]
  },
  "command-guard": {
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/guard-rail.sh"
          }
        ]
      }
    ]
  },
  "test-enforcer": {
    "Stop": [
      {
        "type": "command",
        "command": "./scripts/verify-tests-pass.sh"
      }
    ]
  }
}

The agent doesn’t need to be told to format code or remember test verifications — your local machine guarantees it automatically!