create-daemon

Category: Daily Life | Uploader: mint-philosophy | Downloads: 0 | Version: v1.0（Latest）
Create new launchd daemons for macOS — covers plist generation, shell wrappers, secret resolution, logging, state persistence, and lifecycle management
Changelog: Source: GitHub https://github.com/mint-philosophy/minty-agent-toolkit
Directory Structure

Current level: daemon-framework/create-daemon/
📄 SKILL.md 17.0 KB
SKILL.md

---
name: create-daemon
description: Create new launchd daemons for macOS — covers plist generation, shell wrappers, secret resolution, logging, state persistence, and lifecycle management
version: 1.0
triggers:
  - create daemon
  - new daemon
  - background process
  - launchd
  - scheduled task
scope:
  - infrastructure
---

# Create Daemon

## Overview

Background processes on macOS run as launchd agents under `~/Library/LaunchAgents/`. This skill covers creating a new daemon from scratch: choosing a scheduling type, writing the plist, structuring the project directory, handling secrets, logging, state, and installation.

Replace `{{PLIST_PREFIX}}` with your reverse-domain prefix (e.g., `com.myorg`) and `{{DAEMON_NAME}}` with the daemon's short name throughout.

## When to Use

- Creating any new background process, scheduled task, or persistent listener
- Converting a manual script into an automated daemon
- NOT for one-off scripts run manually

## Step 1 -- Choose a Scheduling Type

| Type | Plist Key | Use When | Examples |
|------|-----------|----------|----------|
| **A -- Persistent** | `KeepAlive` + `RunAtLoad` | Long-running process (Socket Mode listener, event watcher, web server) | Slack bot, webhook listener |
| **B -- Polling** | `StartInterval` (seconds) | Periodic check-and-act; script runs once and exits | Health check (600s), sync job (300s) |
| **C -- Daily** | `StartCalendarInterval` | Nightly/daily batch job; runs once at a fixed time | Digest (06:00), index rebuild (02:00) |

## Step 2 -- Create Directory Structure

```
{{DAEMONS_ROOT}}/
  {{DAEMON_NAME}}/
    CLAUDE.md                                  # Agent docs (what it does, how to debug)
    {{PLIST_PREFIX}}.{{DAEMON_NAME}}.plist     # launchd config
    main_script.py                             # Entry point (or .sh wrapper)
    data/                                      # State files + app-level logs
    logs/                                      # launchd stdout/stderr
    requirements.txt                           # (optional) pip deps
    config.yaml                                # (optional) for complex configs
```

Create both `data/` and `logs/` directories upfront. Scripts should `mkdir -p` them at startup too.

## Step 3 -- Write the Plist

Label convention: `{{PLIST_PREFIX}}.{{DAEMON_NAME}}`

### Template Variables

Before using the templates below, define these values for your project:

| Variable | Description | Example |
|----------|-------------|---------|
| `{{PLIST_PREFIX}}` | Reverse-domain label prefix | `com.myorg` |
| `{{DAEMON_NAME}}` | Short daemon name (used in paths and labels) | `health-probe` |
| `{{DAEMONS_ROOT}}` | Absolute path to your daemons directory | `/Users/me/project/daemons` |
| `{{PYTHON_BIN}}` | Absolute path to the Python interpreter | `/usr/bin/python3` or a venv path |
| `{{USER_HOME}}` | Absolute path to the user's home directory | `/Users/me` |

### Type A -- Persistent (KeepAlive)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>{{PLIST_PREFIX}}.{{DAEMON_NAME}}</string>

    <key>ProgramArguments</key>
    <array>
        <string>{{PYTHON_BIN}}</string>
        <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/main_script.py</string>
    </array>

    <key>WorkingDirectory</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:{{USER_HOME}}/.local/bin</string>
        <key>HOME</key>
        <string>{{USER_HOME}}</string>
        <key>LANG</key>
        <string>en_US.UTF-8</string>
    </dict>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
    </dict>

    <key>ThrottleInterval</key>
    <integer>10</integer>

    <key>StandardOutPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stderr.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>
