Download Neox CLI
Agent

Hooks

Attach your own scripts before and after tool calls, and block when needed. Works with system notifications and tool approval.

Drop in a script

Put a script in your project's .neox/hooks/ or the user-level ~/.neox/hooks/ directory, and Neox runs it at the matching moment:

.neox/hooks/
  pre-tool-call     before a tool runs — can block it
  post-tool-call    after a tool runs
  pre-session       before a session starts
  post-session      after a session ends

Scripts can be .sh / .py / .js, or extension-less. At runtime they receive a JSON payload on stdin (tool name, arguments, etc.) and can read these environment variables: NEOX_HOOK_TYPE, NEOX_TOOL_NAME, NEOX_WORKSPACE, NEOX_SESSION_ID.

The exit code is the verdict:

Exit codeResult
0Allow
1Block this tool call (pre-* only)
2Block, and return the script's output to the agent as the reason

Scripts are killed after 10 seconds without returning.

Match specific tools only

Configure matchers in .neox/settings.json (or ~/.neox/settings.json) instead of spawning a process for every call:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "execute_shell|write_file",
        "hooks": [{ "type": "command", "command": "./guard.sh", "timeout": 10 }]
      }
    ],
    "PostToolUse": []
  }
}

matcher is a regex over tool names; leave it empty to match all. Exit with code 2 to block, or print {"decision":"block","reason":"..."} — the reason is returned to the agent.

Project-level and user-level configs both apply; project-level runs first.

System notifications

Neox notifies you when a background task finishes or the context approaches its limit:

  • macOS — native notifications
  • Linux — notify-send
  • Windows — system toast

To turn them off:

NEOX_OS_NOTIFICATIONS=off

Tool-call approval

When writing files or running shell commands, Neox asks for confirmation based on risk level. Three approval modes:

  • Auto (default) — only critical operations ask for confirmation
  • Manual — confirm everything other than reading
  • Dangerous — nothing asks for confirmation

See Tool use.

Common patterns

  • Run lint before commits; block on failure
  • Record every agent file write into your own audit log
  • Block changes to production directories, returning the reason so the agent picks another path
  • Archive artifacts automatically when a session ends