ConvoSketchpad

让想法自由分支 · Let ideas fly free

一张画布，多条思路，熟悉的 Agent

One canvas. Many paths. The agents you know.

中文 · English ↓

ConvoSketchpad 是一张用于分支与合并 AI 对话的自托管可视化画布。你可以从任意已完成节点展开、比较和继续不同思路，再把选中的分支上下文接回现有输入框，同时直接使用已经配置好的 OpenClaw、Codex 或 OpenCode 运行环境，以及其中已有的 Agent、模型、技能、记忆、插件和工具。

Agent Runtime 中的单个 Conversation 通常以线性消息流推进。在同一条对话中穿插创意试验、图片生成、临时调研或补充提问时，这些过程都会进入后续对话，逐渐稀释主线目标；如果另开 Conversation，又需要重新整理分叉点之前的背景。

ConvoSketchpad 把这些方向铺展在同一张 Canvas 上：从任意已完成的 Interaction 带着当时信息创建新方向，独立试验，再把有价值的分支连接到任意现有 Composer。探索过程彼此清晰，汇总时也不需要手工复制历史或猜测来源顺序。

• 自媒体与内容创作者（优先推荐）：围绕选题、叙事、文案和视觉风格并行尝试多个方向，在不同分支生成和比较图片，同时继续使用运行端中已经配置的 Agent、插件、技能与工具。
• 研究、产品及其他知识工作者：让主线专注于目标任务，把临时调研、验证和补充询问放到侧支；得到答案后，再将筛选、整理过的结论带回主线，避免过程信息持续占用核心上下文。
• 已经使用 OpenClaw、Codex 或 OpenCode 的用户：保留熟悉的 Agent 或默认模型、技能、记忆、审批策略和工具，只增加可视化分支与 Canvas 组织方式，无需迁移到第二套 Agent 环境。

• 从任意一轮对话重新出发：保留到这一刻为止的创作背景，排除之后已经跑偏或无关的交流，为选题、脚本、文案或画面重新开一条干净的路线。
• 同时尝试多个创意方向：把不同标题、叙事角度、表达方式、视觉风格和图片版本铺在同一张画布上并行推进，随时放大查看和并排比较。
• 把独立探索重新汇合：将多个会话流中有价值的想法和成果接入同一个输入框，在这些内容的共同基础上继续写稿、策划或创造新内容，无需手工复制和整理多段聊天记录。
• 把创作交给更合适的 Agent：在任意输入框选择下一步使用的 Agent；切换后会带上这条路径的完整创作背景，在新的 Agent 中继续，而不必手工搬运上下文。
• 复制一轮内容再重新创作：把任意一轮输入复制成未发送的新分支，再调整 Agent、文字或素材后手动提交，适合用同一要求比较不同 Agent 或快速制作变体。
• 让每条要求准确指向素材：输入时使用 @ 点名本次上传或已经带入当前创作的图片、文件和生成结果，让 Agent 清楚哪段描述、修改意见或创作要求对应哪个素材。
• 继续使用你熟悉的 Agent：直接沿用 OpenClaw、Codex 或 OpenCode 中已经配置好的模型、技能、记忆、插件和工具，不必为了使用画布重新搭建工作流。
• 随时回到完整的创作现场：画布布局、对话过程、上传素材和生成结果都会保留下来，方便继续创作、回看不同方案，或找回某次探索中的关键成果。

• macOS 或 Linux
• Node.js 22.22.2 或更高版本
• npm 和 Git
• 至少一个已配置且可访问的 Agent 运行端：OpenClaw Gateway、已登录的本地 Codex CLI 0.146.0+，或已配置默认模型的本地 OpenCode 1.18.16+

推荐使用安装脚本：

curl -fsSL https://raw.githubusercontent.com/MrToyy/convosketchpad/main/install.sh | bash

安装脚本默认解析最新的官方稳定 Release。开发版安装需要显式指定 --branch main。完整参数请参阅安装文档。

手动安装：

