DeskMode

Terminal-first workspace lifecycle automation for macOS.

DeskMode turns repetitive desktop setup into one command:

deskmode coding
deskmode study
deskmode chill

It can switch wallpapers, change light/dark mode, adjust brightness, open apps, launch URLs, reset running apps, remember the active workspace, and validate your setup.

Why

Switching between coding, studying, and relaxing often means repeating the same small desktop setup steps. DeskMode makes those steps explicit, configurable, and fast.

Features

• Workspace modes with descriptions
• Natural commands like deskmode coding
• Bundled wallpaper packs that work immediately after install
• Wallpaper switching with history and no recent repeats
• Foreground wallpaper rotation with deskmode rotate
• Optional favorite wallpapers
• Dark/light mode automation
• Built-in macOS brightness control, with optional CLI fallbacks
• App and URL launching
• status, doctor, and validate commands
• Interactive mode creation with deskmode create gaming
• Interactive mode editing with deskmode edit coding
• Startup-style profiles: focus, morning, and night in the starter config
• Workspace cleanup with deskmode reset
• Dry-run previews
• Rich terminal UI

Install

DeskMode is macOS-only. Install it directly from GitHub with pipx:

brew install pipx
pipx ensurepath
pipx install git+https://github.com/adhithyapandiri-a11y/deskmode.git

Restart Terminal after pipx ensurepath, or reload your shell:

source ~/.zshrc

Then run:

deskmode init
deskmode doctor
deskmode list
deskmode coding

You can also install with pip:

python3 -m pip install --user git+https://github.com/adhithyapandiri-a11y/deskmode.git

If the deskmode command is not found after a pip --user install, make sure Python's user scripts directory is on your PATH.

For local development or modifying the code:

git clone https://github.com/adhithyapandiri-a11y/deskmode.git
cd deskmode
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
deskmode init
deskmode coding

On first real use, macOS may ask for permission for Terminal or Python to control System Events, open apps, and change desktop settings.

Homebrew tap target:

brew tap adhithyapandiri-a11y/tap
brew install deskmode

Quick Start

deskmode init
deskmode doctor
deskmode list
deskmode coding --dry-run
deskmode coding

Config lives at:

~/.config/deskmode/config.toml

State lives at:

~/.local/state/deskmode/state.json

Commands

deskmode                  # banner and command guide
deskmode --version
deskmode help
deskmode init
deskmode list             # aliases: ls, modes
deskmode packs            # list bundled wallpaper packs
deskmode show coding
deskmode status           # alias: st
deskmode doctor
deskmode validate
deskmode create gaming
deskmode edit coding
deskmode wallpaper coding
deskmode wp coding
deskmode coding --wallpaper-only
deskmode rotate coding --every 5m
deskmode rotate status
deskmode rotate stop
deskmode reset --dry-run
deskmode coding
deskmode coding --dry-run
deskmode coding --clean
deskmode config-path

Config Example

[modes.coding]
description = "Developer-focused dark workspace"
theme = "dark"
brightness = 0.8
apps = ["PyCharm"]
wallpaper_dir = "~/Pictures/DeskMode/coding"
wallpaper_pack = "coding"
favorite_wallpapers = ["coding_03_code-luis-gomes.jpg"]
rotation = "5m"

[modes.chill]
description = "Relaxed entertainment setup"
theme = "dark"
brightness = 0.45
urls = ["https://www.netflix.com"]
browser = "Google Chrome"
wallpaper_pack = "chill"

[modes.focus]
description = "Low-distraction work session"
theme = "dark"
brightness = 0.7
apps = ["PyCharm", "Notes"]
wallpaper_pack = "coding"
focus = true

wallpaper_dir is optional. If both are set, the custom wallpaper_dir wins over wallpaper_pack.

Bundled Wallpapers

DeskMode ships with bundled wallpaper packs:

deskmode packs

Default modes use:

wallpaper_pack = "coding"
wallpaper_pack = "study"
wallpaper_pack = "chill"

That means a fresh install can run deskmode coding without manually downloading wallpapers.

Publishing note: only distribute bundled wallpapers when you have redistribution rights for them. Personal/free wallpaper downloads are not always safe to redistribute through GitHub, PyPI, or Homebrew.

Interactive Creation

Create a custom mode without editing TOML by hand:

deskmode create gaming

DeskMode prompts for:

• description
• theme
• brightness
• wallpaper folder
• apps
• URLs
• preferred browser
• Focus support
• favorite wallpapers

Then it appends the new mode to your config.

Edit an existing mode:

deskmode edit coding

The edit flow keeps current values as defaults and lets you modify apps, URLs, theme, brightness, wallpaper source, focus support, favorites, and rotation.

Wallpaper Rotation

Change only the wallpaper for a mode without opening apps, changing theme, or touching brightness:

deskmode wallpaper coding
deskmode wp study
deskmode chill --wallpaper-only

Start rotation in the background:

deskmode rotate coding --every 1m
deskmode rotate chill --every 5m
deskmode rotate study --every 1h

Check or stop it:

deskmode rotate status
deskmode rotate stop

Supported intervals:

1m, 5m, 1h, 5h, 12h, daily

For debugging or demos, run rotation in the current terminal:

deskmode rotate coding --every 1m --foreground

Stop a foreground run with Ctrl+C.

For quick testing:

deskmode rotate coding --every 1m --count 1 --dry-run

Diagnostics

Use doctor when something feels off:

deskmode doctor

It checks macOS, config health, brightness backends, Shortcuts availability, and configured app paths.

Use validate to inspect config quality:

deskmode validate

It checks wallpaper folders, empty folders, invalid URLs, favorites that do not exist, and other config issues.

Brightness

DeskMode ships with built-in macOS brightness support. It first tries macOS display frameworks directly. If the display refuses direct control, it falls back to macOS keyboard brightness automation, which requires no third-party package.

If macOS blocks the keyboard fallback, allow Automation/Accessibility for your terminal app in System Settings.

BetterDisplay CLI and brightness are still supported as optional fallbacks, but they are not required for DeskMode brightness control.

Focus Mode

For realistic macOS Focus support, create a Shortcut named:

DeskMode Focus

Configure that Shortcut to enable your preferred Focus mode. When a DeskMode mode has:

focus = true

DeskMode will run that Shortcut.

Workspace Reset

deskmode reset gracefully quits non-excluded GUI apps using AppleScript. It keeps core macOS apps and lets you preserve specific apps:

deskmode reset --dry-run
deskmode reset --keep "Terminal,PyCharm"
deskmode coding --clean

Architecture

src/deskmode/
  cli.py            # argparse commands and Rich output
  config.py         # config loading and validation
  config_writer.py  # interactive mode persistence
  validation.py     # config validation checks
  doctor.py         # dependency and environment diagnostics
  app_manager.py    # app exclusion and cleanup selection rules
  cleanup.py        # cleanup planning and quit execution
  errors.py         # CLI-friendly exception hierarchy
  models.py         # typed domain models
  reset_logic.py    # workspace reset orchestration
  runner.py         # mode orchestration
  state.py          # active mode and wallpaper history
  wallpaper.py      # wallpaper discovery and selection
  assets/           # bundled wallpaper packs
  macos.py          # AppleScript/subprocess automation adapter
  status.py         # status snapshot logic

Demo Ideas

Good README screenshots or terminal GIF frames:

• deskmode
• deskmode list
• deskmode status
• deskmode doctor
• deskmode coding --dry-run
• deskmode create gaming

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
python -m unittest discover -s tests

Roadmap

• Homebrew tap formula
• Bundled wallpaper packs
• More robust Focus mode presets
• Optional scheduling
• Multi-monitor wallpaper support

License

MIT