pi-kde-wakelock

KDE sleep inhibitor extension for pi. Prevents suspend (and optionally screen lock) while agent or subagent sessions are running.

Quick Start

Prerequisites

• pi coding agent
• KDE desktop (XDG_CURRENT_DESKTOP=KDE)
• kde-inhibit from kde-cli-tools (falls back to systemd-inhibit if unavailable)

Install

# Global install (writes to ~/.pi/agent/settings.json)
pi install npm:pi-kde-wakelock

# Project install (writes to .pi/settings.json, shareable with your team)
pi install -l npm:pi-kde-wakelock

The extension loads automatically on pi startup — no extra configuration needed.

Try without installing:

pi -e npm:pi-kde-wakelock

Use

# Default: inhibit suspend while agents run
pi

# Also inhibit screen saver / screen lock
pi --wakelock-screen

# Or set a persistent default via environment variable
export PI_WAKELOCK_INHIBIT_SCREEN=1
pi

Verify

# Inside a pi session
/wakelock

# From another terminal while an agent is running
pgrep -af "kde-inhibit.*sleep infinity"

Update / Remove

pi update npm:pi-kde-wakelock
pi remove npm:pi-kde-wakelock

What's Included

pi-kde-wakelock/
├── extensions/
│   ├── index.ts                 # Extension entry (events, flag, /wakelock)
│   └── wakelock/
│       ├── config.ts            # Constants, flag/env resolution, command builder
│       ├── environment.ts       # Detect kde-inhibit / systemd-inhibit
│       ├── inhibitor.ts         # Long-running inhibit subprocess
│       ├── manager.ts           # Reference-counted acquire/release
│       └── types.ts             # Readonly type definitions
├── docs/
│   └── engineering/
│       └── kde-wakelock.md      # Agentic engineering notes
├── package.json                 # Pi manifest (extensions only)
├── tsconfig.json                # Type checking (dev)
├── biome.json                   # Lint/format (dev)
├── CHANGELOG.md
├── LICENSE
└── README.md

Package Structure

Pi packages can contain any combination of these resources:

Extensions (extensions/)

wakelock — Prevents KDE from suspending while any agent or subagent is running. Uses kde-inhibit --power (falls back to systemd-inhibit) for the duration of each agent run; the lock is released automatically when the agent finishes.

• /wakelock — show lock status in the current pi session
• --wakelock-screen — also inhibit screen saver / screen lock (KDE only)
• PI_WAKELOCK_INHIBIT_SCREEN=1 — persistent default for screen inhibition

pi -e pi-kde-wakelock
pi -e pi-kde-wakelock --wakelock-screen

See docs/engineering/kde-wakelock.md for design details.

Learn More

• kde-inhibit
• systemd-inhibit

License

MIT