git clone https://github.com/MrToyy/convosketchpad.git
cd convosketchpad
npm install
npm run setup
npm run build
npm start

npm run setup 会先探测并多选 Agent 运行端，再逐项配置连接，随后配置访问方式和可选的受管用户认证，最后从统一 Agent 目录选择 Root Composer 的默认 Agent。Codex 接入直接监督本机 codex app-server；OpenCode 接入监督本机 opencode serve 并沿用其默认模型。安装或启动本项目不会替代 Agent 运行端。

React Canvas ── HTTP/SSE ── ConvoSketchpad 服务端 ── Agent Runtime Port
                              │                       ├─ OpenClaw Adapter ⇄ Gateway
                              │                       ├─ Codex Adapter ⇄ 本地 App Server
                              │                       └─ OpenCode Adapter ⇄ 本地 HTTP/SSE Server
                              └──────── SQLite + Artifact 存储

Agent 运行端负责 Agent 执行、工具、Conversation 和原始运行记录；ConvoSketchpad 负责 Canvas 拓扑与布局、发送预留、恢复元数据、用户隔离，以及附件和 Artifact 的持久化副本。具体协议和凭据由各 Adapter 封装，Canvas 通用层不依赖 OpenClaw、Codex、OpenCode 等原生方法名。

以下运行端正在评估，不代表已经适配或承诺具体版本。评估顺序以图片设计用途的直接性为准：原生图片生成/编辑优先于明确的设计工作流和多模态输入，仅能通过外部 MCP 扩展图片能力的候选排在后面。

新运行端必须优先通过 App Server、ACP、Gateway、SDK 或稳定的机器可解析无头模式接入，不解析终端 UI 或非稳定 stdout。图片能力还必须覆盖输入媒体、生成或编辑工具调用、二进制 Artifact 发现与持久化；正式实现仍以事件完整性、审批安全、Session 恢复和 Adapter 一致性测试为准。

以下路线图不承诺具体版本或交付时间。相关能力继续遵守现有 Agent Runtime 边界：ConvoSketchpad 组织、比较和持久化 Canvas 数据，模型、工具与 Agent 执行仍由所选运行端负责。

• 分支评审与并排比较：多选同源或任意 Interaction，对照输入、输出、Artifact 和实际 Agent，并以独立 Canvas 元数据标记待评审、候选、入选、淘汰或定稿，不改写不可变历史，也不与 Runtime 权限审批混用。
• 批量并行探索：从一个历史节点一次创建多个独立 Composer，分别调整提示词、素材或 Agent，确认后再并行发送；每个方向继续使用真实 Branch 和既有发送状态机，而不是新增模型工作流执行器。
• 语义化资源引用：在现有 @ 引用上表达主体、产品、构图、风格、环境、光线、必须保留或避免模仿等用途，并由通用材料编译流程投影为运行端可理解的明确指令。
• Canvas 分区与检索：持久化 Section/Frame、便签和分区标题，按输入、输出、文件名、Agent、执行状态与评审状态查找节点，并聚焦或高亮匹配路径；组织元素默认不进入 Agent 上下文。
• Storyboard / Collection：把不同分支中的图片、视频和文本 Artifact 按顺序编排，补充镜号、说明和时长，并导出联系表或清单；保持为 Canvas 组织能力，不内置完整视频剪辑器。
• 用户私有素材架：由用户显式把已持久化的附件或 Artifact 提升为可跨 Canvas 复用的角色、产品、风格或环境素材，继续执行所有者隔离，不扫描 Agent Runtime 工作区。
• Canvas 模板：保存布局、Branch 骨架、未发送 Composer、引用角色占位符和说明；默认不包含 Conversation Handle、历史执行、历史对话正文或私有附件。
• 发送前检查：发送前汇总目标 Agent、Conversation 继续或 Replay、资源槽位、Merge 来源、缺失文件和 Runtime 能力；只有运行端能够可靠提供时才显示费用或用量估算。
• 图片区域批注：在图片 Artifact 上圈选区域并添加修改或保留说明，生成与原图关联的不可变批注派生资源，再作为普通附件交给 Agent。
• 创意工作流后端：支持连接 ComfyUI 等本地或云端创意执行服务，让现有 Agent 调用可复现的图片、视频、音频和 3D 工作流，并把结果作为 Artifact 带回 Canvas。
• 设计工具与交付平台：逐步连接 Figma、Canva、Adobe 等设计环境，在保持各平台职责边界的前提下交换设计上下文、素材和最终产物。
• Windows 支持：在上述产品能力之后，提供与 macOS、Linux 一致的安装、配置、服务管理和运行体验。

