Skip to content

Linux hosts have no documented way to keep moshi-hook alive #4

Description

@tburny

What changes for the user

Today the skill's host-setup guidance assumes macOS: §1 "Host Readiness" and §5 "Agent Hooks" tell the user to keep the moshi-hook daemon alive with brew services start moshi-hook, and pairing defaults to Keychain. There is no Homebrew-services equivalent on Linux, so a Linux user who follows the skill ends up paired but with no documented way to keep moshi-hook serve running across logout or reboot. After this change the skill would include a Linux path — a systemd user service plus linger — so Linux hosts are covered the same way macOS hosts are.

Why it matters

moshi-hook serve is a long-lived daemon (agent-hook Unix socket + remote-approval WebSocket). If it isn't supervised it dies on logout, and remote approvals / Live Activity / Watch stop working until the user manually restarts it. macOS users get brew services; Linux users currently have to improvise their own supervision. The skill already documents the Linux-friendly moshi-hook pair --store file flow, so Linux is clearly a supported target — it just stops short of the "keep it running" step.

Desired behaviour — acceptance criteria

  • Following the skill on Linux, the user ends with moshi-hook serve running under systemctl --user and Active: running.
  • The daemon survives logout and reboot (skill instructs loginctl enable-linger).
  • The skill provides a copy-pasteable ~/.config/systemd/user/moshi-hook.service unit.
  • Linux pairing points at moshi-hook pair --token <T> --store file (already in the skill) rather than Keychain.
  • Verification steps are given: systemctl --user is-active moshi-hook and moshi-hook status showing paired.

Reference — a unit that works (verified on Linux, moshi-hook 0.2.34)

[Unit]
Description=Moshi hook daemon (agent-hook Unix socket + remote-approval WebSocket)
Documentation=https://getmoshi.app

[Service]
Type=simple
ExecStart=%h/.local/bin/moshi-hook serve
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
systemctl --user enable --now moshi-hook.service
loginctl enable-linger "$USER"   # daemon survives logout / reboot

Verified end-to-end on Ubuntu (Linux 6.8), moshi-hook 0.2.34: service Active: running, Linger=yes, and after pair --store file the daemon logs paired=true and ws bridge connected (remote approvals live).

Out of scope

  • Distro service packaging (deb/rpm) or a system-wide unit — this is user-level systemd only.
  • Teaching moshi-hook to install the unit itself — this is a skill-documentation addition, not a CLI feature.
  • The moshi DIR tmux launcher and tmux config (§2/§4) — unchanged.

Where the details live

  • Current skill: skills/moshi-best-practices/SKILL.md — §1 "Host Readiness" and §5 "Agent Hooks" (the brew services start moshi-hook line and the --store file pairing block).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions