---
slug: "pi-kde-wakelock"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/leejangthegreat/pi-kde-wakelock@main/README.md"
repo: "https://github.com/leejangthegreat/pi-kde-wakelock"
source_file: "README.md"
branch: "main"
---
# pi-kde-wakelock

KDE sleep inhibitor extension for [pi](https://pi.dev). Prevents suspend (and optionally screen lock) while agent or subagent sessions are running.

## Quick Start

### Prerequisites

- [pi](https://pi.dev) coding agent
- KDE desktop (`XDG_CURRENT_DESKTOP=KDE`)
- `kde-inhibit` from `kde-cli-tools` (falls back to `systemd-inhibit` if unavailable)

### Install

```bash
# 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:

```bash
pi -e npm:pi-kde-wakelock
```

### Use

```bash
# 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

```bash
# Inside a pi session
/wakelock

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

### Update / Remove

```bash
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

```bash
pi -e pi-kde-wakelock
pi -e pi-kde-wakelock --wakelock-screen
```

See [docs/engineering/kde-wakelock.md](https://github.com/leejangthegreat/pi-kde-wakelock/blob/HEAD/docs/engineering/kde-wakelock.md) for design details.

## Learn More

- [kde-inhibit](https://linuxcommandlibrary.com/man/kde-inhibit)
- [systemd-inhibit](https://www.freedesktop.org/software/systemd/man/latest/systemd-inhibit.html)
## License

MIT