{"id":27828,"library":"ghostty-ambient","title":"Ghostty Ambient","description":"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.","status":"active","version":"0.9.0","language":"python","source_language":"en","source_url":"https://github.com/gezibash/ghostty-ambient","tags":["ghostty","terminal-theme","ambient-light","bayesian","macos"],"install":[{"cmd":"pip install ghostty-ambient","lang":"bash","label":"PyPI"},{"cmd":"uv tool install ghostty-ambient","lang":"bash","label":"uv tool"}],"dependencies":[],"imports":[{"note":"AmbientPicker is a class in the picker submodule, not directly in the package.","wrong":"from ghostty_ambient import AmbientPicker","symbol":"AmbientPicker","correct":"from ghostty_ambient.picker import AmbientPicker"},{"note":"Top-level package does not re-export core functions; must import from learning.","wrong":"from ghostty_ambient import learn_and_recommend","symbol":"learn_and_recommend","correct":"from ghostty_ambient.learning import learn_and_recommend"}],"quickstart":{"code":"from ghostty_ambient.picker import AmbientPicker\nimport os\n\n# Instantiate picker with optional environment sensor override\npicker = AmbientPicker(\n    ghostty_config_path=os.path.expanduser(\"~/.config/ghostty/config\"),\n    state_dir=os.path.expanduser(\"~/.local/share/ghostty-ambient\"),\n)\n\n# Get current ambient lux (with fallback)\nlux = picker.get_current_lux()\nprint(f\"Ambient lux: {lux}\")\n\n# Recommend a theme\nrecommendation = picker.recommend()\nprint(f\"Recommended theme: {recommendation}\")","lang":"python","description":"Basic usage: create an AmbientPicker, get lux, and get a theme recommendation."},"warnings":[{"fix":"Upgrade Python to 3.12 or later.","message":"Python 3.12 minimum: ghostty-ambient uses match/case and other 3.12+ features. Will fail on earlier Python versions.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure the binary compiles (requires clang or the built binary). Run 'ghostty-ambient daemon' once to trigger compilation. Alternatively, set sensor backend explicitly.","message":"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.","severity":"gotcha","affected_versions":">=0.8.3"},{"fix":"Use AmbientPicker.get_current_lux() which internally uses the sensor backend with fallback.","message":"Legacy get_lux() is deprecated in favor of the sensor backend. Future versions may remove it.","severity":"deprecated","affected_versions":">=0.8.1"},{"fix":"Ensure the state directory exists and is writable, or set a custom state_dir.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run 'pip install ghostty-ambient' in your current Python environment.","cause":"Package not installed or installed in a different environment.","error":"ModuleNotFoundError: No module named 'ghostty_ambient'"},{"fix":"Use 'from ghostty_ambient.picker import AmbientPicker' instead of 'from ghostty_ambient import AmbientPicker'.","cause":"AmbientPicker is not exposed at the package root.","error":"ImportError: cannot import name 'AmbientPicker' from 'ghostty_ambient'"},{"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'.","cause":"The macOS ALS sensor binary (als) is missing or failed to compile.","error":"RuntimeError: ALS sensor binary not found. Please compile or use legacy fallback."},{"fix":"Run the picker at least once (interactive mode) or call 'learn_and_recommend' with ambient data to initialize the model.","cause":"No user preference data has been collected yet; the Bayesian model hasn't seen any observations.","error":"ValueError: The 'recommend' method requires at least one trained phase."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}