Configuration

Hooks are configured in settings.json, not in TABNINE.md. Tabnine CLI merges configurations from multiple layers (highest to lowest precedence):

1. Project settings: .tabnine/agent/settings.json in the project root.

2. User settings: ~/.tabnine/agent/settings.json.

3. System settings: Platform-specific system config directory.

4. Extensions: Hooks defined by installed extensions.

Configuration schema

{
  "hooksConfig": {
    "enabled": true,
    "disabled": [],
    "notifications": true
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "sequential": true,
        "hooks": [
          {
            "type": "command",
            "command": "node $TABNINE_PROJECT_DIR/hooks/validate-write.js",
            "name": "validate-write",
            "description": "Validate file writes before execution",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

hooksConfig fields

Field	Type	Default	Description
enabled	boolean	true	Master toggle for the hooks system. Set to false to disable all.
disabled	string[]	[]	List of hook identifiers to skip. Matches against name if set, otherwise command.
notifications	boolean	true	Show visual indicators when hooks execute.

Hook definition fields

Each event contains an array of hook definitions:

Field	Type	Required	Description
matcher	string	No	A regex for tool events (BeforeTool, AfterTool) or exact string for lifecycle events. Omit to match everything.
sequential	boolean	No	If true, hooks in this group run sequentially. If false (default), they run in parallel.
hooks	array	Yes	An array of hook configurations (see below).

Hook configuration fields

Field	Type	Required	Description
type	string	Yes	Must be "command". No default — hooks without type are silently discarded.
command	string	Yes	The shell command to execute.
name	string	No	A friendly identifier for logs and the disabled list.
description	string	No	A brief explanation of the hook's purpose.
timeout	number	No	Timeout in milliseconds. Default: 60000 (60 seconds).
env	Record<string, string>	No	Additional environment variables to set for this hook.

Matchers

The matcher field controls which specific tools or triggers fire your hook:

• Tool events (BeforeTool, AfterTool): Matchers are regular expressions (e.g., "write_file|replace", "read_.*").

• Lifecycle events: Matchers are exact strings (e.g., "startup" for SessionStart).

• Match all: Omit matcher or set to ".*" to match everything.

Tool naming conventions

• Built-in tools: Match by their name (e.g., read_file, run_shell_command, write_file, replace).

• MCP tools: Follow the pattern mcp_<server_name>_<tool_name>.

Multiple hooks

You can define multiple hooks for the same event. By default they run in parallel; set sequential: true to run them in order:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": ".*",
        "sequential": true,
        "hooks": [
          {
            "type": "command",
            "command": "node ./hooks/validate.js",
            "name": "validate"
          },
          {
            "type": "command",
            "command": "node ./hooks/log.js",
            "name": "log-tool"
          }
        ]
      }
    ]
  }
}

You can also define multiple hook definitions per event with different matchers:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "type": "command",
            "command": "node ./hooks/validate-writes.js"
          }
        ]
      },
      {
        "matcher": "run_shell_command",
        "hooks": [
          {
            "type": "command",
            "command": "node ./hooks/validate-commands.js"
          }
        ]
      }
    ]
  }
}