```

Notes on KeepAlive:
- `SuccessfulExit: false` means launchd restarts on non-zero exit (crash). A clean `sys.exit(0)` stays stopped.
- Use `<true/>` instead of the dict form to restart on ALL exits.
- `ThrottleInterval` prevents restart spin loops (10-30s typical).

### Type B -- Polling (StartInterval)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>{{PLIST_PREFIX}}.{{DAEMON_NAME}}</string>

    <key>ProgramArguments</key>
    <array>
        <string>{{PYTHON_BIN}}</string>
        <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/main_script.py</string>
    </array>

    <key>WorkingDirectory</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:{{USER_HOME}}/.local/bin</string>
        <key>HOME</key>
        <string>{{USER_HOME}}</string>
        <key>LANG</key>
        <string>en_US.UTF-8</string>
    </dict>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stderr.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>
```

### Type C -- Daily (StartCalendarInterval)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>{{PLIST_PREFIX}}.{{DAEMON_NAME}}</string>

    <key>ProgramArguments</key>
    <array>
        <string>{{PYTHON_BIN}}</string>
        <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/main_script.py</string>
    </array>

    <key>WorkingDirectory</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:{{USER_HOME}}/.local/bin</string>
        <key>HOME</key>
        <string>{{USER_HOME}}</string>
        <key>LANG</key>
        <string>en_US.UTF-8</string>
    </dict>

    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>6</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>

    <key>StandardOutPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stderr.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>
```

### Plist Rules

- ALL paths must be absolute. No `./` or `~/`.
- Plist does NOT expand `~`. Always use the full home directory path.
- Add `PYTHONPATH` to EnvironmentVariables only if importing from sibling projects.
- For daemons using a `.venv`, point ProgramArguments at the venv Python: `.venv/bin/python3`.

## Step 4 -- Secret Resolution Pattern

Daemons cannot use interactive auth. Use this cascade in every daemon that needs secrets.

```python
import os
import subprocess
import sys

def get_secret(key_name):
    """Resolve a secret via env -> keychain -> dotfile fallback."""
    # 1. Environment variable (set by shell wrapper or plist)
    value = os.environ.get(key_name)
    if value:
        return value

    # 2. macOS Keychain via vault-keychain binary (silent, no GUI popups).
    #    IMPORTANT: Do NOT use `security find-generic-password` in daemon code —
    #    it triggers SecurityAgent popups in launchd/headless contexts.
    #    Use the vault-keychain binary (see scripts/compile-vault-keychain.sh) or
    #    platform_config.get_secret() instead.
    vault_bin = os.path.join(os.path.dirname(__file__), "..", "..", "scripts", "vault-keychain")
    if os.path.isfile(vault_bin):
        try:
            result = subprocess.run(
                [vault_bin, "read", key_name],
                capture_output=True, text=True,
            )
            if result.returncode == 0 and result.stdout.strip():
                return result.stdout.strip()
        except Exception:
            pass

    # 3. platform_config fallback
    try:
        from platform_config import get_secret
        return get_secret(key_name)
    except (ImportError, Exception):
        pass

    raise ValueError(
        "Secret '{}' not found. Set as env var, add to keychain, "
        "or add to .env file.".format(key_name)
    )
```

Keychain service name convention: `{{PLIST_PREFIX}}-KEY_NAME` (e.g., `com.myorg-SLACK_BOT_TOKEN`).

### Claude CLI Auth for Daemons

Daemons that call `claude -p` need a shared auth directory and OAuth token. Do not use `~/.claude` or per-daemon `.claude/` directories -- use a shared config directory for all daemons.

```python
from pathlib import Path

# Shared Claude auth -- all daemons share one config directory
DAEMONS_DIR = Path("/path/to/your/daemons")
CLAUDE_CONFIG_DIR = str(DAEMONS_DIR / ".claude")

# When building env for claude -p subprocess calls:
env = os.environ.copy()
env["CLAUDE_CONFIG_DIR"] = CLAUDE_CONFIG_DIR

