# PenEcho for AI agents

PenEcho gives you a canvas beside the chat. You draw diagrams, plots and working widgets on it; your user writes on it by hand and you read that feedback. People and agents can work on one live Canvas by link.

- MCP server: `https://penecho.ai/mcp` (Streamable HTTP with OAuth). "Continue as guest" needs no account, and MCP calls use no PenEcho credits.
- Skill and plugin package: `https://penecho.ai/downloads/penecho-cloud-plugin.zip`

## When your user asks you to set up PenEcho

Do the whole setup yourself. Involve the user only for a native confirmation or the one-time browser authorization.

1. Download and unpack the package in a temporary folder, not in the user's project:

   ```bash
   cd "$(mktemp -d)"
   curl -fsSL https://penecho.ai/downloads/penecho-cloud-plugin.zip -o penecho-cloud-plugin.zip
   unzip -q penecho-cloud-plugin.zip
   ```

2. From that same folder, install the Skill and the MCP connection for the app you are running in:

   ```bash
   node penecho-cloud/skills/penecho-canvas/scripts/install.mjs --host claude --surface local   # Claude Code
   node penecho-cloud/skills/penecho-canvas/scripts/install.mjs --host codex --surface local    # Codex
   ```

   It installs the `penecho-canvas` Skill and adds an HTTP MCP server named `penecho-cloud` with URL `https://penecho.ai/mcp`. `penecho-cloud/INSTALL.md` has the details. Other MCP apps: add that server in the app's MCP settings. Cloud and web sessions (claude.ai, Claude Code on the web, Codex cloud) need the user to add the same URL as a connector; tell them exactly where.

3. Authorize once; this is the only step the user does. In Claude Code, ask them to type `/mcp`, choose `penecho-cloud`, then Authenticate (restart Claude Code first if it is not listed). In Codex, run `codex mcp login penecho-cloud`. A browser page opens; they choose "Continue as guest" or sign in.

4. Reload the MCP servers if the app needs it (in Claude Code, `/mcp` reconnects), then make one read-only call such as `penecho_list_canvases` to confirm the tools work.

5. Tell the user PenEcho is ready and suggest a first request, such as "Draw this project's architecture on the canvas". From then on, use PenEcho whenever they ask you to draw, diagram or show something on a canvas.

## Using the Canvas

- Draw right away: call `penecho_draw`, `penecho_plot` or `penecho_present_widget` with a `sessionKey` unique to this conversation instead of a `sessionId`. In a folder, first read `.penecho/project.json`: if its `projects` has an entry for this PenEcho server, pass that entry's `project`; otherwise pass `folder` (the folder's absolute path). The result's `project` is the folder's project: merge its `entry` into `projects` in `.penecho/project.json`, and create `.penecho/.gitignore` containing `*` if it is missing. Every agent in that folder then opens the same project. To open the page without drawing, call `penecho_open_workspace` with the same fields.
- Open the returned `url` once in your app's browser (a side panel if it has one). If you cannot open a browser, give the link to the user; it works once and stays valid for 30 minutes. Repeat the same call to get the `sessionId` for later calls.
- A folder's project holds Canvases as tabs; for a signed-in user it is also a project in their Cloud library, where its Canvases save themselves a few seconds after each change, so nobody needs to press Save. Other pages of the folder pick up those saves, keeping everyone's edits. Without an account they are kept for 7 days after their last change; signing in on the page keeps them. A free account keeps 3 projects; its other projects move to Trash after 7 days without changes unless the user keeps them with a paid plan. Agents start on the user's current tab. To use a tab of your own, create one with `penecho_open_canvas` (`create:true`) and pass its `documentId` to `penecho_start_session`; when a Canvas is full, continue on a new tab the same way.
- Read handwritten feedback with `penecho_inbox`. Details: `penecho_get_guidance`.

## Without a browser

If you cannot open a browser, or you send the user a link to open later (for example from a cloud or chat app), call `penecho_create_live_canvas` with a title and a stable `sessionKey`, and give the user its `url`. Draw with its `sessionId` using `penecho_present_widget`, `penecho_draw`, `penecho_plot` or `penecho_edit_canvas` (`create_text`). Everyone with the link sees your work live and can draw or write back; read what they add with `penecho_inbox` (`capture:true` adds a picture).

Tell the user that Cloud clears this Canvas 7 days after its last change unless they sign in on the page and save it, or download a PDF. To turn the link off for everyone, call `penecho_close_session` with `endLink:true`; that also deletes the Canvas.

## Collaborating on a live Canvas

The user chooses Collaborate. Everyone with the collaboration link draws on the same Canvas at once, and ink drawn at the same moment is kept from everyone. No account is needed to start: without one, Cloud keeps the shared copy 7 days after its last change, and signing in to save it keeps the same link. Changes appear live without saving; saving still keeps Cloud revisions. Stopping collaboration ends the link for everyone holding it. Share gives a separate view-only link.
