Control your Mac's awake mode from a terminal or an AI agent.
cpsm is the command-line companion to Capsomnia.
Set one-shot timers, inspect state, change settings, or sleep your Mac when work
is finished. The included capsomnia Skill teaches agents the commands and their
sleep semantics.
日本語 · Command reference · Release guide
v0.1.2 is the current public release (November 13, 2026) and requires Capsomnia 4.0.0+. This is the first CLI-compatible Capsomnia release line.
Download cpsm CLI & Skill · Download Capsomnia Tools
Open the cpsm.pkg.
It installs /usr/local/bin/cpsm and
installs one shared Skill for Codex and Claude Code at
~/.agents/skills/capsomnia/, with ~/.claude/skills/capsomnia linked to it.
There are no agent destination choices. Restart the agent session afterward. You can also
copy the Skill folder to another compatible agent yourself.
The CLI supports Apple silicon and Intel on macOS 13.5+. Capsomnia.app and its helper must already be installed. The app's packaged release requires Apple silicon/macOS 14+; Intel users can build the app from source on macOS 13.5+. The CLI runs as your normal user, without sudo.
The cpsm v0.1.2 release also provides
Capsomnia-Tools.pkg,
combining cpsm, MacReady and both shared Skills. MacReady reads Mac conditions
without needing the app and is also available as an independent
MacReady release.
Capsomnia's Advanced Settings → CLI & Skill links to the same Tools package.
cpsm status --json
cpsm settings get
cpsm doctor --jsonValid commands start Capsomnia if needed. Help, version and invalid commands do
not launch it. The default app path is /Applications/Capsomnia.app. For a
source install, use cpsm --app "$HOME/Applications/Capsomnia.app" status --json.
cpsm timer set 2h
cpsm timer status --json
cpsm timer canceltimer set enables awake mode and replaces the current timer without changing
the saved default. Cancel leaves the current awake state unchanged. Timer
expiry requests sleep. The saved default returns on the next OFF→ON transition;
one-shot settings end when the app quits.
cpsm off includes Mac sleep. Capsomnia turns Caps Lock off, confirms sleep
prevention has been released, then asks macOS to sleep. toggle also sleeps when
its target is off. Regular GUI off retains its existing normal-sleep behavior.
After installing the Skill, ask your agent to “keep this Mac awake for two hours” or “show Capsomnia's remaining timer.” The Skill reports observed results and avoids replaying power commands after a timeout with an unknown outcome.
Requires Xcode 15+ / Swift 5.9+. From this repository:
swift build -c release --product cpsm
swift test
.build/release/cpsm help
SKIP_SIGNING=true ./scripts/build-pkg.shThe package script builds universal binaries by default. See the release guide
for the release build and verification workflow.
Building the combined Tools package requires a sibling MacReady checkout;
./scripts/build-tools-pkg.sh places its standalone output in that checkout's
dist directory and writes the combined package and Tools-SHA256SUMS.txt to
this repository's dist directory.
CapsomniaControl is also a library product. Capsomnia vendors a versioned
snapshot of it so each repository builds independently.
Delete the CLI and the shared Skill:
sudo rm /usr/local/bin/cpsm
sudo rm /usr/local/share/cpsm/LICENSE
sudo rmdir /usr/local/share/cpsm
rm -r ~/.agents/skills/capsomnia
rm ~/.claude/skills/capsomniaThe app, preferences and MacReady remain installed. Removing the CLI does not release awake mode; use the app to restore normal sleep first if needed.
Built by Taketo Fujimaki.
- Capsomnia: the Mac app behind cpsm.
- MacReady: Mac power, battery, thermal, lid and display state as JSON. It is independently usable and does not require Capsomnia.
- Contact for feedback or collaboration.
MIT licensed. See LICENSE and SECURITY.md.