---
title: Local Agent Integration Plan
description: Plan for connecting Codex and Claude to the canvas through Canvas Agent and MCP
---

# Local Agent Integration Plan

## Goal

Allow locally authenticated coding agents to read and modify the active browser canvas without moving canvas data, credentials, or local permissions to a hosted backend.

## Architecture

Canvas Agent is the single local bridge. The browser synchronizes structured canvas state to it over authenticated HTTP and SSE. Codex and future Claude adapters use MCP tools exposed by Canvas Agent. Browser-side writes remain structured, reviewable, and undoable.

The service is divided into agent adapters, canvas state and tool handling, HTTP/SSE transport, and MCP exposure. Codex is the first adapter through `codex app-server`; Claude should use the Claude Agent SDK rather than duplicating canvas logic.

## Tool design

Tools should cover state and selection reads, node creation and updates, connections, batch operations, viewport and selection changes, and text, image, or video generation. High-level tools convert to a small set of canvas operations before the browser applies them.

## Side panel

The browser panel manages connection state, conversations, streaming events, model and reasoning settings, permissions, approvals, local Skills, diagnostics, and task cancellation. A turn is bound to its initiating `clientId` so focusing another browser tab cannot redirect its canvas operations.

## Security

- Bind to localhost and require a generated connection token.
- Pin the accepted browser origin.
- Keep local agent login and file permissions out of the hosted site.
- Make writes confirmable and undoable in the browser.
- Never redirect an active turn to another tab when its initiating page disconnects.

## Delivery stages

1. Expose canvas state and operations to local Codex through MCP.
2. Add the browser Codex panel with streaming conversations and history.
3. Add a Claude Agent SDK adapter using the same canvas tools.
4. Improve approvals, diagnostics, multi-tab behavior, Skills, and recovery.

The MVP is complete when an agent can connect to the active canvas, read state and selection, apply visible node operations, start a generation workflow, return structured errors, and remain isolated across tabs.
