daemon-setup

/asciinema-tools:daemon-setup

Interactive wizard to set up the asciinema chunker daemon. This daemon runs independently of Claude Code, using dedicated credentials stored in macOS Keychain.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Why a Daemon?

Problem with old approach	Daemon solution
Uses gh auth token (shared)	Uses dedicated PAT from Keychain
Dies when terminal closes	launchd keeps it running
Silent push failures	Logs + Pushover notifications
Tied to Claude Code session	Completely decoupled

Setup Phases Overview

Phase	Name	Details
1	Preflight Check	Below
2	Check Existing	Below
3	GitHub PAT Setup	PAT Setup Guide
4	Pushover Setup	Pushover Setup Guide
5-6	Config + Install	launchd Installation Guide
7	Verify + Troubleshoot	Verification & Troubleshooting

Execution

Phase 1: Preflight Check

Check required tools:

/usr/bin/env bash << 'PREFLIGHT_EOF'
MISSING=()
for tool in asciinema zstd git curl jq; do
  command -v "$tool" &>/dev/null || MISSING+=("$tool")
done

# macOS-specific: security command for Keychain
if [[ "$(uname)" == "Darwin" ]]; then
  command -v security &>/dev/null || MISSING+=("security (macOS Keychain)")
fi

if [[ ${#MISSING[@]} -gt 0 ]]; then
  echo "MISSING:${MISSING[*]}"
  exit 1
fi

echo "PREFLIGHT:OK"
PREFLIGHT_EOF

If MISSING not empty, use AskUserQuestion:

Question: "Missing required tools: {MISSING}. How would you like to proceed?"
Header: "Dependencies"
Options:
  - label: "Install via Homebrew (Recommended)"
    description: "Run: brew install {MISSING}"
  - label: "I'll install manually"
    description: "Pause setup and show install instructions"
  - label: "Abort setup"
    description: "Exit the setup wizard"

If "Install via Homebrew": Run brew install {MISSING} and continue.

---

Phase 2: Check Existing Installation

/usr/bin/env bash << 'CHECK_EXISTING_EOF'
PLIST_PATH="$HOME/Library/LaunchAgents/com.cc-skills.asciinema-chunker.plist"
DAEMON_RUNNING="false"

if [[ -f "$PLIST_PATH" ]]; then
  echo "PLIST_EXISTS:true"
  if launchctl list 2>/dev/null | grep -q "asciinema-chunker"; then
    DAEMON_RUNNING="true"
  fi
else
  echo "PLIST_EXISTS:false"
fi

echo "DAEMON_RUNNING:$DAEMON_RUNNING"

# Check if PAT already in Keychain
if security find-generic-password -s "asciinema-github-pat" -a "$USER" -w &>/dev/null 2>&1; then
  echo "PAT_EXISTS:true"
else
  echo "PAT_EXISTS:false"
fi
CHECK_EXISTING_EOF

If PLIST_EXISTS=true, use AskUserQuestion:

Question: "Existing daemon installation found. What would you like to do?"
Header: "Existing"
Options:
  - label: "Reinstall (keep credentials)"
    description: "Update daemon script and plist, keep Keychain credentials"
  - label: "Fresh install (reset everything)"
    description: "Remove existing credentials and start fresh"
  - label: "Cancel"
    description: "Exit without changes"

---

Phase 3: GitHub PAT Setup

See PAT Setup Guide for the full interactive flow: PAT creation walkthrough, Keychain storage, and verification.

---

Phase 4: Pushover Setup (Optional)

See Pushover Setup Guide for the full interactive flow: Pushover explanation, app creation, credential storage, and test notification.

---

Phase 5-6: Daemon Configuration and launchd Installation

See launchd Installation Guide for chunking settings selection, plist generation from template, and service installation.

---

Phase 7: Verification

See Verification & Troubleshooting for daemon health checks, post-install verification, the final success message, and the troubleshooting table.

Quick Reference

Troubleshooting

Issue	Cause	Solution
Keychain access denied	macOS permission not granted	Grant access in System Settings
PAT test failed	Token expired or invalid scope	Generate new token with repo scope
launchctl load failed	plist syntax error	Check plutil -lint <plist-path>
Daemon keeps stopping	Script error or crash	Check /asciinema-tools:daemon-logs
Pushover not working	Invalid credentials	Re-run setup with correct app/user key
Health file missing	Daemon not running	Run /asciinema-tools:daemon-start

Related Commands

Command	Description
/asciinema-tools:daemon-status	Check daemon health
/asciinema-tools:daemon-logs	View logs
/asciinema-tools:daemon-stop	Stop daemon
/asciinema-tools:daemon-start	Start daemon

---

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.