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

A tiny Pi extension that immediately syncs light/dark theme changes across every Pi session running as the same user.

No polling. No OS detection. No subprocesses. Sessions share one state file and watch it with filesystem events.

## Install

From npm:

```bash
pi install npm:pi-theme-flip
```

Try without installing:

```bash
pi -e npm:pi-theme-flip
```

From this repository:

```bash
npm install
npm run check
pi -e ./src/index.ts
```

Or install/use it as a Pi package from a local path:

```bash
pi install /absolute/path/to/pi-theme-flip
```

## Use

```text
/theme-flip
/theme-flip toggle
/theme-flip dark
/theme-flip light
/theme-flip status
```

`/theme-flip` toggles between Pi's built-in `dark` and `light` themes. Pi extension commands execute immediately while the agent is streaming, without interrupting its turn.

Every loaded session updates from `~/.pi/agent/theme-flip`. New sessions read the same file on startup, and existing sessions recheck it before each prompt in case a filesystem event was missed.

After first install or update, restart existing Pi sessions or run `/reload` once in each idle session.

## External control

Other processes can set every session by atomically replacing the shared state file:

```bash
mkdir -p ~/.pi/agent
printf 'dark\n' > ~/.pi/agent/.theme-flip.tmp
mv -f ~/.pi/agent/.theme-flip.tmp ~/.pi/agent/theme-flip
```

This gives a laptop-side macOS appearance watcher one simple target to update over SSH.

## Behavior

- Shared `dark` flips to `light`; shared `light` flips to `dark`.
- Without shared state, the current session theme determines the first toggle.
- `dark` and `light` force one side in every loaded session.
- `status` reports the current session's active theme.
- Missing or invalid shared state is ignored.
- Non-UI modes no-op.