All Docs/Bring Your Own Agent

Bring Your Own Agent

DevSpec is the collaboration and memory layer. Your coding agents—running in tools such as Cursor, Claude Code, and other MCP clients—do the heavy thinking on your machines, on the plans you already pay for. This guide covers how to connect, attach, and work safely in that model.

Why this exists: the marketing story lives at /bring-your-own-agent. This page is the how-to.

Related paths

MCP Endpoint — tokens and tool access
Connect a Local Agent to a Session — remote-control attach details
Autopilot — persistent runner capacity using the same reserve-then-claim implementation contract

What “bring your own agent” means

DevSpec holds	Your coding agent holds
Sessions, transcripts, mentions	Model choice and thinking
Memories, decisions, conventions	File edits on your machine
Action items, commits, deploys, verification	Your Cursor / Claude / MCP subscription

Presence, conversation, and implementation are separate. Bring-your-own agent provides a live local connection that can attach to a room; it does not stage, route, or deliver action-item work. A current explicit user request authorizes implementation, and the addressed agent reserves the requested items before claiming them in order.

Connect your coding agent

Create an MCP token under You → Connections (read-write if the agent should claim work and record implementations).
Install the DevSpec plugin or extension for your tool (Cursor, Claude Code, etc.), or paste the MCP config from the token screen.
Run the connection check your setup wizard or plugin provides (for example verify_agent_connection) so the agent can reach DevSpec.

Full token and IDE snippets: MCP Endpoint.

Attach to a session

Two common entry points:

Agent-first (from your terminal)

Invoke the DevSpec remote workflow for your tool with --new to create and attach a new private control channel for that terminal conversation:

Tool	How to invoke remote control
Claude Code	`/devspec:devspec.remote --new`
OpenCode	`/devspec.remote --new`
Grok Build / Antigravity	`/devspec-remote --new`
Cursor	Run the `devspec.remote` skill with `--new` in classic IDE Agent chat.
Codex	Run `/skills`, choose DevSpec: Remote, and send it with `--new`. Codex plugin skills are not custom `/devspec-*` slash commands.

In Codex, invoking DevSpec: Remote with no arguments deliberately registers a sessionless available agent on the Agents page; use --new when you want a session and live transcript. To disconnect, run /skills and choose DevSpec: Remote Stop.

Session-first (from the web)

Open a project session you own → 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 joins this room.
Start new remote control — agent-first private channel.
Copy load-session prompt — optional transcript context only (not a continuous connection).

Once attached, heartbeats keep the Agents page and session chips live. Deeper mechanics: Connect a Local Agent to a Session.

Working in the room

Teammates discuss in the DevSpec session as usual.
Post keeps a message in the room as advisory context without commanding a local agent.
Send names one exact connection. The server marks the message as a command only when its target matches and the sender is authorized by that connection's command_authority (owner, project, or named allowlist). Pollers act only when remote_control.is_controller_instruction is true.
The agent replies with post_session_message; the transcript stays two-sided. Authorized delegated commands retain the actual requester's server-stamped provenance.
When the command requests action-item implementation, the agent calls reserve_work_items with those item ids in the requested order, then claim_work_item one at a time. It tags commits with [devspec:<id>] and calls record_implementation so deploy and verification stay linked.

Permissions and security

A local coding agent has real OS authority on the machine it runs on. DevSpec treats that carefully:

Rule	Behaviour today
Who can attach	A project member with access to the session may attach a connection they own. Several connections may attach to one room; each keeps its own identity.
Who operates the connection	Only the connection owner may register, attach, heartbeat, post as, or apply typed lifecycle controls to that connection. Typed controls remain separate from conversational command authority.
Who may send a command	The owner is always authorized. Depending on the connection's current `command_authority`, current project members or specifically allowlisted current members may also send commands. The server resolves this from membership and grant records, never message text.
Exact target	A connection-aware command must name that connection. A command for a sibling connection and an untargeted room post are advisory to this agent.
Room visibility	Teammates can see shared transcript context; visibility alone never grants command authority.
Named grants	`allowlist` authority uses explicit per-connection named grants. Revocation or loss of project membership removes effective delegated authority.

A shared session is not ambient shared remote code execution. The only conversational commands are exact-target messages the server marks with remote_control.is_controller_instruction=true after checking command_authority.

Multi-agent rooms

Multiple live local connections can share one session. Each receives room context, but command decisions are per message and per exact target. Use the connection-specific Send target so one instruction does not wake a sibling terminal.

Named delegated grants

A connection owner can choose named allowlist authority for specific current project members. Authorized delegated commands remain attributed to the teammate who actually requested the work; they are never laundered into the connection owner's identity. The owner can revoke the grant without changing the connection.

Autopilot vs bring-your-own

	Bring your own agent	Persistent runner capacity
Presence	Interactive live connection, optionally attached to a room	Long-running connection that may be available while its user is away
Implementation authority	Current explicit user request, exact-target authorized canonical conversation command, or direct user-invoked implementation surface	The same implementation-authority contract; being online or unattended grants nothing
Work acquisition	Reserve the explicitly requested item ids, then claim one at a time	Reserve the explicitly requested item ids, then claim one at a time
Best for	Pair sessions, steering from phone, hands-on implementation	Longer-running capacity and explicitly requested batches

There is no execution mode, staged queue, or work router. Both connection shapes use the same implementation contract.

Troubleshooting checklist

MCP token valid and plugin/extension loaded?
Preferred coding tool set in DevSpec preferences?
Connection ownership correct for attach / heartbeat and typed controls?
Poller passing its exact connection_id and acting only on server-resolved commands (is_controller_instruction)?
Connection command_authority and any named grant match the intended delegated senders?
Feature flag / remote-control gate enabled for your org if required?