Guide

Hooks in every AI coding agent: Claude Code, Cursor, Gemini CLI, GitHub Copilot, Kiro and Factory Droid (2026)

Where do hooks go in each AI coding agent, and how does a hook block a command?

Claude Code reads a hooks block in .claude/settings.json, Gemini CLI a hooks block in .gemini/settings.json, Cursor reads .cursor/hooks.json, Factory Droid .factory/hooks.json, GitHub Copilot .github/hooks/*.json and Kiro any JSON file in .kiro/hooks/. Every one sends the event to your script as JSON on stdin. To block a tool call, exit with code 2 in Claude Code, Cursor, Gemini CLI, Factory Droid and the Kiro CLI, or print a deny decision as JSON (Copilot uses permissionDecision, Cursor uses permission).

Also in: 简体中文 · 日本語 · 한국어 · Español · Português (Brasil)

Coding agent settings change often

Get one email a week when a setting, flag or permission rule changes, checked against the vendor docs.

Quick answer: hook file locations

  • Claude Code: a hooks key in .claude/settings.json (project) or ~/.claude/settings.json (user). /hooks shows what is configured.
  • Cursor: .cursor/hooks.json (project) or ~/.cursor/hooks.json (user), with "version": 1. Enterprise and team hooks sit above both.
  • Gemini CLI: a hooks key in .gemini/settings.json (project), ~/.gemini/settings.json (user) or /etc/gemini-cli/settings.json (system).
  • GitHub Copilot: .github/hooks/*.json for the cloud agent and Copilot CLI, plus ~/.copilot/hooks/ for the CLI. "version": 1.
  • Kiro: any .json file in .kiro/hooks/ (workspace) or ~/.kiro/hooks/ (global, CLI V3), with "version": "v1".
  • Factory Droid: .factory/hooks.json (project) or ~/.factory/hooks.json (user). /hooks opens the hooks manager.

How a hook blocks a tool call

  • Claude Code: a PreToolUse hook that exits 2 blocks the action and sends its stderr back as the reason.
  • Cursor: exit 2, or print {"permission": "deny"}. Any other non-zero code fails open unless the hook sets failClosed: true.
  • Gemini CLI: exit 0 and print {"decision": "deny", "reason": "..."} (the preferred way), or exit 2 with the reason on stderr. Other codes only warn.
  • GitHub Copilot: a preToolUse hook prints {"permissionDecision": "deny", "permissionDecisionReason": "..."}. Doing nothing allows the call.
  • Kiro: in the CLI, exit 2 blocks PreToolUse. In the IDE, any non-zero exit blocks a Pre Tool Use hook.
  • Factory Droid: exit 2 in PreToolUse blocks the tool call. Other non-zero codes are logged and Droid continues.

Same idea, different event names

  • Before a tool runs: PreToolUse (Claude Code, Kiro, Factory Droid), preToolUse and beforeShellExecution (Cursor), BeforeTool (Gemini CLI), preToolUse (Copilot).
  • After a tool runs: PostToolUse (Claude Code, Kiro, Factory Droid), postToolUse and afterFileEdit (Cursor), AfterTool (Gemini CLI), postToolUse (Copilot).
  • Session start: SessionStart (Claude Code, Kiro, Factory Droid, Gemini CLI), sessionStart (Cursor, Copilot).
  • Agent finished: Stop (Kiro, Factory Droid), stop (Cursor), agentStop (Copilot).
  • Prompt submitted: UserPromptSubmit (Kiro, Factory Droid), beforeSubmitPrompt (Cursor), userPromptSubmitted (Copilot).

Same hook, four syntaxes

Claude Code: .claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Cursor: .cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-risky.sh",
        "matcher": "rm -rf|curl|wget"
      }
    ]
  }
}

Gemini CLI: .gemini/settings.json

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Kiro: .kiro/hooks/guard-shell.json

{
  "version": "v1",
  "hooks": [
    {
      "name": "Guard shell commands",
      "trigger": "PreToolUse",
      "matcher": "shell",
      "action": {
        "type": "command",
        "command": "./scripts/guard.sh"
      }
    }
  ]
}

Gotchas

  • Gemini CLI stdout must hold only the final JSON. Invalid JSON is treated as allow.
  • Gemini CLI warns before running a project hook whose name or command changed, for example after a git pull.
  • Copilot passes toolArgs as a JSON string, so parse it twice. The cloud agent treats an "ask" decision as "deny" and only loads hooks from the default branch.
  • Cursor project hooks run from the project root and user hooks from ~/.cursor/, so relative script paths differ.
  • Kiro agent prompt actions start a new agent loop and use credits. Shell command actions do not.
  • Factory Droid matchers are case sensitive regex. Use commandRegex to filter Execute calls by the command text.

Full hooks guide for each agent

Get coding agent settings changes by email

When a setting, flag or permission rule in this guide changes, it goes in the weekly AgentAtlas update, checked against the vendor docs. One email a week.

Sources

Claude Code: Automate actions with hooksCursor: HooksGemini CLI: HooksGemini CLI: Hooks referenceGitHub Docs: Hooks referenceGitHub Docs: Use hooks with Copilot CLIKiro Docs: HooksFactory: Hooks

Other guides

How to allow Cursor to run all commands: Run Everything, allowlist and sandboxHow to allow Claude Code to run all commands: permission modes, allow rules and skip permissionsClaude Code permissions: allow, ask and deny rules, rule syntax and allowed toolsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryCLAUDE.md: where it goes, how it loads, and how it works with AGENTS.mdClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call itAdd MCP servers to Cursor with mcp.json: Keep files out of Cursor with .cursorignore: Configure Codex with config.toml: Configure Gemini CLI with settings.json: Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes): Claude Code custom slash commands and skills (SKILL.md): GitHub Copilot custom instructions: Adding MCP servers to GitHub Copilot: Claude Code settings.json: file locations, precedence, and key settingsClaude Code plugins and marketplaces: install, create, and shareGemini CLI extensions and custom commands: Configuring OpenCode with opencode.json: Cline Rules: workspace, global, and conditional rulesKiro steering files: .kiro/steering, inclusion modes, and AGENTS.mdZed agent: instruction files, MCP servers, tool permissions, and ACP agentsCursor CLI: install, headless mode, permissions and CIAider: CONVENTIONS.md, .aider.conf.yml and API keysJunie guidelines, MCP and the Action Allowlist: Amp AGENTS.md, settings.json and MCP: Configure Goose extensions, hints, recipes and permissions: Customize OpenHands with skills, AGENTS.md, setup.sh and MCP: Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCPConfigure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modesCursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codesCursor sandbox: sandbox.json, network allowlist and run modesCursor settings: settings.json, Cursor Settings and the ~/.cursor config filesCursor browser agent: @browser, browser automation and approval modesCursor subagents: .cursor/agents, frontmatter, built-in Explore and BrowserCursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API): Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.mdClaude Code headless mode: claude -p, --output-format json, --bare and CI flagsClaude Code statusline: custom status bar in settings.json with context %, cost and git branchClaude Code /model: switch models, aliasesClaude Code /cost and /usage: check token spend, usage limits and reduce costsClaude Code VS Code extension: install, shortcuts, settings and /ideCodex AGENTS.md: global, project and override instruction files explainedCodex MCP servers: codex mcp add and [mcp_servers] in config.tomlCodex sandbox modes: read-only, workspace-write, danger-full-access and network accesscodex exec: run Codex non-interactively in scripts and CI with JSON outputCodex skills: create SKILL.md, skill folder locations and $skill invocationGEMINI.md in Gemini CLI: context file locations, imports and /memoryGemini CLI MCP servers: gemini mcp add and mcpServers in settings.jsonGemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CIGemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisorcopilot-setup-steps.yml: set up the GitHub Copilot cloudGitHub Copilot CLI permissions: --allow-tool, --deny-tool, --allow-all-tools and trusted directoriesGitHub Copilot custom agents: .github/agents/*.agent.md profiles, tools and frontmatterGitHub Copilot code review settings: automatic PR reviews, rulesets, effort level and approvalsOpenCode MCP Server Setup: Local and Remote Servers in opencode.jsonOpenCode Permissions: Allow, Ask or Deny Bash, Edit and WebfetchOpenCode Custom Agents and Subagents: Markdown Files, Modes and @ MentionsCline MCP Setup: cline_mcp_settings.json for Local and Remote ServersCline Auto Approve and YOLO Mode: Run Commands and Edits Without PromptsCline Skills: SKILL.md Location, Format and Slash Command UseAmp MCP Setup: amp mcp add, amp.mcpServers and Workspace ApprovalAmp AGENTS.md: File Locations, @ Mentions and Glob-Scoped GuidanceAmp Skills: SKILL.md Folders, amp skill add and Search OrderKiro MCP Setup: .kiro/settings/mcp.json, autoApprove and OAuthKiro Hooks: .kiro/hooks JSON, PreToolUse, PostFileSave and StopKiro Permissions: permissions.yaml Allow, Ask and Deny RulesFactory Droid MCP Setup: droid mcp add, mcp.json Locations and /mcpFactory Droid Hooks: hooks.json, PreToolUse Matchers and Exit CodesFactory Droid Custom Droids (Subagents): .factory/droids Markdown FilesJunie MCP Setup: .junie/mcp/mcp.json for CLI and /mcp CommandJunie Brave Mode and Action Allowlist: Auto-Approve Commands in Junie CLIJunie Custom Slash Commands: .junie/commands Markdown Files and Argumentsgoose .goosehints and AGENTS.md: Global and Project Instructionsgoose Permission Modes: GOOSE_MODE auto, approve, smart_approve and chatgoose Recipes: recipe.yaml Format, Parameters and goose run --recipeZed Agent Tool Permissions: Auto-Approve Terminal Commands with tool_permissionsUse Claude, Codex and Gemini CLI in Zed: External Agents and agent_serversZed with Ollama, LM Studio and llama.cpp: Local Model Setup and Context LengthMCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 UpgradeSubagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub CopilotAllow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 moreAdd an MCP server to any AI coding agent: Claude Code, Cursor, Codex, Gemini CLI, VS Code and 8 moreSettings file locations for every AI coding agent: Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, Amp and Factory DroidRules and instruction files in every AI coding agent: .cursor/rules, CLAUDE.md, AGENTS.md, GEMINI.md, Copilot instructions and moreGemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooksGitHub Copilot hooks: .github/hooks/*.json for Copilot CLI and the cloud agentAgent Skills (SKILL.md) in every AI coding agent: Claude Code, Codex, Cline, Amp and OpenHandsHow to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and moreHeadless mode in every AI coding agent: claude -p, codex exec, gemini -p, Cursor agent -p and copilot -p for scripts and CIClaude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict modeSandbox modes in every AI coding agent: Claude Code, Cursor, Codex and Gemini CLI compared

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.