macos-launchd-service

Set up macOS launchd service for auto-starting Python applications

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the generation of macOS launchd service infrastructure for Python applications. It streamlines the process of turning Python scripts into reliable background daemons by creating a complete suite of management tools, including automated installers, uninstallers, log viewers, and development-mode scripts. It ensures your services start automatically on login and remain resilient with auto-restart capabilities.

Use Cases

  • 1. Persistent Web Services: Automatically launch and maintain FastAPI, Flask, or other web servers as background services on macOS boot or login.
  • 2. Background Task Automation: Deploy Python-based daemons for periodic data processing, file monitoring, or system maintenance tasks that need to run continuously.
  • 3. Optimized Development Workflow: Use the generated dev scripts to run applications with auto-reload functionality while preventing system sleep using 'caffeinate'.
  • 4. Standardized Service Management: Simplify the monitoring and lifecycle management of local services with dedicated scripts for viewing logs and checking service status.
namemacos-launchd-service
descriptionSet up macOS launchd service for auto-starting Python applications
allowed-toolsRead, Write, Bash, Glob

macOS launchd Service Setup

Generate complete launchd service infrastructure for Python applications on macOS.

What This Skill Creates

launchd/
├── install.sh                          # Automated service installer
├── uninstall.sh                        # Service uninstaller
├── {project}.plist.template           # Service configuration
dev.sh                                  # Development mode script
view-logs.sh                           # Log viewing helper

When to Use This Skill

  • Web services: FastAPI, Flask apps that should auto-start
  • Background services: Daemons, periodic tasks
  • Development servers: Local services you want always running

Before Running

Requirements:

  • macOS 10.10+ with launchd
  • Python project with uv and .venv
  • pyproject.toml with [project.scripts] defining a CLI command

Check pyproject.toml:

[project.scripts]
yourapp = "yourapp.cli:main"

IMPORTANT - Replacing Existing Setup:

If the project already has launchd/ directory or existing scripts:

  • ALWAYS use the parameters provided by the user
  • DO NOT read values from existing files
  • The user wants to replace with NEW values, not keep old ones
  • Overwrite existing files with the new parameter values

Step-by-Step Process

1. Gather Information from User

Ask the user for these parameters (use AskUserQuestion if needed):

  • Domain (e.g., "dev.pborenstein", "com.pborenstein") - Reverse domain notation for service label
    • Default suggestion: dev.{username} (e.g., "dev.philip")
    • Best practice: Use owned domain (e.g., "dev.pborenstein" if you own pborenstein.dev)
  • Project name (e.g., "temoa", "apantli") - lowercase, no spaces
  • Module name (e.g., "temoa", "apantli") - Python import name
  • Port number (e.g., 4001, 4000) - unique port for this service
  • CLI command (e.g., "temoa server", "python3 -m apantli.server")
  • Dev command (e.g., "temoa server --reload", "python3 -m apantli.server --reload")
  • Process name (e.g., "temoa server", "apantli.server") - for detecting running processes

Use these exact values provided by the user - do not infer from existing files.

2. Suggest Defaults from pyproject.toml (Optional)

Only if the user hasn't provided values, you may suggest defaults from pyproject.toml:

# Suggest project name
grep "^name" pyproject.toml

# Suggest CLI command from [project.scripts]
grep -A 5 "\[project.scripts\]" pyproject.toml

But always use what the user explicitly provides.

3. Generate launchd Directory

Create launchd/ directory:

mkdir -p launchd

4. Generate Files from Templates

For each template in skills/macos-launchd-service/templates/, perform substitutions:

Substitution variables:

User-provided parameters (use values from step 1):

  • {{DOMAIN}} - Reverse domain notation (e.g., "dev.pborenstein", "com.pborenstein")
  • {{PROJECT_NAME}} - Project name (e.g., "temoa")
  • {{MODULE_NAME}} - Python module name for import check
  • {{PORT}} - Port number
  • {{CLI_COMMAND}} - Full CLI command as plist array elements
  • {{DEV_COMMAND}} - Development mode command
  • {{PROCESS_NAME}} - Process name for pkill/pgrep

