Remote Control & Agents

pw code sessions are hosted by a background daemon on your machine, not by the terminal you started them in. That is what lets a session keep working after you quit, lets you browse and manage every session from one list, reach sessions on another machine with pw code attach, and view and drive a session from the web app with remote control.

Remote Control

Remote control makes a session viewable and drivable from the web app's Agents page. Turn it on from inside a session:

/rc

/rc (or /remote-control) accepts on (the default), off, and status. It answers with the session's address, https://<platform-host>/agents?session=<session-id>, and the status line shows a /rc badge while it is on. To start a session with remote control already on, pass --remote:

pw code --remote

From the web app you can follow the conversation as it streams, send prompts, answer approval prompts, and interrupt the agent. The session itself keeps running on your machine, and its transcript stays there.

/rc off disconnects remote access to the session. Work that was already accepted keeps running.

Remote Control Settings

These settings live in your user settings file, ~/.config/pw/code.json, under remoteControl. A workspace's settings files cannot set them, so a repository can never open your machine to remote drive. The first three are rows in /settings.

Key	`/settings` row	Default	Description
`newSessions`	Remote control for new sessions	`false`	Start every new session with remote control on. `--remote=false` overrides it for one launch.
`start`	Allow remote session start	`false`	Let the web app start new sessions on this machine.
`maxPermissionMode`	Remote permission ceiling	`accept-edits`	The highest permission mode a remote turn may run at: `read-only`, `plan`, `accept-edits`, or `bypass-permissions`.
`selfConnect`	(none)	`true`	Let the daemon connect this machine to the platform itself while anything here is open to remote control. Set `false` to make the machine reachable only through a `pw` agent running on it.

{
  "remoteControl": {
    "newSessions": true,
    "maxPermissionMode": "read-only"
  }
}

What Remote Turns May Do

A prompt sent from the web app runs with tighter rules than one typed in your terminal:

The ceiling applies. The turn runs at the session's permission mode, lowered to the remote permission ceiling when the mode is higher.
Your standing approvals do not apply. Allow rules, directories you approved earlier, and skill tool grants do not pre-approve anything on a remote turn, so the action goes through an approval prompt instead.
Configuration files always ask. Writes to the workspace's .agents/ directory or .mcp.json prompt for approval even in bypass-permissions mode.
Skills and commands that run shell commands while expanding are refused when invoked remotely.

A session that runs above the ceiling, for example in bypass-permissions with the default ceiling, can still be watched and interrupted from the web app, but remote clients cannot send it prompts or approve its actions. /rc status says so.

The Background Daemon

The first pw code you run starts a per-user daemon in the background. It hosts every session on this machine, interactive and one-shot alike, and each terminal running pw code is a client of it.

Quitting detaches. A running turn finishes in the background, and the exit message prints the command to reconnect. Resume the session to pick it back up.
It keeps running until stopped. The daemon does not exit when idle. Scripts and CI jobs that run pw code -p can stop it afterwards with pw code daemon stop.
Upgrades are picked up. After you update pw, the outdated daemon is replaced automatically the next time pw code starts while it hosts no live sessions.
Sign-ins are picked up. After pw auth in another shell, new sessions use the new credentials without a restart.

Manage it with the pw code daemon commands:

# Show the daemon's pid, version, live session count, and remote control policy
pw code daemon status
 
# Start it in the background (pw code does this automatically)
pw code daemon start
 
# Stop it: running turns end and every session closes; sessions stay saved and resumable
pw code daemon stop

The daemon's socket and log live under ~/.local/state/pw (or $XDG_STATE_HOME/pw), named after the host so that machines sharing a home directory each run their own: code-<host>.sock and code-daemon-<host>.log. A log that has grown past 8 MB is moved to code-daemon-<host>.log.1 the next time the daemon starts. See pw code daemon for the command reference.

Attaching to Another Machine

pw code attach connects your terminal to the sessions on another resource over SSH. The sessions run on the resource, with its files, tools, and session store; your terminal only shows and steers them.

# Browse the resource's sessions and pick one to resume
pw code attach my-cluster
 
# Attach to one session directly
pw code attach my-cluster/20260819-101500-ab12cd34
 
# Start a new session in a workspace on the resource
pw code attach -w /home/user/project -m org:openai/gpt-5.2 --allocation my-allocation my-cluster

You need SSH access to the resource, as for pw ssh, and a version of pw on it that includes the daemon. The daemon starts there automatically. For a new session, -w must be an absolute path on the resource, and -m, --effort, --allocation, and --permission-mode work as they do for pw code. Inside an attached session, /auth asks for a pasted API key or token, since the resource keeps its own sign-in. See pw code attach for the command reference.

The Agents List

The agents list shows every pw code session on this machine with its live status, grouped and filterable, with a details pane for the selected session. Open it with /agents, with ← at an empty prompt, or from your shell:

# Open the agents list
pw agents
 
# Live sessions plus recent history, as text or JSON
pw agents -o text
pw agents -o json

Tabs across the top filter by status, each with a count: All, Needs you (waiting for an approval or an answer), Working, Ready, and Inactive. Sessions live on another host that shares your home directory are marked as such. Pinned sessions are listed first.

Key	Action
`↑`/`↓`, `PgUp`/`PgDn`	Move through the list.
`Enter` or `→`	Open the selected session.
`Tab` / `Shift`+`Tab`	Cycle the status filter.
`g`	Change grouping: by project, status, or model.
`/` or `F3`	Search.
`n`	Start a new session.
`w`	Start a new session in a new git worktree: a detached checkout of the repository's default branch, under `~/.local/state/pw/code-worktrees`.
`o`	Open the session picker across all saved sessions.
`f`	Fork the selected session into a new one with a copy of its history, and open it.
`r`	Rename the selected session.
`p`	Pin or unpin it.
`x`	Stop its running turn.
`a`	Archive it and its subagents (asks first).
`h`	Hide it from the list for now.
`Backspace`	Permanently delete it and its subagents (asks first).
`?`	Show the keys.
`Esc`	Go back.

The grouping you choose is saved as the agentsGrouping setting (project, status, or model). To change the keys, set agentsKeymap in ~/.config/pw/code.json to a map from action to keys. The actions are help, open, filter_next, filter_prev, group, search, new, new_worktree, resume, fork, rename, toggle_pin, stop, archive, hide, and delete; open_agents adds keys that open the list from the chat. An action given an empty list is unbound.

{
  "agentsGrouping": "status",
  "agentsKeymap": {
    "delete": ["ctrl+x"],
    "open_agents": ["ctrl+a"]
  }
}

See pw agents for the command reference.

pw code Overview: Feature overview and quick start
Sessions & Resume: How sessions are saved and resumed
Permissions: Permission modes and allow rules
Settings: The settings files and /settings menu
Non-Interactive Mode: One-shot runs and the daemon in CI
pw code daemon: Daemon command reference
pw code attach: Attach command reference
pw agents: Agents list command reference