All Docs/Connect a Local Agent to a Session

Connect a Local Agent to a Session

Sometimes a chat session needs an agent that can read your code and run things on your machine — not just reason about it in the browser. DevSpec’s path for that is bring-your-own agent (continuous remote control): attach your coding agent to a session and work from the web or Agents page while it acts on your machine.

Product story: Bring your own agent · Full how-to: Bring Your Own Agent docs

One-shot “Brainstorm together” / “Get an answer” modes are retired. Use remote control instead: it is better for multi-turn work, multi-person sessions, and reconnecting later from the Sessions list or Agents page.

Two ways in

Agent-first (from your terminal)

In your preferred coding tool, invoke its DevSpec remote-control workflow with --new for a new private control channel (unique friendly codename). Command-based hosts expose names such as /devspec:devspec.remote, /devspec.remote, or /devspec-remote; Codex exposes DevSpec: Remote as a skill instead. In Codex, run /skills, choose DevSpec: Remote, and send it with --new — /devspec-remote is not a registered Codex slash command.

Codex's no-argument mode is intentionally different: it registers the thread as a sessionless available agent on the Agents page. Use --new for a new session, or --session <uuid> for an existing one. Disconnect from the same connected TUI by choosing DevSpec: Remote Stop from /skills.

Soft-reconnect after stop only applies to that same conversation, never another tool’s or folder’s leftover state. Multiple terminals can each run their own remote without disturbing each other.

Session-first (from the web)

Open any project session you can access → share / send surface (Your machine):

Attach agent to this session — copies the correct tool-specific command or skill prompt with --session <uuid> so the agent attaches to this session only (no create_session).
Start new remote control — copies your preferred tool’s agent-first remote command (new channel).
Copy load-session prompt — optional: have an agent load transcript context only (not a continuous connection).

How continuous control works

Your local agent heartbeats so Agents + session chips show live. Presence does not authorize action-item work.
In the web composer you can Post (advisory room context) or Send to one exact local-agent connection.
For every message the server checks exact target plus that connection's current command_authority. The owner and configured project/allowlist delegates may be authorized; every other message remains advisory.
Pollers act only when remote_control.is_controller_instruction is true. is_owner_instruction is a compatibility alias for the same server decision, not an owner-only rule.
If the command requests action-item implementation, the agent calls reserve_work_items with the requested ids in order, then claim_work_item one at a time. Internal reservation assignment rows are not delivery.
Agent replies appear live via post_session_message. Explicit owner-scoped automation runs remain a separate surface.

Before it’ll work

Preferred coding tool configured in DevSpec preferences.
MCP token working (verify_agent_connection / plugin setup).
Desktop for launching tools; phone can still message a live remote session.
The connection owner alone may attach, heartbeat, post as, or apply typed lifecycle controls to that connection. Conversational command authority is separate and may include server-authorized delegates.