Skip to content

phone-first-setup.md

Latest commit

 

History

History
75 lines (63 loc) · 4 KB

phone-first-setup.md

File metadata and controls

75 lines (63 loc) · 4 KB
Raw

Phone-first setup: drive your agents from anywhere

This guide is for new users who want the full remote workflow: every coding agent reachable from a phone, one team room for coordination, and approval buttons for anything gated. It assumes you have at least one always-on or frequently-on machine (desktop, mini, laptop) where an agent runs.

The mental model: three surfaces

Getting this straight up front saves hours of confusion:

  1. The agent's session — its actual working brain. One conversation, living on the agent's machine. The provider app (Claude app for Claude Code agents, ChatGPT app for Codex agents) can open a window into this same session: what you type on the phone lands in the session, what the agent does shows on the phone. Same conversation, two screens.
  2. The team room — a shared channel (GroupMind) that you and every agent read and post to. Agents wake within seconds of a new message. This is where coordination happens: task handoffs, decisions, status.
  3. CodeWatch — the phone app that shows the room plus Approve/Deny buttons for gated actions (merges, privileged commands). Approvals are one tap; agents verify the button decision server-side.

Rule of thumb: talk to the team in the room; type into an agent's session only when you need to drive that specific agent directly.

One session per agent

Each agent has exactly one canonical session, ever. Don't open a second chat for a side task — you end up with two half-informed copies of the same agent, and (before ide-agent-kit's responder lock) both would answer the team room as the same handle with conflicting messages.

ide-agent-kit enforces the room half of this automatically: the SessionStart bootstrap claims a per-machine responder lock, so if a stray session starts anyway, it boots passive — it serves you directly if you type into it, but it never arms the room loop or posts as the agent. The first session keeps the room voice; the lock releases itself when that session's process exits.

Setup, per agent machine

  1. Install ide-agent-kit (Quick Start: agent key, installer, config) and run ide-agent-kit init --ide claude-code in the agent's working directory. This installs two hooks: the room poller (message notifications) and the session bootstrap (instant wake + responder lock). No manual arming — a fresh session self-arms.
  2. Connect the agent to the team room. In CodeWatch: add the room, then add the agent with its own handle and login key (each agent gets its own handle — don't share one key across agents).
  3. Make the session phone-drivable. Two paths, either works:
    • Start the agent's session from the provider app (Claude app → Code tab → new session on that machine). App-created sessions are drivable by construction.
    • Or, in an interactive terminal session, run /remote-control — it registers the running session, full history included. (This command is unavailable in headless/automation-launched sessions; that's expected — use the app-created path instead.)
  4. Verify. Type a marker word into the phone entry; the agent should see it in-session within seconds. Post a message in the team room; the agent should react without being poked.

What to expect day-to-day

  • From your phone you can: follow and steer everything in the room, approve gated actions with one tap in CodeWatch, and drop into any agent's session directly via the Claude/ChatGPT app when it needs hands-on driving.
  • Laptop agents sleep. An agent on a laptop is unreachable while the lid is closed or the machine suspends. Put agents that must always be reachable on an always-on machine.
  • Stale session entries. If you kill an agent's process, its entry may linger in the provider app's session list. It's inert — archive it from the app. Content matching (does the entry show the agent's real work?) is the reliable way to identify the live session.