Cursor Hooks Relative Path Fails When Using Symlinked .cursor Directory

Support Bug Reports
,
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Problem Description

Environment
OS: macOS
Cursor Version: [your version]
Setup: Using symlink for shared .cursor configuration, hooks are not working.
error: no such file or directory

Steps to Reproduce

Project Structure

Using a symlink to share Cursor configuration across multiple projects:

# .cursor is a symbolic link
/Users/createsun/project/.cursor 
  -> /Users/createsun/cursor-rule-repo

Directory layout:

cursor-rule-repo/
├── hooks.json
└── hooks/
    └── format.sh

Configuration (hooks.json)
Following the official documentation example:

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      {
        "command": "./hooks/format.sh"
      }
    ]
  }
}

Error Message:
no such file or directory: ./hooks/format.sh

Expected Behavior

Cursor Hooks support symlinked directories and relative path resolution work.
or
Is there a better way to share hooks configuration across multiple projects? Other than using absolute paths

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.3.41
VSCode Version: 1.105.1
Commit: 2ca326e0d1ce10956aea33d54c0e2d8c13c58a30
Date: 2026-01-16T19:14:00.150Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 24.6.0

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

3

Hey, thanks for the report!

Relative paths in hooks are resolved relative to Cursor’s working directory, usually the project root, not the actual location of the .cursor directory. When .cursor is a symlink, ./hooks/format.sh resolves to <project>/hooks/format.sh, not <symlink-target>/hooks/format.sh.

A few workarounds:

  1. Use an absolute path. This is the simplest option:

    {
  "command": "/Users/createsun/cursor-rule-repo/hooks/format.sh"
}

  2. Create a symlink to the hooks folder in the project root if you want to avoid absolute paths in JSON:

    ln -s /Users/createsun/cursor-rule-repo/hooks /Users/createsun/project/hooks

    Then ./hooks/format.sh will work.

  3. Put a wrapper script in the project root that calls the real script.

If you’re sharing configs across projects, absolute paths are probably the most reliable option right now. The team knows symlink support could be better, but there’s no ETA yet.