Auto-detected variables (these are filled in by install.sh at runtime):

  • {{HOME}} - User's home directory
  • {{PROJECT_DIR}} - Absolute path to project directory
  • {{VENV_PYTHON}} - Path to venv Python interpreter
  • {{VENV_BIN}} - Path to venv bin directory

CLI_COMMAND special handling:

Must be converted to plist array format:

Input: "temoa server --host 0.0.0.0 --port 4001"

Output:
        <string>{{VENV_BIN}}/temoa</string>
        <string>server</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>4001</string>

5. Generated Files

install.sh (from install.sh.template):

  • Auto-detects environment (username, paths, venv)
  • Validates venv and module are installed
  • Generates service plist from template
  • Installs and loads service
  • Shows access information and management commands

uninstall.sh (from uninstall.sh.template):

  • Checks if service exists
  • Shows what will be removed
  • Asks for confirmation
  • Stops running service
  • Removes plist file
  • Confirms uninstall complete

{project}.plist.template (from service.plist.template):

  • Service configuration with substitution placeholders
  • Used by install.sh to generate final plist
  • Configured with RunAtLoad, KeepAlive for production

dev.sh (from dev.sh.template):

  • Stops launchd service if running
  • Runs app with auto-reload for development
  • Uses caffeinate to prevent sleep
  • Offers to restore service on exit

view-logs.sh (from view-logs.sh.template):

  • Modes: app logs, errors, or all
  • Uses tail -f for live viewing
  • Logs location: ~/Library/Logs/{project}.log

6. Make Scripts Executable

chmod +x launchd/install.sh
chmod +x launchd/uninstall.sh
chmod +x dev.sh
chmod +x view-logs.sh

7. Provide Next Steps

After generation, tell the user:

✓ Generated launchd service structure

Next steps:
1. Review generated files in launchd/
2. Run: ./launchd/install.sh
3. Access your service at: http://localhost:{PORT}
4. View logs: ./view-logs.sh
5. Development mode: ./dev.sh

Service will auto-start on login and auto-restart on crash.

Manage service:
  Stop:    launchctl unload ~/Library/LaunchAgents/{DOMAIN}.{project}.plist
  Start:   launchctl load ~/Library/LaunchAgents/{DOMAIN}.{project}.plist
  Status:  launchctl list | grep {project}

Example: temoa

Input parameters:

  • Domain: dev.pborenstein
  • Project name: temoa
  • Module name: temoa
  • Port: 4001
  • CLI command: temoa server --host 0.0.0.0 --port 4001 --log-level info
  • Dev command: temoa server --reload
  • Process name: temoa server

Generated CLI_COMMAND for plist:

    <array>
        <string>{{VENV_BIN}}/temoa</string>
        <string>server</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>4001</string>
        <string>--log-level</string>
        <string>info</string>
    </array>

Implementation Notes

Reading templates:

Templates are in skills/macos-launchd-service/templates/:

  • install.sh.template
  • uninstall.sh.template
  • service.plist.template
  • dev.sh.template
  • view-logs.sh.template

Writing generated files:

  • launchd/install.sh
  • launchd/uninstall.sh
  • launchd/{PROJECT_NAME}.plist.template
  • dev.sh
  • view-logs.sh

String substitution:

Simple replace all instances of each {{VARIABLE}} with its value.

CLI_COMMAND conversion:

Split on spaces, wrap each token in <string>TOKEN</string> with proper indentation.

Validation

After generation, verify:

  • All 5 files created (install.sh, uninstall.sh, plist.template, dev.sh, view-logs.sh)
  • Scripts are executable
  • No leftover {{VARIABLES}} in files
  • CLI_COMMAND properly formatted as plist array

Common Issues

Port conflicts: Use lsof -i :{PORT} to check if port is available

Module not found: User needs to run uv sync first

Permission errors: Ensure ~/Library/LaunchAgents exists

See Also

  • README.md - Detailed usage guide
  • Example implementations: temoa, apantli in nahuatl-projects