Preventing MacBook from Sleeping with the macOS caffeinate Command

by

Introduction

I once left Claude Code running for a long time and stepped away. When I came back, my MacBook had gone to sleep and the process had stopped. This issue of the MacBook turning off on its own while something is running in the terminal can be solved with a basic macOS command.

1. What is caffeinate?

caffeinate is a command built into macOS. No separate installation is required. As the name suggests, it “caffeinates” your MacBook to prevent it from sleeping.

You could change the settings in System Preferences to “Prevent computer from sleeping,” but then you have to change it back every time. caffeinate prevents sleep only when needed, and automatically reverts to the original settings when the task is finished.

2. Basic Usage — When Starting a New Process

To prevent sleep from the moment you start a terminal task, simply add the command to be executed after caffeinate.

caffeinate -dims claude

This will prevent your MacBook from sleeping while Claude Code is running. When you terminate Claude Code, caffeinate will automatically terminate as well.

You might be wondering what -dims is. These are flags that prevent different types of sleep.

Flag Meaning Description
-d display Prevent display sleep (prevent screen from turning off)
-i idle Prevent system idle sleep (doesn’t sleep even without input)
-m disk Prevent disk sleep
-s system Prevent system sleep (when plugged in)

If you don’t mind the screen turning off and just want to prevent the task from stopping, -i is sufficient.

caffeinate -i claude

3. Applying to an Already Running Process

There are times when you’ve already started running Claude Code and think, “Oh, I didn’t use caffeinate.” In this case, you can open another terminal tab and use the -w flag.

# Run in another terminal tab
caffeinate -dims -w $(pgrep -ox "claude")

-w prevents sleep while a specific process ID (PID) is alive. pgrep -ox "claude" finds the PID of the currently running claude process.

If pgrep finds multiple processes and causes an error, you can use only the -o flag. (Selects only the oldest parent process)

caffeinate -dims -w $(pgrep -o "claude")

4. Using with a Specified Time

If you want to prevent sleep for a specific period, specify the time in seconds with the -t flag.

# Prevent sleep for 2 hours (7200 seconds)
caffeinate -dims -t 7200

5. Practical Usage Examples

You can use this for any long-running task in the terminal, not just Claude Code.

# Large build
caffeinate -i ./gradlew assembleRelease

# Download large file
caffeinate -i wget https://example.com/big-file.zip

# npm install + build
caffeinate -i bash -c "npm install && npm run build"

# Run server
caffeinate -dims node server.js

The key is simple. “Put caffeinate -i in front of any long-running command.” Just remember this.

6. Things to Note

  • Even with caffeinate, your MacBook will go to sleep if you close the lid (clamshell mode). To use it with the lid closed, you need an external monitor + power + keyboard/mouse connected.
  • The -s flag does not work in battery mode. Use the -i flag when using battery power.
  • To end caffeinate, press Ctrl+C in the corresponding terminal.

7. Registering an Alias — When You’re Tired of Typing It Every Time

Typing caffeinate -dims claude every time is a hassle. If you register an alias, caffeinate will be applied automatically even if you only type claude.

Add the following line to ~/.zshrc (~/.bashrc for bash users).

# Add to ~/.zshrc
alias claude='caffeinate -dims claude'

Save and open a new terminal or run source ~/.zshrc to apply the changes.

source ~/.zshrc

From now on, just typing claude will run Claude Code with caffeinate enabled. You don’t have to worry about it anymore.

If you want to run claude purely without caffeinate, you can use the command keyword.

# Run original claude ignoring alias
command claude

Thoughts

It’s a minor thing, but it’s subtly annoying if you don’t know about it. Especially when working with AI like Claude Code for long periods, it’s quite frustrating if the MacBook goes to sleep in the middle and the session is disconnected. Knowing caffeinate can completely prevent this situation. If you register an alias, you can forget about it altogether.

Leave a Comment