npm install
npm run setup
npm run dev

npm run dev 会同时启动 Vite 客户端和监听模式服务端，只需打开终端中标记为 Open in browser 的地址：

• HOST 和 PORT 在开发、生产中都表示浏览器访问的 ConvoSketchpad 入口，默认是 127.0.0.1:3080。
• /api 和 /health 会由 Vite 代理到内部服务端；浏览器不直接连接任何 Agent Runtime。
• 内部服务端只绑定 loopback，端口由开发脚本自动选择，无需配置。
• React 客户端支持 HMR；服务端代码变更后由 tsx watch 自动重启。

自定义开发地址：

PORT=4000 npm run dev

此时浏览器入口是 http://127.0.0.1:4000。需要从 LAN 或 Tailscale 访问时，请重新运行 setup 选择对应访问模式，让 HOST、ALLOWED_ORIGINS 和认证策略保持一致。修改环境变量后需要重新启动开发进程。

复制 .env.example 或运行 npm run setup 生成 .env。以下仅列出最常用的配置：

Codex 与 OpenCode 固定共用 ~/.convosketchpad/workspace，setup 按需创建；该路径不提供环境变量覆盖。

对外提供服务前，请启用受管用户认证，并通过反向代理或 Tailscale Serve 提供 HTTPS；ConvoSketchpad 自身只监听 HTTP。请仔细配置精确 Origin、可信代理与网络访问策略。完整说明请参阅配置文档、部署文档和安全文档。

产品与架构：

• 产品目标与原则
• 架构、Session 与运行时数据流
• Canvas 功能索引
• 分支合并设计

安装与运维：

• 文档总索引
• 安装
• 部署
• 配置
• 安全
• 故障排查
• 更新
• HTTP API

维护者参考：

• Canvas 功能与代码地图
• 认证功能与代码地图
• Git 工作流

本项目采用 MIT License。第三方来源与版权说明见 NOTICE。

返回顶部 ↑ · 跳转到 English ↓

ConvoSketchpad is a self-hosted visual canvas for branching and merging AI conversations. Fork, compare, and continue different paths from any completed node, then connect selected branch context back into an existing composer while reusing your OpenClaw, Codex, or OpenCode environment and its Agents, default model, skills, memory, plugins, and tools.

An Agent Runtime Conversation usually advances as a linear message stream. When creative experiments, image generation, quick research, and side questions all happen in one chat, they become part of everything that follows and gradually dilute the primary objective. Starting a separate Conversation avoids that mixture, but requires reconstructing the information available at the fork point.

ConvoSketchpad lays those directions out on one Canvas. Fork any completed Interaction with the information available at that point, experiment independently, then connect useful branches to any existing composer. Each exploration stays clear, and combining results does not require manually copying history or guessing source order.

• Social media and content creators (recommended first): explore topics, narratives, copy, and visual styles in parallel; generate and compare images across branches; and keep using the Agents, plugins, skills, and tools already configured in the selected Runtime.
• Researchers, product teams, and other knowledge workers: keep the primary branch centered on the target task, move temporary research, validation, and side questions into branches, then summarize selected findings back into the main line.
• Existing OpenClaw, Codex, or OpenCode users: keep familiar Agents or default models, skills, memory, approval policies, and tools while adding visual branching and Canvas organization instead of migrating to a second Agent environment.

