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

  1. Open Settings, then Connections (or use step 3 of setup).
  2. Click Connect… next to the tool.
  3. A folder window opens on the tool’s settings folder, such as .claude in 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.
  4. The app saves a backup of the settings file, adds its hooks and shows Connected.
  5. 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-backup next 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.