# If using an OAuth token from the keychain:
oauth_token = get_secret("CLAUDE_CODE_OAUTH_TOKEN")
if oauth_token:
    env["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
```

## Step 5 -- Logging Pattern

Dual-handler: stderr (captured by launchd) + app log file (for history).

```python
import logging
import sys
from pathlib import Path

SCRIPT_DIR = Path(__file__).resolve().parent
LOG_DIR = SCRIPT_DIR / "data"
LOG_DIR.mkdir(parents=True, exist_ok=True)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    handlers=[
        logging.StreamHandler(sys.stderr),
        logging.FileHandler(str(LOG_DIR / "app.log"), encoding="utf-8"),
    ],
)
logger = logging.getLogger("{{DAEMON_NAME}}")
```

## Step 6 -- Error Handling

### Run-once daemons (Type B and C)

Wrap `main()` in a top-level try/except. Exit non-zero on failure so launchd records it.

```python
if __name__ == "__main__":
    try:
        main()
    except Exception:
        logger.exception("Unhandled exception in {{DAEMON_NAME}}")
        sys.exit(1)
```

### Long-running daemons (Type A)

Handle SIGTERM/SIGINT for graceful shutdown.

```python
import signal
import threading

shutdown_event = threading.Event()

def _handle_signal(signum, frame):
    logger.info("Received signal %s, shutting down...", signum)
    shutdown_event.set()

signal.signal(signal.SIGTERM, _handle_signal)
signal.signal(signal.SIGINT, _handle_signal)

# In your main loop:
while not shutdown_event.is_set():
    # do work
    shutdown_event.wait(timeout=1.0)
```

For Socket Mode (e.g., Slack Bolt), the framework manages its own event loop. Catch KeyboardInterrupt and let crashes propagate -- launchd restarts via KeepAlive.

## Step 7 -- State Persistence

For daemons that track progress between runs.

```python
import json
import os
from pathlib import Path

STATE_FILE = Path(__file__).resolve().parent / "data" / "state.json"

def load_state():
    if STATE_FILE.exists():
        try:
            return json.loads(STATE_FILE.read_text())
        except (json.JSONDecodeError, IOError):
            return _default_state()
    return _default_state()

def _default_state():
    return {"last_run": None, "processed_ids": []}

def save_state(state):
    """Atomic write: write to tmp file then rename."""
    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
    tmp = str(STATE_FILE) + ".tmp"
    with open(tmp, "w") as f:
        json.dump(state, f, indent=2)
    os.rename(tmp, str(STATE_FILE))
```

Atomic write (tmp + rename) prevents corruption if the process is killed mid-write.

## Step 8 -- Shell Wrapper Pattern

Use when the daemon needs to resolve secrets before launching, or calls scripts from another project.

```bash
#!/bin/bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
echo "[$(date)] Starting {{DAEMON_NAME}}..."

# Resolve secrets from keychain (customize the service name prefix)
export MY_API_TOKEN="$(security find-generic-password -s "{{PLIST_PREFIX}}-MY_API_TOKEN" -w 2>/dev/null || true)"

if [ -z "$MY_API_TOKEN" ]; then
    echo "ERROR: Failed to retrieve MY_API_TOKEN" >&2
    exit 1
fi

# Run the script (absolute path to Python, absolute path to script)
exec {{PYTHON_BIN}} "$SCRIPT_DIR/main_script.py" "$@"
```

In the plist, use `/bin/bash` as the program:

```xml
<key>ProgramArguments</key>
<array>
    <string>/bin/bash</string>
    <string>{{DAEMONS_ROOT}}/{{DAEMON_NAME}}/run.sh</string>
</array>
```

## Step 9 -- CLAUDE.md Template

Every daemon should have a `CLAUDE.md` describing it for AI agents that may maintain or debug it.

```markdown
# {{DAEMON_NAME}} Daemon

## Purpose

One-paragraph description of what this daemon does and why it exists.

## Schedule

- **Type**: [Persistent / Polling (Ns) / Daily (HH:MM)]
- **Plist**: `{{PLIST_PREFIX}}.{{DAEMON_NAME}}.plist`

## Architecture

Brief description of how the daemon works: what it reads, what it writes,
what external services it calls.

