|
| 1 | +--- |
| 2 | +title: 'Working with Canvas Extensions' |
| 3 | +description: 'Create and iterate on GitHub Copilot app canvases using /create-canvas, then shape them into reusable project or personal extensions.' |
| 4 | +authors: |
| 5 | + - GitHub Copilot Learning Hub Team |
| 6 | +lastUpdated: 2026-06-17 |
| 7 | +estimatedReadingTime: '8 minutes' |
| 8 | +tags: |
| 9 | + - copilot-app |
| 10 | + - canvases |
| 11 | + - canvas-extensions |
| 12 | +relatedArticles: |
| 13 | + - ./github-copilot-app.md |
| 14 | + - ./agents-and-subagents.md |
| 15 | + - ./using-copilot-coding-agent.md |
| 16 | +prerequisites: |
| 17 | + - Access to the GitHub Copilot app |
| 18 | + - Basic familiarity with GitHub Copilot agent sessions |
| 19 | +--- |
| 20 | + |
| 21 | +Canvas extensions give you shared, interactive work surfaces inside the GitHub Copilot app. Instead of keeping all progress in chat, you can move work into a visible artifact (such as a board, document, checklist, or browser-oriented surface) that both people and agents can update. |
| 22 | + |
| 23 | +This guide explains what canvases can do, how to create one with `/create-canvas`, and how to use patterns from this repository as reference implementations. |
| 24 | + |
| 25 | +## What canvases can do |
| 26 | + |
| 27 | +A canvas is a bidirectional surface: |
| 28 | + |
| 29 | +- You can interact through UI controls (buttons, forms, filters, cards, etc.) |
| 30 | +- The agent can call canvas capabilities to update that same state |
| 31 | +- You can iterate quickly by asking the agent to add or revise capabilities |
| 32 | + |
| 33 | +This makes canvases especially useful for workflows where visibility and steering matter, for example: |
| 34 | + |
| 35 | +- Triage boards |
| 36 | +- Planning documents |
| 37 | +- Live browser-assisted workflows |
| 38 | +- Release coordination surfaces |
| 39 | + |
| 40 | +## Create a canvas with `/create-canvas` |
| 41 | + |
| 42 | +In the GitHub Copilot app, create canvases from an active session using the `/create-canvas` skill. |
| 43 | + |
| 44 | +1. Open or start an agent session. |
| 45 | +2. In the prompt box, run `/create-canvas` and describe: |
| 46 | + - the workflow you want |
| 47 | + - what people should do in the UI |
| 48 | + - what the agent should do via callable capabilities |
| 49 | +3. Let the agent generate the extension and open it in the right panel. |
| 50 | +4. Continue iterating by asking for capability or UI changes. |
| 51 | + |
| 52 | +### Prompt patterns that work well |
| 53 | + |
| 54 | +Use explicit capability language in your prompt: |
| 55 | + |
| 56 | +```text |
| 57 | +/create-canvas Create an issue triage canvas with list filtering, label editing, and quick-priority actions. Add capabilities for get_issues, update_priority, and apply_label. |
| 58 | +``` |
| 59 | + |
| 60 | +```text |
| 61 | +/create-canvas Create a release checklist canvas that tracks milestones and owners. Add capabilities for add_item, assign_owner, mark_done, and export_summary. |
| 62 | +``` |
| 63 | + |
| 64 | +```text |
| 65 | +/create-canvas Create a markdown planning canvas that combines my open PRs and issues, and lets me launch and track agent sessions from the canvas. |
| 66 | +``` |
| 67 | + |
| 68 | +## Choose scope: project or personal |
| 69 | + |
| 70 | +When creating a canvas extension, choose where it should live: |
| 71 | + |
| 72 | +- **Project scope**: `.github/extensions` (shared with the repository team) |
| 73 | +- **User scope**: `~/.copilot/extensions` (personal to your machine) |
| 74 | + |
| 75 | +Use project scope when the workflow is team-relevant, and user scope for personal experiments or private workflows. |
| 76 | + |
| 77 | +## Typical extension structure |
| 78 | + |
| 79 | +Canvas extensions can vary, but most include: |
| 80 | + |
| 81 | +- `package.json` for metadata and dependencies |
| 82 | +- `extension.mjs` (or another entry module) for canvas behavior and capabilities |
| 83 | +- Optional UI files (`index.html`, assets) for richer panel controls |
| 84 | +- Optional persisted artifacts/state files |
| 85 | + |
| 86 | +## Best practices |
| 87 | + |
| 88 | +### 1. Choose storage scope intentionally |
| 89 | + |
| 90 | +Default canvas state is often session-scoped. If you only need state for the current session, keep it in session storage paths such as: |
| 91 | + |
| 92 | +- `<copilot_home>/session-state/<sessionId>/files/<whatever>` |
| 93 | + |
| 94 | +If you want data to persist across multiple sessions for the same extension, use extension-scoped storage such as: |
| 95 | + |
| 96 | +- `<copilot_home>/extensions/<extensionId>/<whatever>` |
| 97 | + |
| 98 | +This split keeps ephemeral workflow data separate from longer-lived user data. |
| 99 | + |
| 100 | +### 2. Use `joinSession` handlers as your canvas-agent contract |
| 101 | + |
| 102 | +Treat `joinSession` + `createCanvas` as the contract between UI interactions and agent-callable actions: |
| 103 | + |
| 104 | +- Define clear canvas actions and schemas in `createCanvas(...)` |
| 105 | +- Keep action names verb-oriented and predictable (`get_*`, `apply_*`, `sync_*`) |
| 106 | +- Return structured state from handlers so both the UI and agent remain in sync |
| 107 | + |
| 108 | +Reference implementations: |
| 109 | + |
| 110 | +- SDK docs/source: [`joinSession`](https://github.com/github/copilot-sdk/blob/main/nodejs/docs/extensions.md), [`createCanvas`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/canvas.ts) |
| 111 | +- Repo example: [`extensions/backlog-swipe-triage/extension.mjs`](https://github.com/github/awesome-copilot/blob/main/extensions/backlog-swipe-triage/extension.mjs) |
| 112 | +- Persistent user-scoped path example: [`extensions/chromium-control-canvas/extension.mjs`](https://github.com/github/awesome-copilot/blob/main/extensions/chromium-control-canvas/extension.mjs) |
| 113 | + |
| 114 | +## Examples from this repository |
| 115 | + |
| 116 | +Use these extension folders as concrete references: |
| 117 | + |
| 118 | +- [`Backlog Swipe Triage`](../../extensions/#backlog-swipe-triage): swipe-based issue triage surface for fast backlog decisions. |
| 119 | +- [`Release Notes Showcase`](../../extensions/#release-notes-showcase): release notes authoring and review canvas pattern. |
| 120 | +- [`Chromium Control Canvas`](../../extensions/#chromium-control-canvas): advanced canvas that coordinates panel controls with a real headful Chromium window. |
| 121 | + |
| 122 | +These examples show different complexity levels, from focused workflow boards to richer UI + automation integrations. |
| 123 | + |
| 124 | +## Iterating after first creation |
| 125 | + |
| 126 | +Treat the first `/create-canvas` result as version one. Then refine in-place: |
| 127 | + |
| 128 | +- Add or rename capabilities as your workflow evolves |
| 129 | +- Simplify controls that are rarely used |
| 130 | +- Add guardrails around sensitive actions |
| 131 | +- Keep capability names clear and action-oriented |
| 132 | + |
| 133 | +The fastest loop is: **use the canvas**, note friction, and ask the agent for a targeted update. |
| 134 | + |
| 135 | +## Next steps |
| 136 | + |
| 137 | +- Review the [GitHub Copilot app overview](../github-copilot-app/) for broader session and workflow concepts. |
| 138 | +- Browse the [Canvas Extensions page](../../extensions/) for discoverable extensions. |
| 139 | +- Fork one of the example extension folders above and adapt it to your own workflow. |
| 140 | + |
| 141 | +--- |
0 commit comments