Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.signalrooms.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Chat with an AI agent during setup

Status: Current setup reference. Designed for operators running Hermes (or any AI agent with local shell access) who want the agent to triage Warmr setup problems before reaching out to support.

​
What this gives you

An agent that can:
  • Look at your live Warmr install and answer “is this iPhone ready to run a warmup.”
  • Tell you the exact warmrctl command to run next when something is off.
  • Read SignalRoom docs and quote the relevant section instead of you searching.
It does not install Warmr, sign anything, or take any action that mutates state on its own. The whole loop is read-only inspection + recommendation. The operator still types the action commands by hand.

​
What you install

Nothing new. This entire setup is configuration on the agent side. You already have:
  • Warmr.app, installed via DMG.
  • warmrctl, installed via Settings → Command Line Tool → Install. If not installed yet, open the macOS Settings window (Cmd-,), go to the Command Line tab, click Install.
  • An AI agent with local shell access (Hermes, Claude Code, Codex CLI, or any agent that can shell out via Bash / terminal tools).
If all three are in place, skip to Agent configuration.

​
Why warmrctl is the bridge

Warmr’s control plane is a local Unix Domain Socket at ~/Library/Application Support/Warmr/control/control.sock speaking JSON-RPC. The agent does not talk to the socket directly; it shells out to warmrctl --json <subcommand>, which wraps the socket protocol in a stable CLI surface. This matters because:
  • Every command emits a JSON envelope with a schema: "1.0" marker. The agent parses the response structurally instead of regexing free text.
  • Read-only commands (status, devices list, devices doctor, templates list, thread list, logs --follow) run without operator approval, so the agent can answer most diagnostic questions on its own.
  • Action commands (thread start, thread stop, evidence export, app start | stop | restart) sit behind a two-gate approval model. The agent can suggest them; the operator runs them.

​
Agent configuration

​
Step 1: Expose warmrctl as a tool to your agent

The agent needs permission to run warmrctl and the path to the binary. Default install paths: 
/usr/local/bin/warmrctl    # system-wide install (Settings → Command Line)
~/.local/bin/warmrctl       # per-user install (Settings → Show shell commands → User PATH)
Whichever your install used, the agent’s shell needs that directory on PATH. Hermes-style agents that wrap a shell tool usually pick it up automatically from your shell’s PATH. For Claude Code or Codex specifically, allowlist these read-only commands in .claude/settings.json (or the Codex equivalent) so the agent does not prompt on every invocation: 
{
  "permissions": {
    "allow": [
      "Bash(warmrctl --json status*)",
      "Bash(warmrctl --json devices list*)",
      "Bash(warmrctl --json devices doctor*)",
      "Bash(warmrctl --json templates list*)",
      "Bash(warmrctl --json thread list*)",
      "Bash(warmrctl --json logs --follow*)"
    ]
  }
}
Action commands (thread start, evidence export, etc.) deliberately stay out of the allowlist. The operator approves them per-invocation.

​
Step 2: Give the agent a setup-helper system prompt

The system prompt tells the agent which docs are canonical, which commands to run first, and how to talk to the operator. Drop this into the agent’s startup prompt (Hermes config, Claude Code project memory, Codex config, etc.): 
You are a setup helper for SignalRoom (also called Warmr internally —
same product, two artifact names). The operator runs the macOS app on
their own Mac and drives real iPhones over USB.

Canonical docs live at https://docs.signalrooms.xyz. When the operator
asks a setup question, prefer linking the exact section over restating
it.

Diagnostic verbs you may run without asking:

- warmrctl --json status
- warmrctl --json devices list
- warmrctl --json devices doctor
- warmrctl --json devices doctor --udid <UDID>
- warmrctl --json templates list
- warmrctl --json thread list
- warmrctl --json logs --follow --configuration-id <UUID>

Action verbs the operator must approve explicitly (do NOT run them
yourself, only suggest):

- warmrctl thread start --configuration-id <UUID>
- warmrctl thread stop --configuration-id <UUID>
- warmrctl evidence export
- warmrctl app start | stop | restart

