Connect an agent (Velloo docs)

The canvas and connected agents share one local daemon per design folder. That gives them one live state and one mutation path: an agent edit appears in the browser, and human feedback on the canvas is available to the agent.

Let Velloo write the configuration

velloo connect

The interactive flow detects installed agents, shows existing wiring, and offers global or project-only configuration. Without a terminal it wires Claude Code and Cursor at project scope.

Agent	Project	Global
Claude Code	`claude-code`	`claude-code-global`
Cursor	`cursor`	`cursor-global`
Codex CLI	`codex`	`codex-global`
Continue	`continue`	`continue-global`
opencode	`opencode`	`opencode-global`
Gemini CLI	`gemini`	`gemini-global`
VS Code / GitHub Copilot	`vscode`	None
Claude Desktop	None	`claude-desktop`
Droid	None	`droid-global`
Cline	None	`cline-global`
Windsurf	None	`windsurf-global`

Restart the agent after wiring it.

What it writes

Besides each agent’s MCP configuration, connect installs the guidance that agent reads:

Claude Code: the Velloo plugin (skills, commands, and subagents) as a local marketplace at ~/.velloo/claude-plugins, registered and enabled in ~/.claude/settings.json. Only Velloo’s entries there are touched.
opencode, Droid, Cline, Gemini CLI, and Codex: skill copies in the project’s .agents/skills/.
Gemini CLI: also a Gemini extension at ~/.velloo/gemini-extension.
Cursor: a project rule at .cursor/rules/velloo.mdc.

velloo upgrade refreshes whatever guidance is already installed; wiring something new stays velloo connect.

Flags

velloo connect --agent claude-code-global,cursor-global
velloo connect --agent manual        # print a config for any other MCP client
velloo connect --http --mcp-url http://127.0.0.1:7301/mcp

--agent takes comma-separated ids from the table above; manual prints the configuration instead of writing files.
--project-root sets where project-scoped files go. The default is the nearest package.json above the design folder, otherwise its parent.
--http wires the HTTP transport, where the agent dials a running server, instead of stdio. --mcp-url sets that URL.
--no-skill writes only the MCP configuration and skips the plugin, skills, extension, and rule.

Manual stdio setup

Most MCP clients can spawn Velloo themselves:

{
  "mcpServers": {
    "velloo": { "command": "velloo", "args": ["mcp"] }
  }
}

Project-scoped configuration normally uses plain velloo mcp, so moving or renaming a design does not leave a stale path in the client. Velloo resolves a design from the working directory, application binding, the only associated design, or defaultDesign. You can still pin a deliberate name or path after mcp.

When a checkout has several designs, the session instructions identify the current one and the agent can call list_designs. A stdio session can call switch_design without restarting. If resolution is still ambiguous, Velloo opens the first design by name and tells the agent to confirm before changing anything. HTTP clients cannot switch in place; reconnect with velloo mcp --http <name> instead.

For a client that dials a URL, run velloo mcp --http. It starts or attaches to the daemon and prints the Streamable HTTP endpoint to put in that client’s configuration.

Guided by default

The default MCP surface is guided. It presents three compact tools:

call_velloo invokes one native operation.
run_velloo_plan runs a deliberate sequence of operations.
operation_schema returns the exact input schema for an operation.

The full catalogue still covers discovery, composition, focused edits, lifecycle, themes, visual verification, annotations, and code emission. Guided mode saves context by loading the operation contract when it is needed; it does not remove capabilities.

If a client performs better with conventional function schemas, use:

velloo mcp --surface full

Or set VELLOO_MCP_SURFACE=full in the environment that starts the MCP server. Both modes call the same operations against the same live state. The old progressive-disclosure and reveal_tools setup is no longer the current model.

Runtime guidance

At connection time Velloo adapts its instructions to the folder’s provider and styling channel. It also exposes focused MCP guides at velloo://guide/*. Prefer those runtime resources and operation_schema over remembered argument shapes; they describe the build actually installed on the machine.

Working with your agent How to structure the design and verification loop once connected. MCP overview The surfaces, operation families, and native-operation references. CLI Run, connect, MCP, status, and stop in the wider command map.