todo-wallpaper 0.1.0

A CLI todo list that renders as your desktop wallpaper

Todo-Wallpaper

A simple interactive todo list that appears as your Linux desktop wallpaper.

Features

• 📝 Manage todos via simple CLI commands
• 🖼️ Live wallpaper rendering with minimalist design
• 🚀 Automatic startup on login (via systemd)
• 🎨 Clean, readable formatting with blue accent

Architecture

todo-wallpaper/
├── todos.json              # Todo storage (JSON)
├── render.py               # Wallpaper renderer (Pillow)
├── todo.py                 # CLI interface
├── todo                    # Shell wrapper for the global command
├── watch.py                # File watcher (optional daemon)
├── init.py                 # One-command setup

└── wallpaper.png           # Generated wallpaper

Installation

Prerequisites

Ensure you have Python 3 installed:

python3 --version  # Should be 3.7+

Quick Setup (One Command)

cd ~/projects/random/todo-wallpaper
python3 init.py

This will:

1. ✓ Check and install Python dependencies (Pillow, watchdog)
2. ✓ Verify system tools (feh, fonts)
3. ✓ Generate your first wallpaper
4. ✓ Install the todo command into ~/.local/bin
5. ✓ Enable automatic startup on login via systemd

Install via pip (recommended)

Install from PyPI with pip:

pip install todo-wallpaper

After install, run the packaged setup step to enable autostart and install the command wrapper:

todo init

Install via Homebrew (macOS / Linuxbrew)

You can create a Homebrew tap or formula that installs the package; we recommend using the PyPI wheel in the formula. Example (once tap exists):

brew install Yash-Thio/tap/todo-wallpaper

Convenience installer (curl|bash)

If you prefer a single-line installer, you can use the hosted install.sh which wraps a pip install:

curl -sSL https://raw.githubusercontent.com/Yash-Thio/todo-wallpaper/main/install.sh | bash

This script is a thin convenience wrapper around pip install. It supports --dry-run and --system flags.

Manual Setup (advanced)

If you prefer to set up manually from source:

# Install dependencies
pip install Pillow watchdog

# Install system tools
sudo apt install feh fonts-dejavu

# Generate initial wallpaper
python3 render.py

# Make sure ~/.local/bin is on PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Enable autostart (Linux systemd)
mkdir -p ~/.config/systemd/user
cp todo-wallpaper-init.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable todo-wallpaper-init.service

Usage

Adding Todos

todo add "Buy groceries"
todo add "Complete project"

The wallpaper will automatically render and update your desktop.

Listing Todos

todo list

Output:

1: Buy groceries
2: Complete project

Removing Todos

todo remove 1  # Remove first todo
todo remove 2  # Remove second todo

Get Help

todo

Set Up Autostart

todo init

Publishing

Follow these steps to publish releases to PyPI and to test uploads with Test PyPI.

1. Create a PyPI account if you don't have one: https://pypi.org/account/register/

2. Create an API token (recommended) instead of a password:

   • Go to https://pypi.org/manage/account/token/
   • Create a new token scoped to "Upload packages" and give it a descriptive name.
   • Copy the token value once — you won't be able to see it again.

3. Add the token to your GitHub repository as a secret named PYPI_API_TOKEN:

   • Repository → Settings → Secrets and variables → Actions → New repository secret
   • Name: PYPI_API_TOKEN
   • Value: the token you copied from PyPI

4. Test locally with Test PyPI (optional):

python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine upload --repository testpypi dist/*

# Install from Test PyPI to verify the package
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps todo-wallpaper

5. Publish via GitHub Actions (automated):
   • Tag a release and push the tag to GitHub:

git tag v0.1.0
git push origin v0.1.0

• The CI workflow .github/workflows/publish.yml will build the distributions, run a smoke import test, publish to PyPI using PYPI_API_TOKEN, and create a GitHub Release.

Notes

• Keep PYPI_API_TOKEN secret — treat it like a password.
• If you want to test the whole CI flow against Test PyPI, you'll need to adjust the publish action to point at Test PyPI or perform a manual twine upload as shown above.

This enables automatic wallpaper rendering on login via systemd.

Workflow Examples

Daily Routine

# Start your day
todo add "Review emails"
todo add "Team standup"
todo add "Code review"

# Check what's on your plate
todo list

# Mark items as done
todo remove 1  # ✓ emails done
todo remove 1  # ✓ standup done

Batch Operations

Add multiple tasks:

for task in "Fix bug" "Write docs" "Deploy"; do
   todo add "$task"
done

Files Explained

File	Purpose
todos.json	JSON file storing your todo list
render.py	Generates wallpaper PNG from todos.json
todo.py	CLI tool to add/remove/list todos
todo	Shell wrapper for the todo command

| init.py | One-command installation + autostart setup | | wallpaper.png | Generated wallpaper image |

Customization

Colors

Edit render.py:

BACKGROUND = (20, 20, 30)      # Dark blue-gray
TEXT = (240, 240, 240)         # Light white
ACCENT = (120, 200, 255)       # Light blue

Font Size

Edit render.py:

title_font = ImageFont.truetype(..., 54)    # Title (TODO)
font = ImageFont.truetype(..., 36)          # Items

Wallpaper Dimensions

Edit render.py:

WIDTH = 1920
HEIGHT = 1080

Font Path

If you have a different font installed, update render.py:

font = ImageFont.truetype("/path/to/font.ttf", 36)

Find available fonts on Linux:

fc-list | grep -i "font-name"

Troubleshooting

Dependencies missing after todo init

If you see errors about missing tools, install the required system packages:

sudo apt install feh fonts-dejavu

Then run todo init again.

"Font not found"

Ensure fonts-dejavu is installed:

sudo apt install fonts-dejavu
# Or check available fonts:
fc-list | head -20

"Pillow not found"

pip install Pillow

Wallpaper not updating on startup

Check systemd service status:

systemctl --user status todo-wallpaper-init.service
journalctl --user -u todo-wallpaper-init.service -n 20

Want to stop autostart?

systemctl --user disable todo-wallpaper-init.service

Re-enable autostart?

systemctl --user enable todo-wallpaper-init.service

Manual wallpaper render

python3 render.py

Optional: File Watcher

Use watch.py to auto-update wallpaper whenever todos.json changes:

python3 watch.py

This runs a daemon in the foreground. Press Ctrl+C to stop.

Requirements: watchdog package (pip install watchdog)

Tips

1. Keybinding: Create a shell alias for faster access:

   alias todo='python3 ~/projects/random/todo-wallpaper/todo.py'
   # Now use: todo add "task name"
   

2. Full-screen todo view: List all todos in a terminal:

   watch -n 1 'python3 ~/projects/random/todo-wallpaper/todo.py list'
   

3. Regular refresh (if not using watch.py):

   # Add to crontab to refresh every hour
   0 * * * * python3 ~/projects/random/todo-wallpaper/render.py
   

Development

Testing

# Add a test todo
python3 todo.py add "Test task"

# Verify it appears in wallpaper
python3 render.py

# List todos
todo list

# Remove it
todo remove 1

Project Structure

• State: todos.json (persistent JSON file)
• Rendering: render.py (Pillow image generation)
• Interface: todo.py (CLI commands)
• Automation: init.py + systemd service (startup)

License

MIT (or your preferred license)

Support

Issues or suggestions? Check:

• Are all dependencies installed? Run python3 setup.py
• Is feh correctly setting the wallpaper? Try manually: feh --bg-fill wallpaper.png
• Are todo files in the right location? Should be in ~/projects/random/todo-wallpaper/