PowerKit-Go

powerkit-go is a Darwin-only Go library for reading and controlling macOS power state through IOKit, SMC, and OS power APIs.

Scope

Use powerkit-go when you need:

• battery, adapter, and charging telemetry
• charging and adapter control where the current macOS build exposes those controls
• MagSafe LED control
• Low Power Mode read/write
• sleep assertion control
• event-driven power, sleep, and wake notifications

This library targets Apple Silicon Macs. Intel behavior is not guaranteed.

Status

• OS: macOS only
• Build tag: //go:build darwin
• cgo required
• Mutating control APIs require root
• Hardware control availability is reported at runtime; newer macOS builds can remove individual SMC control keys.

Install

go get github.com/peterneutron/powerkit-go

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/peterneutron/powerkit-go/pkg/powerkit"
)

func main() {
	info, err := powerkit.GetSystemInfo()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Charge: %d%%\n", info.IOKit.Battery.CurrentCharge)
	fmt.Printf("Charging: %v\n", info.IOKit.State.IsCharging)
}

Public API

Main package: github.com/peterneutron/powerkit-go/pkg/powerkit

Core entrypoints:

• GetSystemInfo(opts ...FetchOptions) (*SystemInfo, error)
• GetSystemInfoContext(ctx context.Context, opts ...FetchOptions) (*SystemInfo, error)
• StreamSystemEvents() (<-chan SystemEvent, error)
• StreamSystemEventsWithHooks(StreamHooks) (<-chan SystemEvent, error)
• StreamSystemEventsContext(context.Context, StreamHooks) (<-chan SystemEvent, error)
• GetRawSMCValues(keys []string) (map[string]RawSMCValue, error)

Control APIs:

• SetChargingState(ChargingAction) error
• SetAdapterState(AdapterAction) error
• SetMagsafeLEDState(MagsafeLEDState) error
• GetMagsafeLEDState() (state MagsafeLEDState, available bool, err error)
• GetMagsafeStatus() (MagsafeStatus, error)
• IsMagsafeCharging() (bool, error)
• IsMagsafeAvailable() bool
• GetLowPowerModeEnabled() (enabled bool, available bool, err error)
• SetLowPowerMode(enable bool) error
• ToggleLowPowerMode() error

Context-aware variants are available for system info and mutating control APIs:

• GetSystemInfoContext(ctx context.Context, opts ...FetchOptions) (*SystemInfo, error)
• SetAdapterStateContext(ctx context.Context, action AdapterAction) error
• SetChargingStateContext(ctx context.Context, action ChargingAction) error
• SetMagsafeLEDStateContext(ctx context.Context, state MagsafeLEDState) error
• SetLowPowerModeContext(ctx context.Context, enable bool) error
• ToggleLowPowerModeContext(ctx context.Context) error

Sleep assertions:

• CreateAssertion(AssertionType, reason string) (AssertionID, error)
• ReleaseAssertion(AssertionType)
• AllowAllSleep()
• IsAssertionActive(AssertionType) bool
• GetAssertionID(AssertionType) (AssertionID, bool)

Event Stream Notes

StreamSystemEventsWithHooks supports a synchronous BeforeSleep hook.

Use it only for short, bounded pre-sleep work. macOS sleep acknowledgement waits for that hook to return. Use StreamSystemEventsContext when the caller needs to cancel the stream and release the singleton hook registration.

Privileges

• Read telemetry: no root required
• Sleep assertions: no root required
• Charging, adapter, MagSafe, and Low Power Mode writes: root required and subject to runtime hardware/OS availability
• SMC-backed context APIs check cancellation before starting hardware calls; Low Power Mode reads use Foundation, while writes use pmset and pass through context cancellation.

Build

go build ./...

Verify

make tests
make vet
make lint
make verify

Hardware-backed integration tests are opt-in:

make integration-tests

Mutating integration tests are skipped unless explicitly enabled and run with privileges:

sudo POWERKIT_WRITE_INTEGRATION=1 go test -tags powerkit_integration ./pkg/powerkit

Docs

Keep the README short. Detailed material lives elsewhere:

• Contract Details
• Release Process

Release Model

• semver tags on master
• additive API changes allowed in patch releases
• breaking API changes require a minor or major bump
• release notes belong in tags and Git hosting releases, not an in-repo changelog

Safety

This library can change charging, adapter, MagSafe LED, and Low Power Mode behavior at the hardware-control layer. Prefer read APIs unless you explicitly need mutation.