Hooks

# Hook Authoring Guidelines

Hooks are **small, deterministic commands or scripts** that run at specific lifecycle events.

An awesome hook does one clear job, runs quickly, and makes its side effects explicit.

Folder Structure

A GitHub Copilot hook lives in `.github/hooks/` inside your repository:

.github/
└── hooks/
    ├── block-dangerous-commands.json   ← hook config (which event, which script, options)
    └── scripts/
        ├── block-dangerous-commands.sh  ← Bash implementation
        └── block-dangerous-commands.ps1 ← PowerShell implementation (optional if Bash-only)

You can have multiple `.json` files — each one registers hooks for one or more events. The host loads all of them.

The Config File

Each `.json` file maps events to an array of hook entries.

- **Command hooks** (`type: "command"`): run a local script. The host passes event JSON on stdin, your script responds through exit code and stdout.

Config example

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "matcher": "bash",
        "type": "command",
        "bash": "./.github/hooks/scripts/block-dangerous-commands.sh",
        "powershell": "./.github/hooks/scripts/block-dangerous-commands.ps1",
        "cwd": ".",
        "timeoutSec": 5,
        "env": {
          "BLOCK_MODE": "deny"
        }
      }
    ]
  }
}

Config fields

| Field | Required | What it does |

| ---- | ---- | ---- |

| `type` | yes | `"command"` for scripts |

| `matcher` | no | Host-level filter — hook only fires when the tool name matches this value (e.g. `"bash"`, `"powershell"`, `"edit"`, `"create"`). Locally verified working in Copilot CLI v1.0.36; not yet used in repo hook samples. |

| `bash` | one or both | Command line invoked on Unix / Bash-capable hosts |

| `powershell` | one or both | Command line invoked on Windows / PowerShell-capable hosts |

| `cwd` | no | Working directory, relative to repo root |

| `timeoutSec` | no | Max seconds before the host kills the process (default 30) |

| `env` | no | Extra process environment variables passed to the script |

Why matchers matter

Without a matcher, every `preToolUse` hook fires on **every** tool call. Your script starts with boilerplate like:

tool_name="$(printf '%s' "$payload" | jq -r '.toolName')"
[[ "$tool_name" != "bash" ]] && exit 0

With a matcher, the host does this filtering for you — no boilerplate, no process spawn for irrelevant tools. This will likely become the standard pattern once the feature stabilizes.

If your hooks must work on both the CLI and the cloud agent (or on older CLI versions), keep the in-script filtering as a fallback even when using matchers.

`env` — static configuration for your script

`env` is a **standard host field**. The keys inside it are **author-defined variables** — you choose the names and values.

They arrive as **process environment variables**, not inside the stdin JSON payload. Use them for static configuration that should not be hardcoded:

| Pattern | Example |

| ---- | ---- |

| Mode flag | `"BLOCK_MODE": "deny"` — same script logs in one repo, blocks in another |

| Threshold | `"MAX_CHANGED_FILES": "20"` |

| Path | `"AUDIT_LOG_PATH": ".github/logs/hooks.log"` |

| Feature toggle | `"ENABLE_NOTIFICATIONS": "false"` |

`bash` and `powershell` — when to provide one or both

The host picks whichever entry matches the current environment. It does not run both, and does not fall back from one to the other.

| Situation | Provide |

| ---- | ---- |

| Private hook, one known platform | Only that platform's entry |

| Published hook claiming cross-platform support | Both entries |

| Single cross-platform runtime (Python, Node, pwsh) | Expose the same script through both entries |

| Bash-only dependency | `bash` only |

| Windows-only dependency | `powershell` only |

Cross-platform example using Python through both entries:

{
  "type": "command",
  "bash": "python3 ./.github/hooks/scripts/check.p