[Feature] Proposal: add a visual, branching Canvas for agent interactions

[MrToyy]

Summary

Would the maintainers be open to adding a visual, branching Canvas to Nerve?

The Canvas would live alongside the existing Chat and Tasks views. It would provide a spatial way to organize agent interactions, continue a conversation, and fork alternative approaches from an earlier point without modifying the original OpenClaw transcript.

I have a working MVP in a personal fork:

https://github.com/MrToyy/openclaw-canvas

I am opening this issue before preparing pull requests because the feature is non-trivial, and I would like to confirm the product direction, architecture, and preferred PR boundaries first.

Motivation

A linear chat works well for a single conversation, but becomes harder to navigate when a user wants to:

• explore several approaches from the same earlier response;
• keep independent lines of investigation visible;
• compare the outputs and artifacts produced by different branches;
• return to an earlier point without resetting or rewriting the current session;
• organize multiple related agent sessions in one workspace.

The proposed Canvas represents complete user-to-agent interactions as nodes in a graph. Users can continue from the head of a branch or create a new branchfrom a completed historical interaction.

Proposed user model

• A Canvas is bound to one OpenClaw agent.
• A Canvas may contain multiple independent root branches.
• Each root or fork branch maps to its own OpenClaw session.
• An interaction node represents one complete user input → agent output run.
• Continuing from the current branch head reuses the existing session.
• Branching from a historical interaction creates a new session with context frozen at that point.
• Parent branches and their OpenClaw transcripts are never modified.
• Sessions are created lazily when the user sends the first message, avoiding empty OpenClaw sessions.
• Node positions and viewport state are persisted across reloads.

Conceptually:

Root A: I1 ── I2 ── I3 ── I4
                    └──── I5 ── I6  Fork B

Root C: I7 ── I8

Integration with OpenClaw and Nerve

The implementation is designed to reuse existing OpenClaw capabilities rather than introduce a separate agent runtime.

OpenClaw remains responsible for:

• agents and workspaces;
• sessions and transcripts;
• model and tool execution;
• streaming events;
• compaction and overflow handling;
• generated files and artifacts.

Nerve stores only Canvas-specific structure, including:

• canvases, branches, and interaction projections;
• branch-to-session mappings;
• immutable fork snapshots;
• artifact references;
• node positions and viewport state;
• send reservations and recovery metadata.

The prototype uses SQLite through Node's built-in node:sqlite. It does not modify, truncate, or rewrite OpenClaw transcripts, and it does not duplicate artifact file contents.

The frontend is primarily isolated under src/features/canvas/, with thin integration points in the application navigation and server route registration. It uses @xyflow/react for the graph UI and Dagre for initial layout.

Proposed MVP scope

• Create, rename, and archive canvases.
• Bind each Canvas to an existing OpenClaw agent.
• Create multiple independent root branches.
• Continue an existing branch using the same OpenClaw session.
• Fork from a completed historical interaction.
• Display text, Markdown, code, tool results, images, and file references.
• Show thinking, tool-use, streaming, completed, failed, and aborted states.
• Persist the graph structure and layout.
• Recover completed or in-progress interactions after a page reload.
• Keep Canvas-managed sessions out of the normal Chat session list.
• Support Nerve's local, unauthenticated single-user mode.

Non-goals for the MVP

• Replacing or removing the existing Chat view.
• Importing existing Chat sessions into a Canvas.
• Editing or deleting historical interactions.
• Rewriting OpenClaw transcripts.
• Merging branches.
• Multiplayer or real-time collaborative canvases.
• Implementing a separate summarization or compaction system.
• Copying artifact file contents into Canvas storage.
• Providing strong multi-tenant isolation over a shared Gateway.

Fork context

For a fork, the Canvas creates an immutable snapshot of the visible history through the selected interaction.

The current MVP replays that canonical snapshot when the new branch sends its first real message. OpenClaw remains responsible for compaction and context-limit handling.

A future enhancement could reuse OpenClaw compaction checkpoints and send only a checkpoint summary plus the subsequent interaction delta. The MVP does not depend on that capability.

Compatibility and security considerations

• Existing Chat and Tasks behavior should remain available and independent.
• Canvas sessions use a reserved session-key namespace and are filtered from the regular session picker.
• All Canvas API access is scoped to a stable owner identity.
• When authentication is disabled, the implementation uses a single local owner.
• Artifact access is validated against the Canvas/session mapping.
• Gateway credentials are not exposed in browser artifact URLs.
• Existing installations without Canvas data should continue to start normally.

The prototype fork also contains an optional managed-token authentication system. I propose discussing and contributing that separately unless maintainers consider stable multi-user ownership a prerequisite for Canvas.

Prototype status

The current prototype includes:

• the Canvas graph UI and automatic layout;
• root, continue, and fork workflows;
• SQLite persistence and migrations;
• a two-phase send reservation flow;
• transcript reconciliation after terminal Gateway events;
• attachment and artifact handling;
• refresh/restart recovery;
• targeted tests for layout, attachments, database state transitions, reconciliation, routes, and authentication.

The fork currently also contains unrelated or separable changes, including authentication, localization, Gateway compatibility work, and fork-maintenance documentation. I would not submit the current branch as one large pull request.

If the direction is accepted, I will prepare clean contribution branches from the latest upstream master and include only the agreed scope.

Possible contribution plan

Depending on maintainer preference, this could be submitted as:

1. Canvas domain model, SQLite persistence, and session mapping.
2. Canvas API, send lifecycle, and transcript reconciliation.
3. Canvas UI, graph layout, and navigation integration.
4. Fork context, attachments, and artifact presentation.
5. Optional authentication or localization work as separate proposals.

I am also happy to prepare a smaller vertical slice first if that would be easier to review—for example, a minimal Canvas supporting root branches and text interactions before adding fork context and artifacts.

Questions for maintainers

1. Does a visual, branching interaction workspace fit Nerve's product direction?
2. Should Canvas be a top-level view, an optional/experimental feature, or remain outside the core project?
3. Is SQLite persistence inside Nerve acceptable for this feature?
4. Would you prefer one end-to-end PR or a sequence of smaller PRs?
5. Should managed-user authentication remain a completely separate proposal?
6. Which subset would you consider the smallest useful first contribution?

I am happy to adjust the design before preparing the upstream patches.