## Files

| File | Purpose |
|:-----|:--------|
| `main_script.py` | Entry point |
| `data/state.json` | Persistent state between runs |
| `logs/stdout.log` | launchd stdout |
| `logs/stderr.log` | launchd stderr |

## Secrets

List every secret this daemon uses and where each comes from.

## Manual Run

\`\`\`bash
{{PYTHON_BIN}} {{DAEMONS_ROOT}}/{{DAEMON_NAME}}/main_script.py
\`\`\`

## Debugging

\`\`\`bash
# Check daemon status
launchctl list | grep {{DAEMON_NAME}}

# Check logs
tail -f {{DAEMONS_ROOT}}/{{DAEMON_NAME}}/logs/stderr.log

# Force an immediate run
launchctl kickstart gui/$(id -u)/{{PLIST_PREFIX}}.{{DAEMON_NAME}}
\`\`\`
```

## Step 10 -- Installation Checklist

Run these steps in order after writing all files.

```bash
# 1. Create directories
DAEMON="{{DAEMONS_ROOT}}/{{DAEMON_NAME}}"
mkdir -p "$DAEMON/data" "$DAEMON/logs"

# 2. Make scripts executable (if shell wrapper)
chmod +x "$DAEMON/run.sh"

# 3. Copy plist to LaunchAgents
cp "$DAEMON/{{PLIST_PREFIX}}.{{DAEMON_NAME}}.plist" ~/Library/LaunchAgents/

# 4. Load the daemon
launchctl load ~/Library/LaunchAgents/{{PLIST_PREFIX}}.{{DAEMON_NAME}}.plist

# 5. Verify it loaded
launchctl list | grep {{DAEMON_NAME}}

# 6. Check logs
tail -f "$DAEMON/logs/stdout.log"

# 7. Force an immediate run (useful for testing)
launchctl kickstart gui/$(id -u)/{{PLIST_PREFIX}}.{{DAEMON_NAME}}
```

## Quick Reference -- launchd Commands

```bash
# Load (start) a daemon
launchctl load ~/Library/LaunchAgents/PLIST_FILE

# Unload (stop) a daemon
launchctl unload ~/Library/LaunchAgents/PLIST_FILE

# List all your daemons (filter by your prefix)
launchctl list | grep {{PLIST_PREFIX}}

# Force immediate execution
launchctl kickstart gui/$(id -u)/{{PLIST_PREFIX}}.{{DAEMON_NAME}}

# Detailed daemon info (PID, exit status, last run)
launchctl print gui/$(id -u)/{{PLIST_PREFIX}}.{{DAEMON_NAME}}
```

To reload after plist changes: unload, then load again.

## Important Rules

1. **Absolute paths everywhere** -- in plists, in scripts, in imports. Never rely on `~` expansion in plists.
2. **PATH must include tool directories** -- required for CLI tools installed via Homebrew or pip. On Apple Silicon Macs, `/opt/homebrew/bin` is essential.
3. **Network binding** -- bind to `127.0.0.1`, not `0.0.0.0`.
4. **Log management** -- launchd does not rotate logs. Either truncate on startup (polling daemons) or use `RotatingFileHandler` (persistent daemons).
5. **Secrets** -- never hardcode tokens. Always use the secret resolution cascade.
6. **Testing** -- always test with `launchctl kickstart` before considering the daemon done. Check both stdout.log and stderr.log.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Relative paths in plist | All paths must be absolute starting with `/` |
| Missing `data/` or `logs/` dir | Create both at setup AND `mkdir -p` in script |
| Forgot PATH in EnvironmentVariables | Homebrew tools (claude, git) will not be found |
| Using `~/` in plist paths | Plist does not expand `~`; use full path |
| Script not executable (shell wrapper) | `chmod +x` the `.sh` file |
| Plist not copied to LaunchAgents | The file in the daemon dir is the source; the copy in `~/Library/LaunchAgents/` is what launchd reads |
| Editing plist in daemon dir but not reloading | Must copy to LaunchAgents again and unload/load |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
create-daemon

Directory Structure

SKILL.md

Report

Notice
