Guide
Connect your AI tools
Connected tools tell Neurova Awake when they start and finish, so your Mac stays awake only while an agent is working, and sleeps the rest of the time.
On this page
How it works
Most AI coding tools can run a small command when a prompt starts and when it ends. These are
called hooks. When you connect a tool, Neurova Awake adds two or three of these hooks to the
tool’s own settings file. They send the app a hold when the tool starts working and a
release when it’s done.
The ChatGPT and Claude desktop apps don’t have hooks, so for those Neurova Awake keeps the Mac awake while the app is open.
| Tool | How the app knows it’s working |
|---|---|
| Claude Code, the CLI and the Code tab in the Claude app | Hooks: the start and end of each run |
| GitHub Copilot, Copilot CLI | Hooks: the start and end of each run |
| ChatGPT, the desktop app | While the app is open |
| Cursor, the editor | Hooks: the start and end of each run |
| OpenAI Codex, the Codex CLI | Hooks: the start and end of each run |
| Claude, the desktop app, for chat and Cowork | While the app is open |
| Gemini CLI | Hooks: the start and end of each run |
Connect a tool
- Open Settings, then Connections (or use step 3 of setup).
- Click Connect… next to the tool.
- A folder window opens on the tool’s settings folder, such as
.claudein your home folder. Click Allow. Mac App Store apps can only change folders you choose, so this click is the permission. You only do it once per tool. - The app saves a backup of the settings file, adds its hooks and shows Connected.
- Restart the tool if it’s running: tools that are already open only pick up new hooks after a restart.
Click Test to check it: the Mac stays awake for two minutes as if the tool were working, and the tool appears under Active holds in the menu.
The folder doesn’t exist yet? The window says so. Open the tool once so it creates its folder, then click Reconnect.
Disconnect
Click Disconnect. The app saves a backup, removes only its own hooks (the lines that contain
neurova-awake://) and leaves the rest of the file as it was. It also forgets the folder
permission.
Removing Neurova Awake from your Mac? Disconnect each tool first, so no hooks are left behind.
If you forgot, delete the lines containing neurova-awake:// by hand, or the block between the
# >>> neurova-awake >>> markers in Codex’s config.toml. A hook left behind does nothing
without the app.
The tools
Claude Code
The Claude Code CLI and the Code tab in the Claude app.
| Folder | ~/.claude |
| File | settings.json |
| Hooks | UserPromptSubmit holds; Stop and SessionEnd release |
GitHub Copilot
The Copilot CLI. Restart Copilot CLI after connecting so it loads the hooks.
| Folder | ~/.copilot |
| File | hooks/neurova-awake.json, the app’s own file (removed again on Disconnect) |
| Hooks | userPromptSubmitted holds; agentStop and sessionEnd release |
For agent mode in VS Code, add a trigger instead: While an app is open…, and choose Visual Studio Code.
ChatGPT
The ChatGPT desktop app. Switch it on in Connections: the Mac stays awake while the app is open. No file is changed. Cloud tasks such as agent mode and deep research run on OpenAI’s servers, so they don’t need your Mac awake.
Cursor
The agent in the Cursor editor. The Cursor CLI’s hooks don’t fire reliably yet, so the editor is the supported way.
| Folder | ~/.cursor |
| File | hooks.json |
| Hooks | beforeSubmitPrompt holds; stop and sessionEnd release |
OpenAI Codex
The Codex CLI. Codex asks you to approve new hooks once: type /hooks in Codex and trust the
Neurova Awake hooks.
| Folder | ~/.codex |
| File | config.toml, one block between # >>> neurova-awake >>> and # <<< neurova-awake <<< |
| Hooks | UserPromptSubmit holds; Stop and SessionEnd release |
Hooks have to be allowed in your Codex settings: if config.toml says hooks = false under
[features], the app tells you to turn them on first.
Claude
The Claude desktop app, for chat and Cowork. Switch it on in Connections: the Mac stays awake while the app is open. Its Code tab is covered by the Claude Code connection.
Gemini CLI
| Folder | ~/.gemini |
| File | settings.json |
| Hooks | BeforeAgent holds; AfterAgent and SessionEnd release |
Anything else
Any tool or script that can run a command can hold the Mac awake with a neurova-awake://hold
link and let go with release. Link scheme.
When the Mac sleeps again
Two settings in Settings, then Lid & safety, under AI tools:
- Stay awake after an AI tool finishes, 3 minutes by default (0 to 30). A quick follow-up prompt in that time carries straight on. The tool shows finishing under Active holds meanwhile.
- Give up on a silent AI tool after, 4 hours by default (1 to 24). A safety net for a tool that crashes before it says it’s done. It counts from the start of each prompt, so if one prompt often runs longer than 4 hours, raise it.
Several runs at once, in different terminals or tools, each hold the Mac on their own: one finishing never ends another.
Your settings files
- Before every change the app copies the file to
<file>.neurova-awake-backupnext to it, for example~/.claude/settings.json.neurova-awake-backup. Each new change overwrites that backup. - JSON files are saved neatly formatted with their keys in alphabetical order. Your settings stay the same; only the layout of the file changes.
- The app won’t touch a file it can’t read safely, such as JSON with comments in it. It shows what’s wrong next to the tool, and you click Reconnect once it’s fixed. Every message explained.
- The files never leave your Mac.
Last updated 18 November 2026
Can't find it here? See Support and FAQ or email support@neurova-ai.com. We reply by email, usually within two working days.