gaelic-ghost/speakswiftlyserver/speak-swiftly-launchagent-setup

SpeakSwiftly LaunchAgent Setup

Use this skill when the user wants the standalone SpeakSwiftlyServer to run as a per-user background service managed by launchd.

Start Here

• Use the supported SpeakSwiftlyServerTool launch-agent ... commands instead of hand-editing property lists or calling launchctl directly.
• Read the repo operator guidance in README.md first, then LaunchAgent-Workflow.md when the user needs the full setup model.
• If the user is asking about Codex access to the running service, remember that the installed plugin already handles the Codex-side MCP registration through `.mcp.json`. The setup work here is about getting the live server healthy at http://127.0.0.1:7337/mcp, not about hand-editing Codex MCP or hook config files.
• If the user installed Speak Swiftly through the SpeakSwiftlyServer or socket marketplace, use the upgraded installed plugin checkout for first-run setup and service refresh unless the user explicitly asks to promote this development checkout. Marketplace install or upgrade refreshes the Codex-managed plugin payload, but it does not silently install or restart the native LaunchAgent-backed service.
• For marketplace users, make the update sequence explicit: upgrade the owning marketplace, start a fresh Codex session, run launch-agent install from the upgraded plugin checkout, then run healthcheck. Do not imply that plugin upgrade alone updates the running native service, and do not add user-level Codex hook fallbacks.
• Phrase the setup outcome in user terms like "set up SpeakSwiftly on this machine," "install the background service," "make the local service reachable from Codex," or "fix the LaunchAgent install," because those are the kinds of requests this skill should trigger on.

Normal Setup Flow

1. Print the property list first with xcrun swift run SpeakSwiftlyServerTool launch-agent print-plist.
2. Confirm whether the user wants the default config. The standard live-service path is ~/Library/Application Support/SpeakSwiftlyServer/server.yaml, and the install command seeds it automatically when it is missing.
3. Run xcrun swift run SpeakSwiftlyServerTool launch-agent install for the normal all-in-one path. With the default staged artifact path, this builds and stages the current checkout, refreshes the LaunchAgent property list, and bootstraps the service.
4. If the user explicitly wants a custom config file, pass --config-file <server-config-yaml> and make sure that file already exists.
5. Verify the result with xcrun swift run SpeakSwiftlyServerTool healthcheck.

When To Use Each Command

• launch-agent print-plist:

Use before install work or when the user wants to inspect exactly what will be staged into ~/Library/LaunchAgents.

• launch-agent install:

Use for the normal "make this checkout become the live service now" path. With the default executable path, this rebuilds and stages the release artifact first, then refreshes the LaunchAgent install.

• launch-agent promote-live:

Use only when a script or operator flow wants the lower-level promotion spelling explicitly. It performs the same current-checkout staging step before refreshing the LaunchAgent install.

• launch-agent status:

Use when the user wants to inspect the installed state, label, plist location, or staged executable details.

• launch-agent uninstall:

Use when the user explicitly wants the per-user background service removed.

• healthcheck:

Use after install, promotion, config changes, or troubleshooting. It is the supported end-to-end probe for both HTTP and MCP.

Validation And Troubleshooting

• Treat healthcheck as the primary verification path because it probes GET /healthz, reads GET /overview, and sends a real MCP initialize request to /mcp.
• If the HTTP process is healthy but Codex still cannot use the MCP surface, do not jump straight to telling the user to edit Codex config. First check whether the server is actually exposing /mcp. The plugin install should already handle the Codex-side connection; the remaining failure is usually that MCP is disabled in the server config or environment. The MCP endpoint exists only when APP_MCP_ENABLED=true or the config file enables MCP.
• If a marketplace user says the plugin is installed but Speak Swiftly still does not speak, check whether the LaunchAgent-backed service is installed and healthy before changing plugin config. The hook path records speech-route-unreachable when the plugin is present but the native service is not running.
• If the user wants to understand whether the live background service is using the staged artifact or a different executable, rely on launch-agent status, install output, and the printed plist rather than inferring from filesystem timestamps alone.
• If the user needs queue, playback, or backend control after the service is already installed, switch to $speak-swiftly-runtime-operator instead of stretching this skill into runtime operations.
• If the question is about using the live MCP surface from Codex after setup, switch to $speak-swiftly-mcp.