Ghostty Ambient

0.9.0 verified Sat May 09 auth: no python

Ambient light-aware Ghostty theme selector using Bayesian preference learning. Dynamically adjusts terminal theme based on environmental brightness and warmth via on-device ALS sensor (macOS) or periodic sampling. Uses a Bayesian HMM to learn user preferences over time. v0.9.0 requires Python >=3.12 and relies on a compiled sensor binary (macOS). The CLI provides a picker, daemon mode, and manual set commands.

pip install ghostty-ambient

Common errors

error ModuleNotFoundError: No module named 'ghostty_ambient' ↓

cause Package not installed or installed in a different environment.

fix

Run 'pip install ghostty-ambient' in your current Python environment.

error ImportError: cannot import name 'AmbientPicker' from 'ghostty_ambient' ↓

cause AmbientPicker is not exposed at the package root.

fix

Use 'from ghostty_ambient.picker import AmbientPicker' instead of 'from ghostty_ambient import AmbientPicker'.

error RuntimeError: ALS sensor binary not found. Please compile or use legacy fallback. ↓

cause The macOS ALS sensor binary (als) is missing or failed to compile.

fix

Run 'ghostty-ambient daemon' once to trigger on-demand compilation. Requires clang. Alternatively, set GhosttyAmbient to use legacy get_lux() by passing sensor_backend='legacy'.

error ValueError: The 'recommend' method requires at least one trained phase. ↓

cause No user preference data has been collected yet; the Bayesian model hasn't seen any observations.

fix

Run the picker at least once (interactive mode) or call 'learn_and_recommend' with ambient data to initialize the model.

Warnings

breaking Python 3.12 minimum: ghostty-ambient uses match/case and other 3.12+ features. Will fail on earlier Python versions. ↓

fix Upgrade Python to 3.12 or later.

gotcha macOS ALS sensor binary required for light measurement: On macOS, the sensor binary (als) is compiled on first import. If the binary fails or is not found, the library will fall back to a legacy get_lux() method, which may be inaccurate or unavailable. ↓

fix Ensure the binary compiles (requires clang or the built binary). Run 'ghostty-ambient daemon' once to trigger compilation. Alternatively, set sensor backend explicitly.

deprecated Legacy get_lux() is deprecated in favor of the sensor backend. Future versions may remove it. ↓

fix Use AmbientPicker.get_current_lux() which internally uses the sensor backend with fallback.

gotcha State directory must be writable: The library stores Bayesian model state and theme history in ~/.local/share/ghostty-ambient by default. If the directory is not writable, recommendations fail silently. ↓

fix Ensure the state directory exists and is writable, or set a custom state_dir.

Install

uv tool install ghostty-ambient

Imports

AmbientPicker
wrong
```
from ghostty_ambient import AmbientPicker
```
correct
```
from ghostty_ambient.picker import AmbientPicker
```
AmbientPicker is a class in the picker submodule, not directly in the package.
learn_and_recommend
wrong
```
from ghostty_ambient import learn_and_recommend
```
correct
```
from ghostty_ambient.learning import learn_and_recommend
```
Top-level package does not re-export core functions; must import from learning.

Quickstart

Basic usage: create an AmbientPicker, get lux, and get a theme recommendation.

from ghostty_ambient.picker import AmbientPicker
import os

# Instantiate picker with optional environment sensor override
picker = AmbientPicker(
    ghostty_config_path=os.path.expanduser("~/.config/ghostty/config"),
    state_dir=os.path.expanduser("~/.local/share/ghostty-ambient"),
)

# Get current ambient lux (with fallback)
lux = picker.get_current_lux()
print(f"Ambient lux: {lux}")

# Recommend a theme
recommendation = picker.recommend()
print(f"Recommended theme: {recommendation}")