canvas v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/2e7a536276b5f75f.

---
name: canvas
description: Operate Pulse Canvas workspaces — read user-curated context, write results, create nodes
version: 1.0.0
---

# Pulse Canvas

Interact with canvas workspaces via the `pulse-canvas` CLI. The canvas is a shared workspace between humans and agents.

The current workspace ID is available via `$PULSE_CANVAS_WORKSPACE_ID` environment variable (auto-set by canvas). All `node` and `context` commands use it automatically — no need to pass workspace ID explicitly.

Whenever `$PULSE_CANVAS_WORKSPACE_ID` is set, treat the canvas as required user-provided context. Before planning, coding, reviewing, or answering a workspace task, run `pulse-canvas context --format json` and use that result alongside repository files.

## Core Commands

### Read workspace context (start here)
```bash
pulse-canvas context --format json
```
Returns all nodes with structured info: file paths, frame groups, labels.

### List nodes
```bash
pulse-canvas node list --format json
```

### Read a node
```bash
pulse-canvas node read <nodeId> --format json
```

### Write to a node
```bash
pulse-canvas node write <nodeId> --content "..."
```

### Create a node
```bash
pulse-canvas node create --type file --title "Report" --data '{"content":"..."}'
```

Supported `--type` values: `file`, `terminal`, `frame`, `agent`, `mindmap`.

#### Mindmap

For mindmaps, pass the recursive topic tree under `data.root`. Topic ids are auto-generated — do NOT supply them yourself. If `--data` is omitted a placeholder root is inserted.

```bash
pulse-canvas node create --type mindmap --title "Roadmap" --data '{
  "root": {
    "text": "Roadmap",
    "children": [
      { "text": "Q1", "children": [
        { "text": "Ship MVP" },
        { "text": "Onboard 10 users" }
      ]},
      { "text": "Q2", "children": [
        { "text": "Public beta" }
      ]}
    ]
  }
}'
```

Topic shape: `{ text: string, children?: Topic[], color?: string, collapsed?: boolean }` (recursive). Use this whenever the user asks for a mindmap / brainstorm / outline that should be laid out radially rather than as a flat text node.

### Create an edge (connection between nodes)
```bash
pulse-canvas edge create --from <nodeId> --to <nodeId> --label "depends on" --kind dependency --format json
```

### List edges
```bash
pulse-canvas edge list --format json
```

### Delete an edge
```bash
pulse-canvas edge delete <edgeId> --format json
```

### List workspaces
```bash
pulse-canvas workspace list --format json
```

### Send input to a running agent node
```bash
pulse-canvas agent send <nodeId> --input "..."
```
Use this for follow-up prompts, approvals, corrections, or redirections to an already-running agent node. Enter is appended automatically.

Requirements:
- target node type must be `agent`
- agent status must be `running`
- the workspace must be open in Pulse Canvas (so the runtime is reachable)
- the node's PTY session must still be alive (closing the node tears it down)

Do NOT use `node write` for agent nodes — `node write` only modifies file/frame/group content. `agent send` delivers live input to the PTY session and is the only correct channel for talking to a running agent.

### Operate a live webpage

When Pulse Canvas is running, discover the runtime capabilities before using them:

```bash
pulse-canvas runtime capabilities --format json
```

Prefer structured capabilities such as page read, click, and fill. If the user asks for behavior those capabilities cannot express, execute a JavaScript function body inside an open iframe node or right-dock link tab:

```bash
printf '%s' 'return { title: document.title, links: document.links.length }' |
  pulse-canvas runtime eval --node <nodeId> --stdin --format json
```

Requirements:
- Pulse Canvas must be running with **Agent runtime control** and **Webview page control (agent)** enabled.
- The target must be an open iframe node in URL mode or a right-dock link tab.
- Sensitive pages and unsafe URL schemes remain blocked by the app policy.
- Use `runtime eval` sparingly, return JSON-serialisable data, and read the page again after a mutation to verify the outcome.
- Runtime scripts execute in the target webpage, never in the Electron main process.

## Usage Principles
- Before starting a task, run `pulse-canvas context --format json` to understand the user's canvas layout and intent
- Files on the canvas = files the user considers important — prioritize them
- Frame groups = file associations — understand files in the same group together
- Edges = relationships — understand how frames and nodes connect to each other
- After completing work, write results back to the canvas for the user to review
- Prefer discovered structured runtime capabilities over `runtime eval`; use arbitrary scripts only for non-preset behavior