# Nocturnal > Nocturnal keeps a laptop awake with the lid closed while AI agents (or apps the person picks) are working, cuts power use while the lid is shut, and lets the laptop sleep when the work stops. macOS (14+), Windows (10/11) and Linux (systemd). Free. Nocturnal is built to be driven by agents. Everything below works from an MCP client (Claude Code, Codex, the Claude app, Gemini CLI...) or the `nocturnal` command line. ## Connect - macOS: Nocturnal › Settings › Agents (one click per agent), or `nocturnal connect` in Terminal. - Windows / Linux: `nocturnal connect` (adds Nocturnal to Claude Code's ~/.claude.json and Codex's ~/.codex/config.toml, keeping everything else and saving a backup). - Any MCP client: command `nocturnal` (or the app binary with `cli mcp` on macOS), argument `mcp`, transport stdio. - The setup prompt: `nocturnal prompt`, the MCP tool `nocturnal_setup_prompt` (macOS) / `setup_prompt` (Windows, Linux), or https://nocturnal.tools/#ai-h ## MCP tools macOS names start with `nocturnal_`; Windows and Linux use the same names without the prefix. - `nocturnal_status` / `status`: whether closing the lid keeps the machine working and why, battery, hours left lid-closed, agents seen, holds, busiest apps. - `nocturnal_keep_awake` / `stay_awake`: keep awake (also lid closed) until released, for N minutes, or until this session ends. Call before long unattended work. - `nocturnal_release` / `release`: end this session's holds (never anyone else's). - `nocturnal_settings` / `settings`: every setting with value, allowed values, description and safety note. Read before changing anything. - `nocturnal_set_setting` / `set_setting`: change one setting by key. - `nocturnal_power` / `power`: power use now and a list of suspects, each with the setting that fixes it (`setting`, `suggested_value`) and, on macOS, the measured saving. - `nocturnal_power_test` (macOS): with the lid closed, switches each saving off and on and reads the battery controller's whole-Mac figure over full 30-second periods (about 3 to 4 minutes); savings the Mac's own load made unclear are reported as unclear. `screen: true` also measures turning the screen off, which locks the Mac; ask first. - `nocturnal_set_mode` / `set_mode`: off, auto (When Busy), always (optionally for N minutes). - `nocturnal_set_preset` / `set_preset`: max_battery, balanced, full_speed. - `nocturnal_set_app_rule` / `set_app_rule`: one app → leave, slow, pause, default. - `nocturnal_watch_app` / `watch_app`: an app that keeps the machine awake while busy (ffmpeg, Blender, Xcode...). - `nocturnal_energy` / `energy`: busiest apps and what closing the lid does to each. ## Command line ``` nocturnal status [--json] nocturnal settings [--json] nocturnal power [--json] nocturnal power test [--detailed] [--screen] (macOS) nocturnal set nocturnal rule leave|slow|pause|default nocturnal watch nocturnal on [--for 2h] | auto | off nocturnal hold / release nocturnal run -- nocturnal connect [claude|codex] nocturnal prompt nocturnal doctor nocturnal rescue nocturnal wake-at 07:00 | off nocturnal check-in 0|15|30|60 nocturnal event claude-code (run by Claude Code's hooks; reads the hook's JSON on stdin) ``` ## Settings (keys for set / set_setting) - `mode`: auto | on/always | off. - `preset`: max_battery (pause other apps; music, calls and services agents use keep going) | balanced (slow them) | full_speed. - `pause_simulators` (macOS): freeze booted iOS simulators and Xcode previews while closed; skipped during tests. - `screen_off` (macOS, experimental, off by default): switch the built-in screen fully off while closed instead of keeping it dark. If macOS refuses or locks the Mac anyway (some Macs do), Nocturnal switches back to the dark screen and turns this off. Ask the person first. - `shut_down_simulators` (macOS): shut simulators down on close instead of pausing them (frees everything; they don't reopen). - `pause_background_audio` (macOS): freeze background processes holding the speakers open (keeps audio hardware powered). - `low_power`: Low Power Mode / power saver while closed (Windows also turns turbo off on battery; Linux with the optional helper turns turbo off and switches on kernel power saving). - `pause_time_machine` (macOS): pause Time Machine's automatic backups while closed. - `slow_builds` (macOS, experimental, off by default): run the agent's own build tools on efficiency cores while closed. Builds take several times longer. - `check_in_minutes`: 0 | 15 | 30 | 60. While asleep with the lid shut, wake this often for ~25 s to pick up a "wake" sent from the phone. A shut-down laptop can't be woken. - `lock_on_close` (macOS): screen fully off while closed. Biggest single saving, but macOS asks for the password on reopen. Ask the person first. - `battery_floor`: sleep at this % (0 = never). Commands can only raise it. - `heat_guard`: strictest rules when hot, sleep if critical. Commands can only turn it on. - `only_on_power`, `quiet_minutes`, `sleep_when_done`, `claude_app`, `downloads` (macOS), `notify_done`, `done_chime` (macOS), `ntfy_topic`, `menubar`, `live_lid_icon`, `notch_island`, `show_in_dock`, `hotkey`, `appearance` (macOS). The settings file (config.json) can also be edited directly and reloads instantly; edits that would weaken the battery limit or heat guard are undone. ## Claude Code hooks `nocturnal connect` also adds hooks to ~/.claude/settings.json (SessionStart, UserPromptSubmit, Notification, Stop, SessionEnd) that run `nocturnal event`. They tell Nocturnal when Claude Code is working, waiting for the person's approval, or finished, so a quiet two-hour build still counts and a waiting question doesn't look like "done". Other agents are detected from their CPU use and running commands. Disconnecting removes the hooks. ## Phone Settings › Phone › Pair a Phone shows a QR code; each phone gets its own 256-bit key and can be revoked on its own. Phone and computer talk through ntfy.sh (or the person's own relay): topics are derived from the key, every message is AES-256-GCM sealed with the topic name as associated data, and the relay can't read them. The phone page is https://nocturnal.tools/remote/ (add it to the Home Screen); a native iPhone app uses the same protocol. A phone can't loosen the battery limit or the heat guard. ## Rules agents should follow - Hold before long work, release when done. Holds from MCP end when the agent session ends. - Never try to turn off the heat guard, lower the battery limit or allow going below it. Nocturnal refuses; those are the person's calls in Nocturnal's own settings. - "Approve everything" (Claude Code and Codex run without asking) can only be turned on by the person in Nocturnal's own panel or tray menu, never by a command, the phone or the settings file. It ends when the work finishes, at a set time, or when turned off, and the person's own permission settings come back. - Ask before `lock_on_close on` or `nocturnal_power_test` with `screen: true`. - Agents, their process trees and anything a hold is tied to are never slowed or paused. ## Recipes - Set Nocturnal up: follow the setup prompt. - "Why is my battery draining with the lid shut?": call power, apply the fixes for active suspects, then (macOS, lid closed) power test. - Long build or training run: `nocturnal run -- `, or stay_awake with the process id. - Keep a browser task alive: watch_app "Google Chrome", remove it after.