macctl
npx machina-cli add skill lu-zhengda/macos-toolkit/macctl --openclawFiles (1)
SKILL.md
6.7 KB
macctl — macOS Environment Controller
Show power and environment status:
!macctl power status 2>&1 || echo "macctl not installed — brew install lu-zhengda/tap/macctl"
Analyze the output above. Report battery level, charging state, and health. Offer to check thermals with macctl power thermal, adjust display with macctl display, or apply a preset with macctl preset.
Commands — Power
| Command | Purpose | Example |
|---|---|---|
macctl power status | Battery %, health, cycles, charging, time remaining | macctl power status |
macctl power health | Design vs max capacity, condition, age | macctl power health |
macctl power thermal | CPU/GPU temp, thermal pressure, fans | macctl power thermal |
macctl power assertions | What is preventing sleep | macctl power assertions |
macctl power hogs | Top energy consumers | macctl power hogs |
macctl power history | Battery/thermal trends from persistent store | macctl power history --last 7d |
macctl power record | Capture power snapshot (for lanchr agent periodic recording) | macctl power record |
Commands — Disk
| Command | Purpose | Example |
|---|---|---|
macctl disk status | SSD health: model, wear level, SMART status | macctl disk status |
macctl disk io | Current read/write MB/s and IOPS | macctl disk io |
macctl disk history | SSD wear trends over time | macctl disk history --last 30d |
macctl disk record | Capture disk health snapshot (for lanchr agent) | macctl disk record |
Commands — Events
| Command | Purpose | Example |
|---|---|---|
macctl events | Power-related events: wake, sleep, lid, thermal, power source | macctl events |
macctl events --last <duration> | Filter events by time window | macctl events --last 1h |
macctl events --type <type> | Filter by event type | macctl events --type wake |
macctl events --json | JSON output for scripting | macctl events --json |
Event types: wake, sleep, lid, thermal, power_source
Events are automatically deduplicated — consecutive same-type events within 30s are collapsed with a count.
Commands — Display
| Command | Purpose | Example |
|---|---|---|
macctl display list | Connected displays with resolution, refresh, profile | macctl display list |
macctl display resolution | Get current resolution | macctl display resolution |
macctl display resolution <WxH> | Set resolution | macctl display resolution 1920x1080 |
macctl display brightness | Get current brightness | macctl display brightness |
macctl display brightness <0-100> | Set brightness | macctl display brightness 70 |
macctl display nightshift [on|off] | Toggle Night Shift | macctl display nightshift on |
macctl display truetone [on|off] | Toggle True Tone | macctl display truetone on |
Commands — Audio
| Command | Purpose | Example |
|---|---|---|
macctl audio list | List input and output devices | macctl audio list |
macctl audio output | Get current output device | macctl audio output |
macctl audio output <device> | Switch audio output | macctl audio output "AirPods Pro" |
macctl audio input | Get current input device | macctl audio input |
macctl audio input <device> | Switch audio input | macctl audio input "MacBook Pro Microphone" |
macctl audio volume | Get current volume | macctl audio volume |
macctl audio volume <0-100> | Set volume | macctl audio volume 50 |
macctl audio mute [on|off|toggle] | Control mute | macctl audio mute toggle |
macctl audio test | Play test tone and mic check | macctl audio test |
Commands — Focus
| Command | Purpose | Example |
|---|---|---|
macctl focus status | Current focus mode and DnD state | macctl focus status |
macctl focus on [mode] | Enable a focus mode | macctl focus on "Do Not Disturb" |
macctl focus off | Disable current focus mode | macctl focus off |
macctl focus list | List configured focus modes | macctl focus list |
Commands — Presets
| Command | Purpose | Example |
|---|---|---|
macctl preset <name> | Apply a compound preset | macctl preset deep-work |
Compound Presets
Presets span all four domains in a single command:
| Preset | Display | Audio | Focus | Notes |
|---|---|---|---|---|
deep-work | Dim to 50% | Mute | DnD on | Minimize distractions |
meeting | No change | AirPods + unmute | DnD on (allow calls) | Ready for calls |
present | Mirror 1080p, 100% brightness | Speakers | DnD on | Presentation mode |
chill | Dim to 40%, Night Shift on | Volume 30% | DnD off | Relaxed evening |
battery-saver | Dim to 30% | Mute | No change | Extend battery life |
Example workflow:
# Start a focused coding session
macctl preset deep-work
# Switch to a meeting
macctl preset meeting
# Done for the day
macctl preset chill
JSON Output
Add --json to any read command for machine-readable output:
macctl power status --json
macctl power thermal --json
macctl power history --json
macctl disk status --json
macctl disk io --json
macctl disk history --json
macctl events --json
macctl display list --json
macctl audio list --json
macctl focus status --json
macctl focus list --json
Safety Guidelines
- Presets are reversible: Apply another preset or manually adjust individual settings
- Brightness changes are immediate: Display brightness adjusts instantly
- Audio routing affects all apps: Switching output device redirects all audio
- Focus mode respects system config: Focus presets use modes configured in System Settings
- Resolution changes may flash: Screen may briefly flash when changing resolution
TUI Mode
Launch macctl without arguments for an interactive environment dashboard.
Source
git clone https://github.com/lu-zhengda/macos-toolkit/blob/main/skills/macctl/SKILL.mdView on GitHub Overview
macctl is a macOS environment controller that surfaces power and environment status and lets you adjust display, audio routing, focus settings, and presets for meetings or presentations. It reports battery health, thermal data, display details, audio devices, and SSD health, then applies quick changes with simple commands.
How This Skill Works
macctl exposes categorized commands (power, disk, display, audio, events) to query sensors and perform changes. You run subcommands to retrieve status or apply settings, and some outputs can be streamed or reformatted for scripting. The toolkit supports presets and status reports across power, display, audio, and focus-related features.
When to Use It
- Check battery level, charging state, and health before a trip or heavy task
- Inspect CPU/GPU temperatures and thermal status during long builds or rendering
- Adjust display brightness or change resolution for presentations or editing
- Toggle Night Shift, enable Do Not Disturb, or switch Focus modes for work sessions
- List displays or audio devices to troubleshoot I/O or prepare a setup
Quick Start
- Step 1: macctl power status
- Step 2: macctl power thermal (optional for temps) or macctl display brightness 70
- Step 3: Apply a preset, e.g., macctl preset deep_work (or macctl preset meeting)
Best Practices
- Always start with macctl power status to establish baseline battery health and charging state
- Use macctl power thermal before intensive tasks to anticipate thermal throttling
- Adjust display with macctl display brightness or resolution for precise control
- Leverage presets (deep_work, meeting, presentation) to apply multiple settings consistently
- Combine status commands with disk and events queries to diagnose sleep or performance issues
Example Use Cases
- macctl power status
- macctl display brightness 70
- macctl display list
- macctl events --json
- macctl preset meeting
Frequently Asked Questions
Add this skill to your agents