• Restart from any point in a conversation: keep the creative context available at that moment while leaving later detours behind, giving a topic, script, draft, or visual direction a clean path forward.
• Explore several creative directions at once: develop alternative headlines, narratives, tones, visual styles, and image versions side by side on one Canvas, then zoom in and compare them whenever you need.
• Bring separate explorations back together: connect the strongest ideas and results from several conversation paths into one input, then write, plan, or create something new from their combined foundation without manually copying chat history.
• Hand work to the best Agent for the next step: choose an Agent in any composer; when you switch, the complete context of that path is replayed into a new Agent Conversation without manual copying.
• Copy a turn and reshape it before sending: duplicate any input into an unsent branch, then change its Agent, wording, or assets before submitting—useful for comparing Agents or producing quick variations.
• Make every instruction point to the right asset: use @ to name an image, file, or result uploaded in or already brought into the current creative path exactly where you discuss it, so the Agent knows which asset each description, revision, or creative request refers to.
• Keep working with the Agents you already know: reuse the models, skills, memory, plugins, and tools configured in OpenClaw, Codex, or OpenCode instead of rebuilding your workflow for the Canvas.
• Return to the complete creative workspace at any time: Canvas layout, conversations, source material, and generated results stay together, making it easy to continue a project, revisit alternatives, or recover a valuable result from an earlier exploration.

• macOS or Linux
• Node.js 22.22.2 or newer
• npm and Git
• At least one configured and reachable Agent Runtime: OpenClaw Gateway, a logged-in local Codex CLI 0.146.0+, or local OpenCode 1.18.16+ with a default model configured

The install script is recommended:

curl -fsSL https://raw.githubusercontent.com/MrToyy/convosketchpad/main/install.sh | bash

By default, the installer resolves the latest official stable Release. Use --branch main explicitly for a development install. See the installation guide for all options.

Manual install:

git clone https://github.com/MrToyy/convosketchpad.git
cd convosketchpad
npm install
npm run setup
npm run build
npm start

npm run setup first detects and lets you select Agent Runtimes, configures each connection, then configures access mode and optional managed-user authentication. Finally, it chooses the default Agent for Root composers from the unified catalog. Codex integration supervises the local codex app-server; OpenCode integration supervises local opencode serve and inherits its default model.

React Canvas ── HTTP/SSE ── ConvoSketchpad server ── Agent Runtime Port
                              │                       ├─ OpenClaw Adapter ⇄ Gateway
                              │                       ├─ Codex Adapter ⇄ local App Server
                              │                       └─ OpenCode Adapter ⇄ local HTTP/SSE Server
                              └──────── SQLite + Artifact store

Agent Runtimes own Agent execution, tools, Conversations, and authoritative run records. ConvoSketchpad owns Canvas topology and layout, send reservations, recovery metadata, user isolation, and durable copies of attachments and Artifacts. Each Adapter contains its native protocol and credentials; shared Canvas code does not depend on OpenClaw, Codex, OpenCode, or other native method names.

The following Runtimes are being evaluated, not completed integrations or release commitments. Evaluation order reflects how directly they fit image-design work: native image generation and editing rank ahead of explicit design workflows and multimodal input, while candidates that depend entirely on external MCP tools rank lower.

New Runtimes must prefer App Server, ACP, Gateway, SDK, or a stable machine-readable headless mode instead of parsing terminal UI or unstable stdout. Image support must also cover media input, generation or editing tool calls, and binary-Artifact discovery and persistence; implementation still depends on event completeness, approval safety, Session recovery, and Adapter conformance tests.

This roadmap does not commit to a specific version or delivery date. Roadmap work must preserve the existing Agent Runtime boundary: ConvoSketchpad organizes, compares, and persists Canvas data, while the selected Runtime continues to own models, tools, and Agent execution.