Reading devices.doctor output:

- overall = "ready", nextAction = "none": lane is good, no action.
- overall = "ready", nextAction = "start_thread": lane is good but no
  warmup has started yet. Tell the operator to click Start in Threads,
  or to run `warmrctl thread start --configuration-id <UUID>` if they
  already have a configuration.
- overall = "needs_action", nextAction = "install_runner": runner is
  missing. Point the operator at https://docs.signalrooms.xyz/signalroom/setup/trust-runner
  and have them click Install on Warmr's Devices page.
- overall = "blocked", nextAction = "reconnect_cable": iPhone is not
  visible over USB. Have them check the cable, the USB hub power, and
  the "Trust This Computer" prompt on the iPhone.

When you do not know, say so. Quote the doc URL the operator should
read, then stop. Do not invent commands, env vars, or settings.

​
Step 3: Test the loop

Ask the agent in chat:
“Is my warmr setup ready to run a warmup right now?”
The agent should respond by running warmrctl --json status followed by warmrctl --json devices doctor, summarizing the readiness state per device, and recommending the next action. If it tries to run a write command without asking first, the system prompt needs more guardrails. For agents helping an operator through first-time setup, this longer prompt walks them through the whole device-readiness ladder: 
You are walking a new operator through the first 30 minutes of
SignalRoom setup. They have already installed Warmr.app.

Stage 1: Mac host check.
  Run: warmrctl --json status
  If it fails with "control socket missing", tell them to launch
  Warmr.app first.

Stage 2: iPhone setup checklist.
  Confirm in order:
  - iPhone plugged in over USB and trusted
  - Developer Mode on (Settings → Privacy & Security)
  - Auto-Lock = Never
  - Appearance = Light (not Dark, not Automatic)
  - StandBy = Off
  - TikTok installed, opened once, signed into one account
  For each, link the relevant section of
  https://docs.signalrooms.xyz/signalroom/setup/developer-mode
  Stop and ask the operator to confirm each box before moving on.

Stage 3: Runner install.
  Have them open Warmr → Devices → Install (this requires their
  Apple Developer account via App Store Connect API per
  https://docs.signalrooms.xyz/signalroom/setup/trust-runner).
  When they say it is done, run:
    warmrctl --json devices doctor
  Confirm runnerInstalled = true.

Stage 4: First warmup.
  Run: warmrctl --json templates list
  If empty, tell them to create one in the Templates tab using the
  "Safe activity for a new account" preset from
  https://docs.signalrooms.xyz/signalroom/how-to/activity-workflows
  Then walk them through creating a thread configuration in the
  Threads tab. When ready, prompt them to click Start in the GUI
  (or hand them the warmrctl thread start command). Do NOT start
  the thread yourself.

After Stage 4, hand control back to the operator. They run; you
read the logs if they ask.

​
Privacy and safety

  • warmrctl never leaves the operator’s Mac. It talks to the local Unix Domain Socket only.
  • The agent never sees TikTok credentials. Account credentials live in macOS Keychain and are accessed by Warmr.app directly during a warmup; they never appear in warmrctl JSON responses.
  • The agent never starts a thread on its own. Per the system prompt, action commands are suggestion-only. The operator types them or clicks Start in the GUI.
  • Read-only commands cannot mutate state. status, devices list, devices doctor, templates list, thread list, and logs --follow are inert.

​
What’s not yet wired

  • warmrctl device onboard — interactive walkthrough that emits structured state per step. Not shipped; the system prompt above does it manually for now.
  • Live WDA/Bridge HTTP probes inside devices doctor — current doctor reports inferred state from the orchestrator. Live :wdaHostPort/status and :bridgeHostPort/health probes are a planned follow-up so the agent can detect “lane allocated but the device is not responding.”
  • iOS settings probes — the agent can ask the operator to confirm Developer Mode is on, but cannot verify it remotely yet.
These are tracked as follow-up Linear issues; this page will update when they ship.