Service

Always-on service

Wrap Claude Code (with ClawCode) in the OS's service manager so the agent keeps running after the terminal closes. This is what makes the HTTP bridge, WebChat, webhooks, and crons work 24/7.

This is an OPTIONAL feature. See docs/service.md for the full reference, risks, and how to add messaging-channel flags.

⚠️ Safety — read before install

Installing the service runs Claude Code with --dangerously-skip-permissions in the background. That flag:

• Pre-approves every tool call (Bash, Write, Edit, network requests)
• Cannot be undone per-request — the running service has full permissions over the agent's workspace for its whole lifetime
• Is necessary because a daemon cannot answer interactive tool-approval prompts

This is an irrevocable trust decision for this workspace. Only run /agent:service install if you understand that.

Always prompt the user to confirm before installing. Quote the flag by name in the confirmation. If the user hesitates or asks questions, stop and explain.

Dispatch

Parse the action and call service_plan with it.

Install flow

1. Find the claude binary: Bash(which claude). Trim output. If empty, abort with: "Can't find claude in PATH. Install Claude Code or point me at it manually."
2. Inspect the existing service launcher (if any) and preserve its exact channel, session and other arguments. Call channels_detect as supporting evidence; do not replace an existing launcher with a guessed command. If Live is configured, run live_setup_status and follow /agent:live for any setup changes first. Call service_plan({ action: "install", claudeBin: <path>, extraArgs: <existing arguments> }). The plan adds ClawCode's Live channel when opted in and the wrapper supplies the managed web environment; it does not add or authorize WhatsApp or permission flags on behalf of the operator.
3. If the plan has error (unsupported OS), print the error and stop.
4. Show the user the warning (see Safety section). Ask explicitly: "This will install a background service that runs with --dangerously-skip-permissions. Confirm? [y/N]"
5. If the user says no, stop with a neutral acknowledgement.
6. If the user confirms:
   • Pre-check ~/.claude/settings.json (prevents the most common install hang — see docs/service.md "Heads-up" note):
     • Read the file with Read(~/.claude/settings.json). If it doesn't exist or is empty, treat as {}.
     • If skipDangerousModePermissionPrompt is already true, skip to the next sub-step.
     • Otherwise, tell the user: "Heads-up: your ~/.claude/settings.json is missing \"skipDangerousModePermissionPrompt\": true. Without it, the service will show a 'Bypass Permissions — Do you accept?' dialog at startup that no daemon (launchd / systemd) can answer, and the install will appear to succeed but the service will hang silently. Add it now? [y/N]"
     • If yes: merge with jq via Bash (preserves any other keys, atomic write): Bash: jq '. + {"skipDangerousModePermissionPrompt": true}' ~/.claude/settings.json > ~/.claude/settings.json.tmp && mv ~/.claude/settings.json.tmp ~/.claude/settings.json (If the file did not exist, first run Bash: echo '{}' > ~/.claude/settings.json so jq has something to merge into.) Confirm with one line: "Added skipDangerousModePermissionPrompt: true to ~/.claude/settings.json."
     • If no: warn explicitly "Without it the service will hang at startup. Continue anyway? [y/N]". On a second no, abort with a neutral acknowledgement and do not write any service files. On yes, proceed and let the user deal with it.
   • If plan.extraFiles is present, for each entry: ensure the parent dir exists (Bash(mkdir -p <dirname>)), then Write(file.path, file.content), then Bash(chmod <octal> <file.path>) using file.mode (default 0o644 when omitted). These are auxiliary scripts the unit file needs to exist before start — e.g. the resume-on-restart wrapper.
   • Write the plist / unit file: Write(filePath, fileContent) — the plan tells you the path
   • Run each command from plan.commands in order with Bash, printing the label before each
   • If any command fails, stop and report the error (do NOT try to roll back — the user can run uninstall to clean up)
7. Final line: "Service installed. Label: <plan.label>. Log: <plan.logPath>. Run /agent:service status to verify."

Status flow

1. Call service_plan({ action: "status" })
2. Run each command from plan.commands with Bash
3. Summarize in one line: "Active" / "Not loaded" / "Unknown" based on the command output

Uninstall flow

1. Call service_plan({ action: "uninstall" })
2. Ask the user: "Remove the <plan.label> service? [y/N]"
3. On confirmation, run each command from plan.commands
4. Report: "Service removed."

Logs flow

1. Call service_plan({ action: "logs" })
2. Run the single tail command and print output directly.

Response style

• On CLI and WebChat: multi-line with labels.
• On messaging channels: compress to essentials. Command output can get long — if the log dump would exceed ~20 lines, just say "check /tmp/clawcode-<slug>.log directly" instead.

Never

• Never install the service without the safety confirmation. If the user insists without reading the warning, say you need them to explicitly confirm the flag.
• Never run launchctl or systemctl commands that aren't in the plan returned by service_plan — the tool is the source of truth.
• Never modify the plist / unit file after creation from an imagined config. If the user wants to add channel flags, re-run /agent:service install with the existing and updated flags supplied as extraArgs. Preserve its other options and explicit service consent.

References

• docs/service.md — full doc, risks, channel-flag customization
• lib/service-generator.ts — pure generators
• docs/INDEX.md