• Branch review and side-by-side comparison: select sibling or arbitrary Interactions, compare their inputs, outputs, Artifacts, and actual Agents, and store review, candidate, selected, rejected, or final states as separate Canvas metadata without rewriting immutable history or conflating creative review with Runtime approvals.
• Batch parallel exploration: create several independent composers from one historical node, adjust each prompt, asset set, or Agent, then confirm before sending them in parallel. Every direction remains a real Branch using the existing send state machine rather than a new model-workflow executor.
• Semantic resource references: extend existing @ references with roles such as subject, product, composition, style, environment, lighting, must-preserve, or avoid-imitation, then project them through the shared material compiler into explicit instructions a Runtime can understand.
• Canvas sections and search: persist sections/frames, notes, and section titles; find nodes by input, output, filename, Agent, execution state, or review state; and focus or highlight matching paths. Organizational elements stay out of Agent context unless explicitly referenced.
• Storyboard / Collection: order image, video, and text Artifacts from different branches, add shot numbers, notes, and durations, and export a contact sheet or manifest. This remains Canvas organization rather than a full video editor.
• Private asset shelf: let users explicitly promote persisted attachments or Artifacts into reusable character, product, style, or environment assets across Canvases while preserving owner isolation and never scanning an Agent Runtime workspace.
• Canvas templates: save layouts, Branch scaffolds, unsent composers, resource-role placeholders, and guidance while excluding Conversation Handles, run history, historical conversation content, and private attachments by default.
• Preflight review: summarize the target Agent, Conversation continuation or Replay, material slots, Merge sources, missing files, and Runtime capabilities before sending. Show cost or usage estimates only when the Runtime can provide them reliably.
• Image-region annotations: mark regions of an image Artifact with change or preserve notes, create an immutable annotated derivative linked to the original, and send it to the Agent as a normal attachment.
• Creative workflow backends: connect local or cloud creative execution services such as ComfyUI, let existing Agents invoke reproducible image, video, audio, and 3D workflows, and return their results to the Canvas as Artifacts.
• Design tools and delivery platforms: progressively connect design environments such as Figma, Canva, and Adobe to exchange design context, assets, and final deliverables while preserving each platform's responsibility boundary.
• Windows support: after the product capabilities above, provide installation, setup, service management, and runtime behavior consistent with macOS and Linux.

npm install
npm run setup
npm run dev

npm run dev starts the Vite client and watch-mode server together. Open only the URL labeled Open in browser in the terminal:

• HOST and PORT identify the browser-facing ConvoSketchpad entrypoint in both development and production; the default is 127.0.0.1:3080.
• Vite proxies /api and /health to the internal server; the browser never connects directly to any Agent Runtime.
• The internal server listens on loopback at an automatically selected port and requires no user configuration.
• The React client supports HMR; tsx watch restarts the server after server-side code changes.

To customize the development address:

PORT=4000 npm run dev

The browser entrypoint is then http://127.0.0.1:4000. For LAN or Tailscale access, rerun setup and select the matching access mode so HOST, ALLOWED_ORIGINS, and authentication policy stay aligned. Restart the development process after changing environment variables.

Copy .env.example or run npm run setup to generate .env. The most commonly used settings are:

Codex and OpenCode use the fixed shared workspace ~/.convosketchpad/workspace, created by setup as needed; there is no environment-variable override.

Before exposing the service to a network, enable managed-user authentication and terminate HTTPS at a reverse proxy or Tailscale Serve; ConvoSketchpad itself listens on HTTP only. Configure exact origins, trusted proxies, and network policy carefully. See Configuration, Deployment, and Security.

Product and architecture:

• Product goals and principles
• Architecture, Sessions, and runtime data flow
• Canvas feature index
• Branch merging design

Installation and operations:

• Documentation index
• Installation
• Deployment
• Configuration
• Security
• Troubleshooting
• Updating
• HTTP API

Maintainer references:

• Canvas feature and code map
• Authentication feature and code map
• Git workflow

This project is available under the MIT License. See NOTICE for third-party provenance and copyright notices.

Back to top ↑ · 中文 ↑