DEV Community: Astrodevil

Useful Agent memory for Your Openclaw and Hermes Agent🔥

Astrodevil — Mon, 29 Jun 2026 13:25:45 +0000

Astrodevil

Jun 17

Building a Hermes Memory Plugin for a Voice-Powered Conference Agent with Weaviate Engram🧠

#ai #programming #opensource #python

13 min read

Building a Hermes Memory Plugin for a Voice-Powered Conference Agent with Weaviate Engram🧠

Astrodevil — Wed, 17 Jun 2026 16:44:00 +0000

Introduction

Recently, I have been attending a lot of conferences where different booths showcase different projects. One thing I kept noticing was how often visitors approached a booth only to find nobody there to answer their questions.

After seeing this happen several times, I started wondering: what if every booth had an AI agent capable of answering visitor questions and keeping track of interactions for the booth owners?

So I decided to build one using Hermes.

But I quickly ran into a problem: memory.

Hermes’ default memory system was designed for smaller, single user interactions. I needed something that could retain information across many different visitors and conversations.

There are multiple third-party memory plugins for Hermes, but when I came across Engram, Weaviate’s memory solution for AI agents. It looked like exactly what I needed, giving me the opportunity to both enhance my agent’s memory and put Engram to the test.

In this article, I will walk you through how I built a voice-enabled conference agent on top of Hermes with voice support, and how I extended its memory by building a memory plugin using Engram.

The Conference Agent

So here’s what I set out to build.

The conference agent would sit at a booth on a laptop while visitors walk up and interact with it. The agent would answer questions about the project, try to get to know the visitors, and keep track of conversations. Later, the booth owners could come back and ask the agent questions about what particular visitors were interested in.

The conference agent needs a couple of things:

An AI agent
A User Interface that lets attendees speak and listen to the agent
Long term memory
An interface for booth owners to interact with the agent

For the AI agent, Hermes already had me covered. For the attendee interface, the Hermes CLI was perfect since it already has real time voice mode.

Then for the booth owners, the Hermes messaging gateway makes it possible to communicate with the agent over Telegram and retrieve insights from conversations.

So Hermes already had almost everything covered except for one thing: memory.

Hermes’ built in memory system was designed around single user interactions. It stores memory in two markdown files: Memory.md for general facts and User.md for user specific information.

The problem is that this memory is very limited. Memory.md can only hold about 2,200 characters (roughly 800 tokens), while User.md holds around 1,375 characters (about 500 tokens).

That simply isn’t enough for a conference booth interacting with potentially hundreds of visitors.

That’s where Engram comes in.

Thanks to Hermes plugin system, I could extend Hermes built in memory and add Engram as a custom memory provider.

Engram: Weaviate’s Memory Solution

Let’s briefly explore Engram.

Engram is Weaviate’s managed memory and context service, purpose-built to help AI agents orchestrate workflows, learn from experience, and anchor decisions to trusted knowledge.

When a user interacts with an agent, Engram extracts useful information from the conversation and stores it as memory. These extracted memories are then committed to Engram for later use.

One thing that makes Engram stand out is that it doesn’t just keep adding new memory blindly. It can also retrieve existing memories and update them with new information. This helps avoid duplicates and keeps memory more accurate over time.

That’s one of the main reasons Engram was a good fit for my project. I didn’t want a system that just keeps piling up redundant information.

Once memories are stored, they can be searched later and used by an AI agent or even in other pipelines like RAG systems.

Using Engram

Engram is generally available to everyone. To get started, head over to Weaviate Console and sign up for the free tier. Once you're in, navigate to the Engram dashboard and create an API key.

Then, install the Python SDK:

pip install weaviate-engram

Then create a client:

from engram import EngramClient

client = EngramClient(api_key="your-api-key")

There are two main ways to add memory to Engram: using strings or conversations.

With strings, you can pass a single piece of text and Engram will extract useful information from it:

run = client.memories.add("Alice prefers async Python and avoids Java.", 
user_id="hermes"
)

Then for a conversation with an AI assistant:

run = client.memories.add(
   [
       {"role": "user", "content": "What's the best way to handle retries?"},
       {"role": "assistant", "content": "Exponential backoff with jitter is the standard approach."},
       {"role": "user", "content": "Got it — I'll use that in my HTTP client."},
   ],
   user_id="hermes",
)

The user_id is used to scope memory to a specific user, so you can easily separate and retrieve memories per person.

You can then search stored memories like this:

results = client.memories.search(query="What does Alice think about Python?", user_id="hermes")
for memory in results: print(memory.content)

This lets you retrieve only the most relevant memories for a given user.

Now that we understand how Engram works, let’s build the plugin.

Building the Memory Plugin

In Hermes, every memory plugin inherits from the MemoryProvider class. This is an abstract base class, which means we need to implement the methods we want to use.

A memory plugin consists of two main files:

__init__.py: This contains the actual plugin implementation
plugin.yaml: This defines the plugin metadata

Here’s how we are going to implement the plugin:

After each session with a user, the plugin will store the full conversation in Engram. Engram will then extract the relevant memories from it automatically.

We’ll also expose a tool that allows the agent to search Engram and retrieve relevant memories when needed.

Let’s start implementing it. Below is the basic plugin structure without the logic implemented yet.

This code will live in __init__.py.

import json
import os
from typing import Any, Dict, List

from agent.memory_provider import MemoryProvider
from engram import EngramClient

class Engram(MemoryProvider):

   @property
   def name(self) -> str:
       return "engram"

   def is_available(self) -> bool:
       return bool(os.environ.get("ENGRAM_API_KEY"))

   def initialize(self, session_id: str, **kwargs) -> None:
       pass


   def get_config_schema(self):
       pass

   def on_memory_write(
       self,
       action: str,
       target: str,
       content: str,
   ) -> None:
       pass

   def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
       pass

   def get_tool_schemas(self) -> List[Dict[str, Any]]:
       pass

   def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
       pass

Here are methods that will be implemented:

name: Defines the name of the plugin.
is_available: Checks whether the plugin can be used. This should be a lightweight check (for example, verifying an environment variable), not a network call.
initialize: Called when the plugin is first loaded.
get_config_schema: Defines configuration options for the plugin.
on_memory_write: A hook that runs whenever Hermes updates its Markdown memory.
on_session_end: Called at the end of a user session. This is where we’ll send the full conversation to Engram.
get_tool_schemas: Defines tools exposed by the memory plugin.
handle_tool_call: Handles any tool calls made by the agent to the memory plugin.

Implementing the Initialize and Config Methods

Let’s start by implementing the initialize and get_config_schema methods.

  def initialize(self, session_id: str, **kwargs) -> None:
       self._client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
       self._user_id = session_id

This method is called when the plugin is loaded. Here we initialize the Engram client using the API key stored in the environment variables.

We also store the session_id. This will be used as the user_id when storing and searching memories.

Next is the configuration schema:

   def get_config_schema(self):
       return [
           {
               "key": "api_key",
               "description": "Engram API key",
               "secret": True,
               "required": True,
               "env_var": "ENGRAM_API_KEY",
               "url": "https://console.weaviate.cloud/engram",
           }
       ]

In get_config_schema, we define the configuration needed by the plugin. In this case, the plugin requires an ENGRAM_API_KEY.

Implementing the Hooks

The on_memory_write and on_session_end methods are hooks connected to Hermes’ event system.

Whenever Hermes writes memory to its Markdown files, it triggers the on_memory_write hook. In this method, we send that memory directly to Engram.

   def on_memory_write(
       self,
       action: str,
       target: str,
       content: str,
   ) -> None:
       self._client.memories.add(content, user_id=self._user_id)

One important thing to note is that Hermes still uses its built in Markdown memory system alongside an external provider. We can use this to keep Engram continuously updated with the memories Hermes writes locally.

The on_session_end hook is triggered when a conversation session ends. Here, we store the entire conversation between the user and the agent.

   def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
       parsed_message = []
       for message in messages:
           if message['role'] == 'user':
               parsed_message.append({'role': 'user', 'content': message['content'] })

           if message['role'] == 'assistant':
               parsed_message.append({'role': 'assistant', 'content': message['content'] })

       self._client.memories.add(parsed_message, user_id=self._user_id)

Both hooks use the session ID as the user_id. I decided to do it this way so that every visitor interacting with the booth agent gets their own dedicated memory scope. This keeps memories grouped per visitor instead of mixing conversations together.

Implementing the Tools

For the agent to search memories stored in Engram, we first need to define a tool schema.

SEARCH_SCHEMA = {
    "name": "engram_search",
    "description": (
        "Search memories in engram"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "What to search for in engram's memory.",
            },
            "user_id": {
                "type": "string",
                "description": "The user ID to search memories for.",
            },
        },
        "required": ["query", "user_id"],
    },
}

Next, we expose the tool schema through get_tool_schemas:

   def get_tool_schemas(self) -> List[Dict[str, Any]]:
       return [SEARCH_SCHEMA]

Finally, we implement handle_tool_call, which runs whenever the agent calls the tool.

    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:

        if tool_name == "engram_search":
            query = args["query"]
            user_id = args["user_id"]
            results = self._client.memories.search(query=query, user_id=user_id)
            text = []
            for result in results:
                text.append(result.content)

            return json.dumps({"result": "\n".join(text)})

        return json.dumps({"error": f"Unknown tool {tool_name}"})

Putting It All Together

After implementing the Engram memory provider, we can register it as a memory plugin at the bottom of the file:

def register(ctx) -> None:
   """Called by the memory plugin discovery system."""
   ctx.register_memory_provider(Engram())

This allows Hermes to discover and load our plugin automatically.

Here’s the complete `init.py` file:

import json
from typing import Any, Dict, List

from agent.memory_provider import MemoryProvider
from engram import EngramClient

import os

SEARCH_SCHEMA = {
    "name": "engram_search",
    "description": (
        "Search memories in engram"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "What to search for in engram's memory.",
            },
            "user_id": {
                "type": "string",
                "description": "The user ID to search memories for.",
            },
        },
        "required": ["query", "user_id"],
    },
}

class Engram(MemoryProvider):

    @property
    def name(self) -> str:
        return "engram"

    def is_available(self) -> bool:
        return bool(os.environ.get("ENGRAM_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        self._client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
        self._user_id = session_id


    def get_config_schema(self):
        return [
            {
                "key": "api_key",
                "description": "Engram API key",
                "secret": True,
                "required": True,
                "env_var": "ENGRAM_API_KEY",
                "url": "https://console.weaviate.cloud/engram",
            }
        ]

    def on_memory_write(
        self,
        action: str,
        target: str,
        content: str,
    ) -> None:
        self._client.memories.add(content, user_id=self._user_id)

    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
        parsed_message = []
        for message in messages:
            if message['role'] == 'user':
                parsed_message.append({'role': 'user', 'content': message['content'] })

            if message['role'] == 'assistant':
                parsed_message.append({'role': 'assistant', 'content': message['content'] })

        self._client.memories.add(parsed_message, user_id=self._user_id)

    def get_tool_schemas(self) -> List[Dict[str, Any]]:
        return [SEARCH_SCHEMA]

    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:

        if tool_name == "engram_search":
            query = args["query"]
            user_id = args["user_id"]
            results = self._client.memories.search(query=query, user_id=user_id)
            text = []
            for result in results:
                text.append(result.content)

            return json.dumps({"result": "\n".join(text)})

        return json.dumps({"error": f"Unknown tool {tool_name}"})


def register(ctx) -> None:
    """Called by the memory plugin discovery system."""
    ctx.register_memory_provider(Engram())

Next, we can create the plugin.yaml file. This file stores the plugin metadata and defines the hooks used by the plugin.

name: engram
version: 1.0.0
description: "Engram is a fully managed memory service by Weaviate. It lets you add persistent, personalized memory to AI assistants and agents."
pip_dependencies:
 - weaviate-engram
hooks:
 - on_session_end
 - on_memory_write

Setting Up the Engram Memory Plugin

Now that the memory plugin is implemented, let’s set it up in Hermes. First, place both the __init__.py and plugin.yaml files inside a folder called engram.

Your directory should look like this:

engram/
├── __init__.py
└── plugin.yaml

Next, move the engram directory into the Hermes plugins directory:

mv engram ~/.hermes/plugins/

Hermes automatically discovers plugins from this location.

Now enable the plugin by running:

hermes plugins enable engram

Next, run:

hermes memory

This lets you confirm that engram now appears as one of the available memory providers.

After that, run the setup command:

hermes memory setup

You’ll be prompted with a list of available memory providers. Select engram and provide your Engram API key when asked.

Once setup is complete, run:

hermes memory

Now, it will show that Engram is now configured as an active memory provider.

Engram in Action

Now that the Engram plugin is working, let’s test it out.

Before launching Hermes, we first need to modify the SOUL.md file located at ~/.hermes/SOUL.md. This file defines Hermes’ personality and behavior.

For this demo, I want Hermes to behave like an AI agent stationed at a Weaviate booth, showcasing Engram at a conference. I also want it to treat every conversation as a completely new interaction.

Here’s the modified SOUL.md file:


# Hermes Agent Persona

You are Hermes, an AI agent representing Weaviate at a conference booth. Your role is to help attendees learn about Weaviate and answer questions about its products, especially Engram, Weaviate’s memory product.

Treat every conversation as if you are speaking to a new attendee for the first time. Be warm, friendly, and approachable.
Start by introducing yourself, asking for the person’s name, and asking what they would like to know about Engram or Weaviate.

Your goal is to clearly explain concepts, answer questions accurately, and help people understand how Engram can be used in real world AI applications. Keep your responses conversational, engaging, and easy to understand regardless of the attendee’s technical background.

With that in place, we can launch the Hermes CLI and start chatting with the agent.

I took on the persona of “Paul” and had a conversation with Hermes. After the interaction, I closed the session using Ctrl + C.

When I opened the Engram dashboard, I could see that memories from the conversation had been successfully stored.

I could also browse memories from other sessions and confirm that each visitor’s interactions were being stored separately.

This means Hermes can now retain information across multiple users and conversations instead of relying only on short term Markdown memory.

Making the Agent Voice-Enabled

With Engram memory now integrated into Hermes, the conference agent is almost ready. The next thing we need to set up is voice support.

There are different approaches to handling voice in Hermes. You could use cloud models for both speech to text and text to speech, or you could run everything locally.

I decided to go with local models. Here was my setup:

First, I installed the required Python dependencies:

pip install "hermes-agent[voice]"
pip install -U neutts[all]
pip install sounddevice numpy

NeuTTS provides local text to speech capabilities.

Next, I installed the system dependencies required for audio processing:

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng   # required for NeuTTS

Once everything is installed, Hermes can be launched in the terminal and voice mode enabled with:

 /voice on

To enable text to speech:

 /voice tts

Messaging Support for the Conference Agent

The last feature to add is the messaging gateway, which allows booth owners to message the agent and retrieve insights from ongoing conversations with attendees.

This makes it possible to ask questions, monitor interactions, and extract information even when they are not physically at the booth, without interrupting attendees interacting with the agent.

Hermes supports multiple messaging platforms. In this case, I used telegram as the primary interface for interacting with the agent.

Follow the official Hermes guide to set up Telegram as your messaging platform, or choose another supported option. Once configured, enable the gateway and you can start interacting with the agent remotely.

The image above shows how I used the engram_search tool to retrieve memory for a specific user using their session ID. Since session IDs are only accessible to authorized admins via the Engram dashboard, this keeps the data private while still allowing useful insights for booth owners.

Quick Recap

With the conference agent is completed let’s do a recap on what we have built:

A conference agent on top of Hermes that attendees can interact with
Extended memory through a custom memory plugin powered by Engram
Voice support via the Hermes CLI
A messaging gateway that enables booth owners to interact with the agent and retrieve insights

While this agentic setup was built with conference booths in mind, we could take the memory plugin we built and apply it to the following use cases:

A personal assistant with extended long term memory across sessions
A customer support agent that retains conversation history across users and tickets
Educational agents that remember students, their progress, and learning patterns

You can get the full code in this article here: Hermes_Engram_Plugin

Conclusion

What started as a simple idea for a better conference booth experience turned into a full AI agent with persistent memory, real time interaction, and voice capabilities.

With Hermes handling conversations, Engram managing long term memory, and voice support making interactions feel natural, the agent is no longer just answering questions, it’s actively remembering people, conversations, and context across sessions.

While this solution was built with a conference setting in mind, the memory plugin we developed can be used far beyond that. From personal AI assistants to more complex multi user systems, the same approach can help any agent retain meaningful context over time and deliver more useful, personalized interactions.

Top Alternatives to Lovable in 2026

Astrodevil — Wed, 10 Jun 2026 18:43:32 +0000

Lovable is great at generating applications from prompts. It is fast, intuitive, and especially useful when you want to move from an idea to a working prototype quickly. It works well for landing pages, internal tools, MVPs, and early product experiments where speed matters more than having a robust system.

But when you move beyond prototyping or non-technical team members start creating pages and interfaces themselves, it starts to feel limiting. As projects grow, bringing each generated output into the existing codebase becomes harder, slowing the whole process with endless code reviews and subtle integration quirks. What works well for quickly validating an idea can require more effort once it needs to fit into a larger product.

If you’ve found this article, you’ve probably already hit that point and started looking for something that can scale beyond the first prototype. That is exactly what this guide is for: helping you compare five Lovable alternatives and understand where each one fits best.

TL;DR: Lovable Alternatives Comparison

Tool	Core Difference	Best For	Target User	Runs In	Output Requires Deployment
Puck AI	Builds UI at runtime using your existing React components instead of generating new code	Building production UI directly inside your product or workflow	Developers, teams, and non technical users	Your application or your infrastructure	No
Bolt.new	Builds, runs, and deploys full stack apps entirely in the browser	Quickly prototyping and publishing apps	Developers and founders	Browser and Bolt.new cloud environment	Yes
Replit AI	Cloud development workspace with coding, execution, and deployment in one place	Building and iterating on apps inside an online development workspace	Developers and teams	Browser and Replit cloud workspace	Yes
v0 by Vercel	Creates React and Next.js UI code from prompts	Implementing pages and frontend interfaces quickly	Frontend developers	Browser and Vercel ecosystem	Yes
Cursor	AI powered code editor with deep repository awareness	Writing and shipping features inside an existing codebase	Developers	Your machine	Yes

1. Puck AI

Puck AI is a platform for building AI-powered page creation experiences inside your own product. It generates interfaces using a predefined set of components, allowing backend systems and non-technical users to create UI without generating new code.

To use it, you connect Puck AI to the UI components already available in your application. It then generates pages using only those approved components, either on its own as part of an automated AI-driven workflow or alongside the Puck editor for a drag-and-drop editing experience. Since the output is assembled from your existing components, every generated page is safe and stays consistent with your design system and application code.

This is the main difference compared with Lovable. Lovable generates code from prompts. Puck AI generates UI at runtime using components you have already implemented and tested, so there is no generated code to review, rewrite, or deploy separately.

Pros

No deployments

One of the biggest bottlenecks with Lovable is that it generates raw code, which means every output needs to, at the very least, be deployed before it can be used. Puck AI avoids that altogether by generating pages at runtime from your existing React components. There’s 0 code generation. That means each output can be used in your product immediately without waiting for a deployment cycle, opening the door to use cases such as live content updates and personalized experiences in real time.

Safe by design

Lovable can work well when developers are the ones using it, but adding it into workflows for non-technical users is much harder. Because Puck AI works within the execution flows and components you already implemented, the generated UI always stays within the boundaries of your application. This makes it easier for you to safely expose page generation to end users, internal teams, or automated systems without the risk of AI introducing unexpected code or breaking the app.

Embeds in your system

Puck AI is designed to run inside your product, not beside it as a separate platform. You can integrate it into your front end, back end, CMS, internal tools, customer flows, or publishing systems while keeping control over the full page generation flow: how pages are created, where they live, how they are stored, and how they move through your infrastructure.

This means you do not need to migrate your content or workflows into a separate system. Puck AI adapts to your UI generation requirements now and evolves with them over time without locking you in.

Guardrailed generation

Lovable struggles to create UI consistently as a project grows. You might start with something that looks right, but after enough iterations, the code can become messy, inconsistent, and sometimes completely disconnected from the rest of your product. To mitigate this, you usually end up adding plain text rules trying to explain what the AI should or should not do.

Puck AI avoids this by generating pages from the components, rules, and context you define. You decide which React components it can use, how they can be configured, how they should be assembled, and how external data or variables should shape the result for each page. This keeps generation predictable and aligned with your product requirements, instead of producing one-off interfaces that need to be cleaned up later. In other words, you tell the AI what it

Cons

Not a development tool

Puck AI does not generate full applications or new components from scratch. Instead, it generates UI using the React components you have built. If you need to generate APIs, backend logic, database schemas, or complete application code, you will need to use it alongside other development tools. This makes it a better fit for UI generation inside an existing product than for full-stack development.

Requires a React-based UI layer

At the time of writing, Puck AI works with components that already exist in your application and uses React to render them. This means your UI needs to be implemented as React components. If your front end uses another framework, adopting Puck AI may require onboarding your team to React and adding extra development time before your UI generator is ready for end users.

That said, the generation layer itself can work outside React, and there is already an issue on the Puck repo tracking multi-framework support.

Integration overhead

Because Puck AI runs inside your own application, it needs to be integrated into your stack and configured before it can be used. This gives you more control over how UI is generated and where it fits into your system, but it also requires upfront development effort to connect components, define the experience, and deploy it as part of your product.

When to use Puck AI

Use Puck AI when you want people to create pages inside your product while keeping the result consistent with your design system and application. It works especially well when pages need to be production-ready from the start, without requiring engineering work every time something new is created.

This makes it a good fit for CMS experiences, publishing workflows, white-label products, and no-code interfaces where non-technical users need to generate landing pages or content from a predefined set of components.

Puck AI is also useful when page creation needs to happen programmatically as part of a larger workflow. Using the headless generation APIs, pages can be generated from backend systems, user actions, or automated publishing flows while still following the component rules and design constraints defined in your application.

That said, if your goal is to generate entirely new applications or backend logic from prompts, a full-stack development tool will be a better fit.

2. Bolt.new

Bolt.new is an AI-powered IDE from StackBlitz that lets you build and deploy full-stack applications directly in the browser using natural-language prompts. It includes a browser-based workspace where you can generate frontend and backend code, run it instantly, and iterate without setting up a local development environment.

That is the main difference compared with Lovable. While Lovable is primarily focused on generating application interfaces from prompts, Bolt gives you a complete workspace to build, test, and ship an application in one place.

Pros

Requires zero configuration

Bolt allows you to move from prompt to a running full-stack application without switching tools. You can generate frontend and backend code, execute it immediately, and iterate within the same environment. This reduces setup time and simplifies the development workflow, especially during early-stage prototyping.

In-browser execution environment

The platform runs entirely in the browser, using WebContainers to simulate a local development environment. You can install dependencies, run servers, and test applications without having to configure or install anything on your machine. This makes it easier to start building immediately, regardless of your system setup.

Integrated deployment capabilities

Bolt includes built-in deployment options, allowing you to push applications live directly from their platform. This removes the need to configure separate hosting or CI/CD pipelines for basic use cases, making it easy to validate ideas quickly with a working deployment.

Supports multiple JavaScript frameworks

Bolt makes it easy to work across frontend frameworks in the JavaScript ecosystem. This is useful when experimenting with different approaches, rebuilding parts of an application, or migrating from one frontend framework to another without starting from scratch.

Cons

Output requires review

Applications built with Bolt still need to be reviewed, tested, and validated before production use. You are responsible for ensuring correctness, security, and performance, as well as making sure the generated output aligns with your existing codebase, design system, and product requirements. Depending on the stage of the project, this can add additional work before the application is ready to ship.

Limited architectural control

Since the application structure is generated automatically, you may have less control over how the system is organized. Modifying or scaling the architecture can require manual refactoring after generation. This can become a constraint for larger or long-term projects.

Dependency on a third-party hosted environment

Bolt operates entirely as a third-party hosted platform, which means your development workflow depends on its environment and infrastructure. You do not have the same level of control as a local or self-managed setup. This can be limiting if you need custom configurations or deeper system integration.

Harder to adopt in established teams

Since Bolt runs within its own hosted environment, it can be harder to fit into organizations with established infrastructure, internal tooling, or strict deployment workflows. It works well for fast individual builds and prototypes, but can be less practical for teams working across larger or more complex systems.

When to use Bolt

Use Bolt when you need to go from an idea to a working full-stack application without setting up a local development environment or configuring infrastructure.

It is also a strong fit when you want to prototype across different stacks quickly. Since the environment supports installing packages and running servers, you can experiment with frameworks, test integrations, and deploy a working version without setting up build pipelines or hosting manually.

Just keep in mind that, if your use case involves long-term scalability, custom architecture, or deep system integration, you will likely need to keep refining the codebase outside the generated environment. Depending on your needs, that extra work may make it more involved than some of the other solutions on this list.

3. Replit AI

Replit AI is built for continuous development rather than one-time generation. Similar to Bolt, it gives you a browser-based environment where you can build and ship applications without local setup.

The difference is that Replit is designed more as a persistent collaborative workspace for ongoing development, where you can iteratively write, refine, test, and maintain an application over time with AI assistance. While Lovable is centered around creating applications from prompts, Replit is better suited to longer-running development workflows inside the same environment.

Pros

Unified full-stack development environment

Replit AI provides a complete development workflow within a single browser-based IDE. You can write backend logic, build frontend interfaces, manage databases, and deploy applications without switching tools. This reduces the need for external setup and allows you to move from idea to a working system in one place.

Autonomous AI agent for development tasks

The platform includes an AI agent that can interpret natural language instructions and generate entire application components, including APIs, database schemas, and integration logic. It can also assist with debugging, code improvements, and iterative feature development. This enables you to offload repetitive tasks while maintaining control over the codebase.

Multi-language and runtime support

Replit supports over 50 programming languages and provides an execution environment that works consistently across devices. You can run servers, install dependencies, and test applications directly in the browser. This flexibility allows you to experiment with different stacks without configuring local environments.

Built-in deployment and collaboration

You can deploy applications directly from the platform with minimal configuration, including hosting APIs, web apps, and services. Replit also supports real-time collaboration, allowing multiple developers to work on the same project simultaneously. This is useful when you need to iterate quickly or share working prototypes.

Cons

Developer-focused workflow

Replit AI is built primarily for developers working directly with code. Its browser-based IDE, coding workflows, and AI assistance are powerful if you are comfortable building and debugging software, but less accessible for non-technical users who need to create or manage applications without writing code. This makes it a stronger fit for engineering teams than for content teams or end users.

Less control over execution environment

Since Replit operates in a managed cloud environment, you have limited control over system-level configurations. Advanced use cases that require custom infrastructure, fine-tuned environments, or low-level optimizations may be harder to implement. This can become a constraint for complex production systems.

AI-driven changes require oversight

The autonomous AI agent can make changes across your codebase, including refactoring or modifying logic. While this improves speed, it also requires careful supervision to avoid unintended behavior. You need to monitor changes closely, especially in critical parts of your application.

When to use Replit

Use Replit AI when you need a complete development environment where you can continuously build, test, and deploy applications with AI assistance.

For example, if you are developing an MVP or internal tool, you can describe features in natural language, have the AI generate backend APIs, connect databases, and scaffold frontend components, then immediately run and test everything in the same environment. You can iterate on features, debug issues, and deploy updates without setting up local infrastructure or switching between multiple tools.

It is also well-suited when you want to collaborate or experiment across different technologies. Since the environment supports multiple languages and real-time execution, you can prototype services, test integrations, and refine application logic in a single workspace.

However, if your application requires strict architectural control, custom infrastructure, or more advanced performance, security, or deployment requirements, the last item on this list may be more appropriate.

4. v0 by Vercel

v0 by Vercel is an AI-driven UI and application generation tool that turns natural language prompts into React and Next.js code. It focuses on generating frontend components, full pages, and full-stack applications using modern libraries like Tailwind CSS and shadcn/ui.

You can describe a UI, upload a reference, or iterate through prompts, and v0 will generate code with a live preview. It also integrates with Git workflows, allowing you to pull your own repository, push changes to it, or deploy it directly through Vercel.

Compared with Lovable, v0 is more focused on generating framework-aligned frontend code, particularly within the React and Next.js ecosystem. Instead of abstracting part of the development away, it gives you well-structured code that can fit into an existing codebase and development workflow with an IDE to edit and refine it.

Pros

High-quality React and Next.js code generation

v0 generates React and Next.js UI code based on modern frontend patterns and common design conventions. The output is often a strong starting point for landing pages, dashboards, and interface scaffolding, though it typically still requires review, testing, and integration before production use.

Seamless integration with Git and existing codebases

v0 supports direct integration with GitHub repositories, allowing you to push generated code into your project, create branches, and open pull requests. This makes it easier to incorporate AI-generated output into standard development workflows. Instead of copying code manually, you can work within your existing version-controlled environment.

Rapid UI prototyping with live preview

You can generate UI components or pages and immediately see a live preview alongside the code. This, in combination with features like Figma importing, allows you to quickly iterate on layouts, styling, and structure without switching between design and development tools. It is particularly useful when refining frontend experiences or validating design ideas.

Direct deployment via Vercel

v0 integrates natively with Vercel’s deployment platform, allowing you to publish applications or previews instantly. You can go from prompt to a live deployment without configuring infrastructure manually. This simplifies the process of testing and sharing working UI implementations.

Cons

Primarily frontend-focused

v0 is designed primarily for frontend generation, especially React and Next.js. While it can connect to APIs or extend into full-stack workflows, it does not provide the same level of backend generation or orchestration as full-stack AI builders. This limits its use if you need end-to-end application scaffolding.

Generated code requires review and integration

Although the generated code follows modern standards, it still needs to be reviewed, tested, and adapted before production use. You are responsible for ensuring that the generated components align with your architecture, performance requirements, and security constraints. This introduces a development validation step.

Framework and ecosystem dependency

v0 is tightly aligned with the React and Next.js ecosystem and integrates closely with Vercel’s platform. If your stack uses different frameworks or requires infrastructure outside this ecosystem, adoption may require additional adjustments. This can limit flexibility in heterogeneous environments and adoption in large organizations.

When to use v0

Use v0 when you need to generate frontend components or pages that integrate directly into a React or Next.js codebase, while still maintaining control over the code.

For example, if you are building a landing page, you can describe the layout, generate React components, and push them directly to your repository using the Git integration. From there, you can review the changes through pull requests, refine the implementation, and deploy with Vercel all within the same platform.

It is also effective when you want to accelerate frontend development without abstracting it away completely. You still work with real code, but you reduce the time spent on repetitive UI construction and styling.

All this said, if your requirement is full-stack generation, backend orchestration, or complete application automation, you will likely need to combine v0 with other tools or extend the generated code manually.

5. Cursor

Cursor is an AI-native code editor built as a fork of Visual Studio Code, designed to integrate AI directly into the development workflow rather than as an external extension. It allows you to generate, edit, refactor, and navigate code using natural language, with deep awareness of your entire codebase.

It also introduces agent-based capabilities, where you can delegate tasks such as writing features, modifying multiple files, or debugging issues, while still retaining full control over the code and execution process.

Cursor enhances the traditional development workflow by embedding AI directly into the code editor, rather than abstracting development through prompt-based application generation. While Lovable focuses on generating applications from prompts, Cursor operates within your existing codebase, allowing you to iteratively build, modify, and maintain software with full control over architecture and implementation.

Pros

Deep codebase awareness and contextual editing

Cursor can index and understand your entire repository, allowing it to make context-aware suggestions and edits across multiple files. This enables you to perform complex refactoring, update logic across modules, or generate features that align with your existing architecture. It goes beyond simple autocomplete by operating at the project level rather than just individual files.

Agent-based development workflow

Cursor includes agent capabilities that allow you to describe tasks in natural language and have the system plan and execute them. This can include writing new features, modifying existing logic, or debugging issues. You can delegate repetitive or multi-step tasks while focusing on higher-level decisions and system design.

Full control over code and architecture

Unlike tools that abstract away implementation details, Cursor operates directly within your codebase. You can review, modify, and structure the generated code according to your requirements. This makes it suitable for complex systems where architectural decisions and long-term maintainability are important.

Advanced editing and refactoring capabilities

Cursor supports multi-line edits, smart rewrites, and code transformations driven by natural language instructions. You can update large sections of code, refactor logic, or apply consistent changes across files without manual repetition. This significantly reduces the effort required for maintaining and evolving codebases.

Cons

Requires development knowledge and active involvement

Cursor is designed for developers and assumes familiarity with programming concepts, tools, and workflows. You are responsible for guiding the AI, validating outputs, and making architectural decisions. It does not abstract development to the level of no-code or prompt-only tools.

Generated code needs validation and testing

Although Cursor provides high-quality suggestions and edits, the generated code still needs to be reviewed, tested, and validated. You must ensure correctness, security, and performance before integrating changes into production systems. This introduces the standard development lifecycle overhead.

Not focused on UI or app-level generation

Cursor does not specialize in generating complete applications or UI systems from prompts. Instead, it focuses on assisting with code-level development within an existing project. If you are looking for rapid UI generation or end-to-end app scaffolding, additional tools may be required.

When to use Cursor

Use Cursor when you are working within an existing codebase and want to accelerate development without losing control over how your system is built.

For example, if you are developing a feature in a large React or backend application, you can describe the functionality in natural language, and Cursor can generate the required logic, update related files, and suggest changes across the repository. You can then review the implementation, refine it, and integrate it into your system while maintaining full visibility into the code.

It is also well-suited for scenarios where you need to refactor or extend complex systems. Since Cursor understands the broader context of your codebase, it can help you make consistent changes across multiple modules, reduce manual effort, and improve development speed without introducing a separate generation or deployment workflow.

It works best as a development accelerator rather than a replacement for engineering workflows. If your goal is to generate complete applications without managing code, a higher-level abstraction tool would be more appropriate.

Final Notes

Lovable is useful when you want to quickly generate applications from prompts, but as your requirements grow, you may need more control or a workflow that fits more naturally into your existing product. When you reach that point, there are several alternatives worth considering.

The right choice depends on what you are trying to build, how much control you need, and where the generated output needs to live.

If you want to generate UI with your own components, without adding a separate generation and deployment cycle, Puck is worth exploring. It gives you control over how UI is created, while keeping the generation flow inside your existing system.

Build a Real-Time Excalidraw-like Collaborative Canvas using Velt MCP and Antigravity🎉

Astrodevil — Thu, 21 May 2026 16:43:40 +0000

In this tutorial, we’ll build an Excalidraw-style collaborative whiteboard using Next.js, HTML5 Canvas, and Velt. You’ll add real-time features like live cursors, comments, presence, and huddles directly into your app. Instead of wiring everything manually, we’ll use Velt MCP and AI agents to handle the integration. We’ll also look at how CRDT-based sync keeps everything in real time.

By the end, you’ll have a fully working multi-user canvas app with production-ready collaboration built in.

What we are building

Excalidraw-style infinite whiteboard
Real-time collaboration with cursors, comments, huddle, notifications, and presence
Multi-user canvas with shared state

Why add collaboration to Canvas apps

Single-user by default: Most canvas apps work locally and don’t support multiple users out of the box
Real-time sync is complex: Handling state sync, conflicts, and updates across users is not trivial
Lack of shared context: Without comments, cursors, and presence, collaboration feels disconnected

Why use Velt

Velt is a collaboration SDK that lets you add real-time, multi-user features directly into your app without building the backend infrastructure yourself. It handles presence, syncing, communication, and UI components out of the box, so you can focus on your product.

Drop-in collaboration layer: Add features like comments, cursors, and presence without building from scratch
Real-time features built in: Cursors, comments, presence, notifications, and huddles
CRDT-based sync support: Enables conflict-free real-time state updates for multi-user apps
AI-powered setup with MCP: Use Velt MCP and agent skills to automatically install and configure features
No infra needed: No need to manage WebSockets, sync engines, or backend services
Customizable UI components: Easily integrate collaboration UI into your existing design system

Prerequisites

Node.js 18+
Velt API key (from Velt dashboard)
AI coding editor (Anitgravity is used in this demo)
Basic React and TypeScript knowledge

Setting up the project

Clone the repository - https://github.com/Studio1HQ/Velt-Demos/tree/main/excalidraw-velt-demo
Run npm install
And then run npm run dev
Now, open http://localhost:3000

Tutorial: Building Velt-powered Excalidraw-like App

Step 1: Set up Velt MCP

Velt MCP lets your editor (Antigravity) run the Velt installer and guide the integration.

Now, add the Velt MCP installer to Antigravity using the command below:

npx -y @velt-js/mcp-installer

Add it to the Antigravity MCP server configuration with command: "npx" and args: ["-y", "@velt-js/mcp-installer"].

Also, Velt Agent Skills guides the AI on what to implement using best practices, while MCP gives it access to the tools needed to actually execute those changes. Together, they make the integration accurate, structured, and reliable. We have both installed and will be used accordingly.

Get your Velt API key:

Go to the Velt Dashboard
Create a project
Copy your API key

Add it to your .env:

NEXT_PUBLIC_VELT_API_KEY=your_api_key_here

Step 2: Start Velt installation using AI

Now that MCP is set up, we can let the AI agent handle the Velt integration for us.

Open your editor (Antigravity) and type:

install velt

This triggers the Velt MCP installer, which runs as a guided setup inside your editor.

Instead of manually adding SDKs and wiring things, the agent walks you through the setup step by step.

It will ask you for a few inputs:

Your project directory
Your Velt API key and auth token
The features you want to enable (comments, presence, cursors, CRDT, etc.)
Where to place the VeltProvider (recommended: app/page.tsx)
UI placement preferences (like corner position)

You can answer each step directly in chat. The flow is simple and guided.

Step 3: Provide the prompt for MCP

At this point, we already have a working whiteboard built manually. Now, instead of integrating Velt step by step ourselves, we use Velt Agent Skills to analyze this existing app and plan how collaboration should be added.

In your editor, after running install velt, provide the following prompt:

I want to start the Velt integration. Review my project structure and use your Velt Agent Skills to plan the CRDT store implementation.

Once you provide this, the agent starts analyzing your codebase. It looks at how your canvas is structured, how state is managed, and where real-time sync can be introduced. Based on this, it generates an integration plan tailored to your whiteboard.

Instead of manually deciding how to structure CRDT or where to wire Velt, the agent uses its skills to plan it correctly for your app.

After reviewing the plan, you can approve it, and the agent will apply the changes step by step.

Step 4: Understand the existing project structure

Before we look at what MCP added, let us understand how this project is structured. Since the agent analyzes your codebase before integrating Velt, this gives context for what it is working with.

The project is organized into three main folders: app, components, and lib.

The app/ folder contains the core application logic. This is where the whiteboard is rendered and all canvas interactions like drawing, selecting, and updating elements are handled.
The components/ folder contains UI elements and collaboration integrations. This is where Velt features are connected to your app, including user identity, comments, and UI-level controls.
The lib/ folder handles state management and shared logic. It manages canvas data, document context, and sync-ready state, making it easier to extend the app with real-time collaboration.

Step 5: Add real-time collaboration features (Using MCP)

Now that the whiteboard is working, we layer Velt on top to make it collaborative. This is where users start seeing each other, interacting in real time, and sharing context.

After you provide the prompt and approve the plan, the MCP installer integrates Velt into your project. It sets up the foundation required for collaboration to work correctly with your existing whiteboard.

Presence and cursors

In app/layout.tsx, the VeltProvider enables real-time awareness across your app. Then in VeltSetup.tsx, each user is identified using. This is what allows Velt to track who is online.

Learn more here

'use client'
import React, { useEffect, useState, Suspense } from "react";
import {
  VeltProvider,
  useSetDocument,
  VeltCursor,
  useVeltClient,
} from "@veltdev/react";
import { useCurrentDocument } from "@/lib/useCurrentDocument";
import { TEST_USERS } from "@/lib/users";
import { useSearchParams } from "next/navigation";

function VeltIdentity({ children }: { children: React.ReactNode }) {
  const { documentId } = useCurrentDocument();
  useSetDocument(documentId ?? "default-whiteboard");
  return <>{children}</>;
}

function VeltProviderInner({ children }: { children: React.ReactNode }) {
  const searchParams = useSearchParams();
  const [user, setUser] = useState(TEST_USERS[0]);

  useEffect(() => {
    const userIndex = searchParams.get("user");
    if (userIndex) {
      const index = parseInt(userIndex);
      if (!isNaN(index) && TEST_USERS[index]) {
        setUser(TEST_USERS[index]);
      }
    } else {
      // Fallback or default behavior
    }
  }, [searchParams]);

  return (
    <VeltProvider
      apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY!}
      authProvider={{
        user: user,
      }}
    >
      <VeltIdentity>
        {/* <VeltCursor /> */}
        {children}
      </VeltIdentity>
    </VeltProvider>
  );
}

export function VeltSetup({ children }: { children: React.ReactNode }) {
  return (
    <Suspense fallback={null}>
      <VeltProviderInner>{children}</VeltProviderInner>
    </Suspense>
  );
}

Once identity is set, Velt automatically shows:

Active users (avatars)
Live cursor positions

You don’t have to manually sync cursor movement. Velt handles that internally based on user sessions.

Canvas comments

Comments are one of the most important parts of a canvas app.

"use client";

import { useCommentAnnotations, VeltCommentPin } from "@veltdev/react";
import { Point } from "@/lib/types";
import { useWhiteboardStore } from "@/lib/useWhiteboardStore";

interface CanvasCommentLayerProps {
  zoom: number;
  pan: Point;
}

In CanvasCommentLayer.tsx, comments are rendered as an overlay on top of the canvas. Instead of attaching comments to DOM elements, we attach them to canvas coordinates.

 {
              // Use bounds or specific fields
              // Normalized rect provided by normalizeRect helper? not available here easily.
              // Just use raw coords if available, or approximate.
              // Rect/Ellipse/Diamond have x1,y1,x2,y2 usually?
              // Wait, types.ts says DrawingElement...
              // Let's assume standard shape properties
              if (
                "x1" in element &&
                "y1" in element &&
                "x2" in element &&
                "y2" in element
              ) {
                worldX = (element.x1 + element.x2) / 2;
                worldY = (element.y1 + element.y2) / 2;
              }
            } else if (element.type === "line" || element.type === "arrow") {
              worldX = (element.x1 + element.x2) / 2;
              worldY = (element.y1 + element.y2) / 2;
            }
          }
        }

        if (typeof worldX !== "number" || typeof worldY !== "number") {
          return null;
        }

        const screenX = (worldX + pan.x) * zoom;
        const screenY = (worldY + pan.y) * zoom;

        return (
          <div
            key={annotation.annotationId}
            style={{
              position: "absolute",
              left: `${screenX}px`,
              top: `${screenY}px`,
              transform: "translate(-50%, -100%)",
              zIndex: 50,
              pointerEvents: "auto",
            }}
          >
            <VeltCommentPin annotationId={annotation.annotationId} />
          </div>
        );
      })}
    </div>
  );

From app[/page.tsx](https://github.com/Studio1HQ/Velt-Demos/blob/main/excalidraw-velt-demo/app/page.tsx), you trigger comments like this:

Capture the (x, y) position on click
Pass context to Velt
Optionally attach to a specific element using elementId

This enables:

Freeform comments anywhere on the canvas
Context-aware discussions linked to shapes

This is very similar to how tools like Miro or Figma handle comments.

Sidebar and UI controls

These files handle user-facing UI around collaboration.

ProfileMenu.tsx shows user identity and active participants
ThemeToggle.tsx syncs your app theme with Velt UI

ProfileMenu.tsx

"use client";

import React, { useEffect, useState } from "react";
import { ChevronDown, User, Check, LogOut, RefreshCwIcon } from "lucide-react";
// import { useVeltClient } from "@veltdev/react";
import { TEST_USERS } from "@/lib/users";

export function ProfileMenu() {
  const [isOpen, setIsOpen] = useState(false);
  const [currentUser, setCurrentUser] = useState(TEST_USERS[0]); // Default to first user

  // Initialize from URL on mount
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const userIndex = params.get("user");
    if (userIndex) {
      const index = parseInt(userIndex);
      if (!isNaN(index) && TEST_USERS[index]) {
        setCurrentUser(TEST_USERS[index]);
      }
    }
  }, []);

  const handleUserSelect = (user: (typeof TEST_USERS)[0], index: number) => {
    setCurrentUser(user);
    setIsOpen(false);

    // Update URL and reload to ensure clean session isolation via VeltProvider authProvider
    const url = new URL(window.location.href);
    url.searchParams.set("user", index.toString());
    window.location.href = url.toString();
  };

Velt components (like comments sidebar) automatically adapt to your app’s theme. This keeps the experience consistent across your UI and Velt overlays.

Notifications and huddle

Velt also provides built-in tools for:

You can add these as UI buttons in your toolbar. Once added:

Notifications show real-time updates (comments, mentions, etc.)
Huddle lets users start live audio/video sessions inside your app

No extra backend setup is needed. These features are already part of the Velt SDK.

You can see this here in page.tsx

 <div className="mx-1 h-6 w-px bg-slate-200 dark:bg-neutral-800" />
        <div className="flex items-center gap-1">
          <VeltCommentTool darkMode={isDark} />
          <VeltHuddleTool darkMode={isDark} />
          <VeltNotificationsTool darkMode={isDark} />
        </div>
      </section>

Step 6: CRDT-based state sync

Up to this point, the whiteboard works, and collaboration features like comments and presence are in place. But for a real collaborative canvas, the most important piece is shared state. Every shape, line, or text element needs to stay in sync across all users in real time.

This is where CRDT comes in.

In a typical canvas app, state lives locally. When a user draws something, it updates only their view. To make this collaborative, we need a shared state that all users can read and write to.

In useWhiteboardStore.ts, instead of using local state, we use Velt’s CRDT hook:

This creates a shared store that is automatically synced across all connected users.

The id acts as a unique identifier for this piece of state. As long as users are in the same document, they are all connected to this store. The map structure is used to store canvas elements, where each element is indexed by its ID.

"use client";

import { useCallback, useEffect, useMemo, useRef } from "react";
import { useVeltCrdtStore } from "@veltdev/crdt-react";
import type { DrawingElement } from "./types";

type ElementMap = Record<string, DrawingElement>;

export function useWhiteboardStore() {
  const { value, update } = useVeltCrdtStore<ElementMap>({
    id: "whiteboard-elements",
    type: "map",
    initialValue: {},
  });

  const elements: DrawingElement[] = useMemo(
    () => Object.values(value ?? {}).sort((a, b) => a.id.localeCompare(b.id)),
    [value],
  );

  const valueRef = useRef<ElementMap>(value ?? {});

  useEffect(() => {
    valueRef.current = value ?? {};
  }, [value]);

When a user draws a new shape or updates an existing one, the change is not stored locally. Instead, it is written to the CRDT store.

Functions like adding or updating elements internally call the update function provided by useVeltCrdtStore. Once updated, the change is automatically propagated to every other user connected to the same session.

const addElement = useCallback(
    (el: DrawingElement) => {
      update({ ...valueRef.current, [el.id]: el });
    },
    [update],
  );

  const updateElement = useCallback(
    (el: DrawingElement) => {
      update({ ...valueRef.current, [el.id]: el });
    },
    [update],
  );

  const deleteElement = useCallback(
    (id: string) => {
      const next = { ...valueRef.current };
      delete next[id];
      update(next);
    },
    [update],
  );

  return { elements, addElement, updateElement, deleteElement, rawMap: value };

There is no need to manage WebSockets, events, or manual syncing. Velt handles all of that behind the scenes.

The storageProxy.ts file acts as a thin abstraction layer between your canvas logic and the shared store. Instead of directly interacting with the CRDT store everywhere, this layer helps keep the code clean and organized.

It separates:

Canvas logic
State update logic

This makes the system easier to maintain and extend.

"use client";

/**
 * Validates if the code is running in a browser environment
 */
const isBrowser = typeof window !== "undefined";

/**
 * Proxies localStorage to redirect specific keys to sessionStorage
 * This allows Velt to have isolated sessions per tab (using sessionStorage)
 * while the rest of the app continues to use localStorage.
 */
export function initStorageProxy() {
  if (!isBrowser) return;

  // Store the original localStorage implementation
  const originalLocalStorage = window.localStorage;
  const originalSessionStorage = window.sessionStorage;

  // Keys that should be redirected to sessionStorage
  // Velt uses keys starting with 'velt', 'snippyly', or '_v' (e.g., _viu, _vv)
  // Also proxying firebase keys as Velt likely uses them for auth/presence
  const isVeltKey = (key: string) => {
    const k = key.toLowerCase();
    return (
      k.startsWith("velt") ||
      k.startsWith("snippyly") ||
      k.startsWith("_v") ||
      k.startsWith("firebase")
    );
  };

Step 7: Multi-user simulation

The user setup lives in lib/users.ts. This file defines a small set of users with basic details like name, color, and avatar. These are used by Velt to represent each participant across features like cursors, comments, and presence.

In components/velt/VeltSetup.tsx, one of these users is selected when the app loads. A random user is picked and passed to Velt. This is what establishes the session.

export const TEST_USERS = [
  {
    userId: "user1",
    name: "Robin",
    email: "robin@velt.dev",
    photoUrl:
      "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=800&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXR8ZW58MHx8MHx8fDA%3D",
    color: "#F97316", // Orange
    organizationId: "excalidraw-demo",
  },
  {
    userId: "user2",
    name: "Alicia",
    email: "alicia@velt.dev",
    photoUrl:
      "https://images.unsplash.com/photo-1531746020798-e6953c6e8e04?q=80&w=1364&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
    color: "#3B82F6", // Blue
    organizationId: "excalidraw-demo",
  },
];

Every time the app loads, a different user can be assigned. From Velt’s perspective, each session is now a unique participant in the same document.

Step 8: Run and test the app

Now let’s run the app and see everything working together.

Start the development server:

npm run dev

Once the app is running, open it in your browser at http://localhost:3000.

To test collaboration, open the same app in another window. You can use an incognito tab or a different browser. Each session will act as a different user.

As you interact with the canvas, you’ll start noticing the real-time behavior. Drawing a shape in one window reflects instantly in the other. You’ll see users appearing in presence, and comments syncing across both sessions.

At this point, your whiteboard is fully collaborative, with multiple users interacting on the same canvas in real time.

Here is the deployed link for you to explore the demo.

Wrapping up

We started with a simple canvas and turned it into a fully collaborative whiteboard. Along the way, we added real-time cursors, presence, comments, notifications, and even voice huddles using Velt. Instead of building sync logic and infra from scratch, we used Velt MCP and agent skills to handle the heavy lifting and get everything working quickly.

The key takeaway here is simple. You don’t need to spend weeks building real-time systems to make your app collaborative. With the right tools, you can focus on your product and let the platform handle sync, presence, and communication.

From here, you can extend this further:

Connect real authentication instead of simulated users
Improve CRDT logic for more complex canvas operations
Customize Velt UI components to match your product

If you’re building any product where users need to collaborate, this is a pattern worth exploring.

What would your app look like if it supported real-time collaboration from day one?

Try Velt and start adding features like comments, presence, cursors, CRDT sync, notifications, and huddles to your app.

Build a Dropbox Paper-Style Collaborative Editor with Next.js and Velt💥

Astrodevil — Thu, 21 May 2026 16:32:50 +0000

Introduction

Modern apps need built-in collaboration. Users expect to comment on text, see who is online, and receive updates without switching tools. If your editor lacks these features, discussions move to Slack or email. Context gets lost. Engagement drops.

In this guide, we will build a Dropbox Paper-style collaborative editor. You will add inline comments to selected text, show real-time presence, and enable in-app notifications. The stack uses Next.js with the App Router, TipTap for rich text editing, and Velt for collaboration infrastructure.

Building real-time collaboration from scratch is complex and time-consuming. Tools like Velt abstract that complexity so you can focus on product logic instead of infrastructure.

By the end, you will have a fully working collaborative editor running locally.

Tech Stack Overview

This project uses a modern React-based stack built for real-time interaction. Each tool has a clear responsibility and works well in collaborative environments.

Next.js (App Router): Provides the application structure and routing layer. The App Router makes it easy to organize layouts, wrap the app with providers, and manage client components cleanly.
TipTap Editor: A highly extensible rich text editor built on ProseMirror. It allows precise control over marks and extensions, which makes it ideal for inline commenting and collaborative annotations.
Velt SDK: Handles real-time comments, presence, notifications, and collaboration state. It abstracts the backend complexity required for multi-user interaction.
Tailwind CSS + shadcn/ui: Enables fast UI development with consistent styling and accessible components.
Zustand: Manages lightweight global state, such as switching between predefined users for collaboration simulation.

Project Structure Walkthrough

Before diving into the implementation, it helps to understand how the project is organized. The structure separates layout, collaboration logic, and UI components so each concern stays isolated.

app/ — Layout and Velt Initialization

Contains the root layout and App Router setup. This is where VeltProvider wraps the application and initializes the SDK with your API key and active user.
components/ — UI and Core Features

Holds the main building blocks of the interface, including the editor and the top navigation bar.
paper-document.tsx — TipTap + Velt Integration

Implements the rich text editor and registers the Velt TipTap extension. This file handles rendering comments and adding new ones to selected text.
top-bar.tsx — Presence, Notifications, Sidebar Controls

Displays active users, shows notifications, and provides access to the comments sidebar.
helper/userdb.ts — User Switching Logic

Uses Zustand to manage predefined users and simulate multi-user collaboration.

What is Velt?

Velt is a collaboration SDK that lets you add real-time features like comments, presence, and notifications directly into your product. Instead of building backend infrastructure for multi-user sync, conflict resolution, and event handling, you integrate Velt components and ship collaboration features in days.

Below are the key features used in this project:

Contextual Comments: Add inline comments to specific UI elements or selected text. Comments stay attached to their exact position, enabling precise discussions inside the app.
Real-Time Presence: Show who is currently viewing or interacting with the document. Presence indicators update instantly across users.
Notifications System: Trigger in-app notifications for mentions, replies, and updates. Keeps users informed without leaving the product.
Comments Sidebar: Centralized panel to view, manage, and navigate all comment threads within the document.
Multi-User Collaboration Support: Handles user identity, ownership of comments, and live updates so multiple users can interact with the same document seamlessly.

Local Setup (Quick Start)

First, install the Velt client SDK:

npm install @veltdev/client

Velt must be initialized at the root of your application so every component can access the collaboration state. In a Next.js App Router project, this means wrapping your app inside VeltProvider in the root layout.

Create a .env file in the root directory and add your Velt API key:

NEXT_PUBLIC_VELT_ID = your_velt_api_key_here

Clone the repository and install the dependencies:

git clone https://github.com/Studio1HQ/dropbox-velt.git
cd dropbox-velt
npm install

Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

If you're using Velt Agent Skills or MCP-based setup, manual installation steps can be skipped since the AI handles SDK wiring and configuration. This demo uses the standard manual SDK integration.

Wrapping the App with `VeltProvider`

Before integrating Velt features into the editor, Velt must be available across the application. In this project, the provider is added inside the root layout so every component can access collaboration features.

This setup lives in app/layout.tsx. The VeltProvider wraps the entire app and receives the API key from the environment variable. The ThemeProvider is nested inside it so both theme and collaboration context are globally available.

The provider must sit at the top level because presence, comments, and notifications rely on shared context. If it is mounted deeper in the tree, some components will not receive real-time updates.

"use client";

import { ThemeProvider } from "@/hooks/use-theme";
import { VeltProvider } from "@veltdev/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_ID || ""}>
      <ThemeProvider>{children}</ThemeProvider>
    </VeltProvider>
  );
}

Now that Velt is initialized globally, we can integrate it directly into the TipTap editor.

Adding Inline Comments to TipTap

The core collaboration logic lives inside components/paper-document.tsx. This file initializes the TipTap editor and connects it to Velt using the TipTap comments plugin.

"use client";

import { useEditor, EditorContent, BubbleMenu } from "@tiptap/react";
import { StarterKit } from "@tiptap/starter-kit";
import {
  TiptapVeltComments,
  renderComments,
  addComment,
} from "@veltdev/tiptap-velt-comments";
import { useCommentAnnotations } from "@veltdev/react";
import { useEffect } from "react";

import { Avatar, AvatarFallback } from "./ui/avatar";
import { Separator } from "./ui/separator";
import { Button } from "./ui/button";
import {
  MessageCircle,
} from "lucide-react";

const EDITOR_ID = "paper-document-editor";

Start by installing @veltdev/tiptap-velt-comments. This package bridges TipTap’s editor state with Velt’s comment system. Once installed, register the TiptapVeltComments extension inside the editor configuration. This enables comment marks on selected text and connects them to Velt’s backend.

Each editor instance must have a unique editor ID. In this project, a fixed document ID is used so comments stay tied to the same document across sessions.

When the editor loads, renderComments syncs and displays existing annotations from Velt. When a user selects text and clicks the comment action in the bubble menu, addComment creates a new contextual thread linked to that selection.

The bubble menu integration ensures users can comment directly on highlighted text. This creates a Google Docs-style inline commenting experience inside your own app.

export function PaperDocument() {
  const editor = useEditor({
    extensions: [
      StarterKit,
      TiptapVeltComments.configure({
        persistVeltMarks: false,
      }),
    ],
    content: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "This document contains all the essential information and resources for our current project. Feel free to add comments, suggestions, or ask questions using the tools on the right.",
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Overview" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "Our team is working on creating a comprehensive solution that addresses the key challenges in collaborative document editing and file sharing. This project aims to deliver a seamless experience for teams of all sizes.",
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Key Features" }],
        },
        {
          type: "bulletList",
          content: [
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Real-time collaboration with team members" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Inline comments and feedback" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Version history and rollback capabilities" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Secure sharing with granular permissions" }] },
              ],
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Timeline" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "The project is divided into multiple phases, each with specific deliverables and milestones. We're currently in Phase 2, focusing on core functionality and user experience improvements."
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Resources" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "Below you'll find all the files and documents related to this project. Click on any item to preview or download it."
            },
          ],
        },
      ],
    },
    autofocus: false,
    immediatelyRender: false,
  });

Adding Presence & Notifications

Collaboration is not just about comments. Users need awareness and updates in real time. In this project, these features are implemented inside components/top-bar.tsx and connected to the editor view.

"use client";
import {
  useVeltClient,
  VeltCommentsSidebar,
  VeltNotificationsTool,
  VeltPresence,
  VeltSidebarButton,
} from "@veltdev/react";

import { names, userIds, useUserStore } from "@/helper/userdb";
import { Rocket, Share, User } from "lucide-react";
import React, { useEffect, useMemo, useRef } from "react";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { FileText, Share2, MoreHorizontal, ChevronDown } from "lucide-react";
import { Button } from "./ui/button";
import useTheme, { ThemeToggleButton } from "@/hooks/use-theme";

VeltPresence displays the users currently viewing the document. It renders active user avatars in the top bar and updates instantly when someone joins or leaves. This gives immediate visibility into who is online and working on the same content.

VeltNotificationsTool adds an in-app notification system. It surfaces mentions, replies, and comment activity without requiring page refreshes. Users stay informed while remaining inside the document.

VeltSidebarButton toggles the comments panel. When clicked, it opens VeltCommentsSidebar, which lists all comment threads in one place. Users can review discussions, jump to specific annotations, and manage conversations efficiently.

export function TopBar() {
  const { theme } = useTheme();
  const { user, setUser } = useUserStore();
  const { client } = useVeltClient();
  const prevUserRef = useRef(user);
  const isInitializingRef = useRef(false); // Prevent overlapping initialization calls

  const predefinedUsers = useMemo(
    () =>
      userIds.map((uid, index) => {
        const avatarUrls = [
          "https://api.dicebear.com/7.x/pixel-art/svg?seed=Nany",
          "https://api.dicebear.com/7.x/pixel-art/svg?seed=Mary",
        ];
        return {
          uid: uid,
          displayName: names[index],
          email: `${names[index].toLowerCase()}@gmail.com`,
          photoUrl: avatarUrls[index],
        };
      }),
    []
  );

  // Initialize user from localStorage if none exists
  useEffect(() => {
    if (typeof window !== "undefined" && !user) {
      const storedUser = localStorage.getItem("user-storage");
      if (!storedUser) {
        setUser(predefinedUsers[0]);
      }
    }
  }, [user, setUser, predefinedUsers]);

  // Handle Velt client initialization, user identification, and document setting
  useEffect(() => {
    if (!client || !user || isInitializingRef.current) {
      console.log("Velt init skipped:", {
        client: !!client,
        user: !!user,
        initializing: isInitializingRef.current,
      });
      return;
    }

    const initializeVelt = async () => {
      isInitializingRef.current = true;
      try {
        // Detect user switch
        const isUserSwitch = prevUserRef.current?.uid !== user.uid;
        prevUserRef.current = user;

        console.log("Starting Velt init for user:", user.uid, { isUserSwitch });

        // Re-identify the user (handles initial and switches)
        const veltUser = {
          userId: user.uid,
          organizationId: "organization_id",
          name: user.displayName,
          email: user.email,
          photoUrl: user.photoUrl,
        };
        await client.identify(veltUser);
        console.log("Velt user identified:", veltUser.userId);
        await client.setDocuments([
          {
            id: "drop-box-velt",
            metadata: { documentName: "drop-box-velt" },
          },
        ]);
        console.log("Velt documents set: drop-box-velt");
      } catch (error) {
        console.error("Error initializing Velt:", error);
      } finally {
        isInitializingRef.current = false;
      }
    };

    initializeVelt();
  }, [client, user]); // Re-run on client or user change

Together, these components create a real-time collaborative environment with visibility, context, and structured discussion.

Multi-User Switching (Simulating Collaboration)

To demonstrate collaboration locally, this project simulates multiple users using a simple state store. The logic lives inside helper/userdb.ts, where predefined users like Nany and Mary are defined with unique IDs and avatars.

The store is built with Zustand. It keeps track of the currently active user and exposes a method to switch between them. When you select a different user from the dropdown in components/top-bar.tsx, the active user state updates instantly.

Because VeltProvider receives the current userId, switching users changes how Velt identifies the session. Presence indicators update automatically, and new comments are attributed to the selected user. Existing comments also display correct ownership based on user identity.

This setup allows you to test real-time presence, comment ownership, and notification behavior on localhost without needing multiple devices or accounts.

import { create } from "zustand";
import { persist } from "zustand/middleware";

export type User = {
  uid: string;
  displayName: string;
  email: string;
  photoUrl?: string;
};

export interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
}

export const userIds = ["user001", "user002"];
export const names = ["Nany", "Mary"];

export const useUserStore = create<UserStore>()(
  persist(
    (set) => ({
      user: null,
      setUser: (user) => set({ user }),
    }),
    {
      name: "user-storage",
    }
  )
);

How Everything Works Together

At a high level, the editor, Velt SDK, and UI components form a connected real-time collaboration loop. Each layer has a clear responsibility, but they operate as a single system.

Editor → Velt Plugin → Comments

The TipTap editor in components/paper-document.tsx registers the Velt comments extension. When a user selects text and adds a comment, the plugin sends the annotation to Velt. Velt syncs it across sessions, and the editor renders it inline.
User Change → Presence Update

The active user is managed in helper/userdb.ts. When switching users from components/top-bar.tsx, the userId passed to VeltProvider changes. Velt immediately updates presence and ensures new comments reflect the correct ownership.
Comment → Sidebar → Notification

When a comment is created, it appears inline and is listed inside VeltCommentsSidebar, and triggers updates in VeltNotificationsTool. All views stay synchronized in real time.
Provider → SDK Lifecycle

VeltProvider in app/layout.tsx manages initialization and global collaboration state. It maintains the real-time connection and ensures all components receive updates consistently.

Demo

Final Result & Takeaways

We built a Dropbox Paper-style collaborative editor with inline comments, real-time presence, and in-app notifications. The entire collaboration layer runs inside the product without relying on external tools. Instead of building real-time infrastructure from scratch, Velt handles synchronization, ownership, and updates. This pattern applies to CMS platforms, dashboards, internal tools, document editors, and any product that needs structured collaboration.

If you are building a collaborative feature, try integrating Velt and ship production-ready comments, presence, and notifications in days instead of months.

Resources

Velt Documentation
GitHub Repository
Live Demo: Try the application yourself

Building a Superhuman-Style Collaborative Email Editor with Next.js and Velt🔥

Astrodevil — Thu, 21 May 2026 16:24:55 +0000

Introduction

Superhuman rethinks email as a fast, focused workspace. Its clean interface and keyboard-first flow make working through email feel deliberate instead of noisy.

Adding collaboration to this kind of experience is where things get difficult. Real-time updates, user presence, inline comments, and notifications usually require complex backend systems and real-time infrastructure.

In this tutorial, we’ll build a Superhuman-style collaborative email interface using Next.js and Velt. The UI stays simple and frontend-focused, while Velt handles comments, presence, and notifications behind the scenes.

What We’re Building

A Superhuman-style email interface with a clean inbox and focused email preview
Inline comments directly on email content using Velt
Real-time user presence when multiple users view the same email
In-app notifications for collaboration activity
Light and dark theme support
Multi-user collaboration using predefined users, without backend or database setup

Tech Stack Overview

Next.js (App Router): Structures the application and layouts for a modern email interface
React: Builds the inbox, email preview, and interactive UI components
Tailwind CSS: Enables a clean, minimal UI with easy theming
shadcn ui (powered by Radix UI): Provides accessible, reusable UI primitives
Tiptap: Renders rich email content and supports inline annotations
Zustand: Manages demo users for multi-user collaboration testing
Velt: Acts as the collaboration layer, adding comments, presence, and notifications without backend infrastructure

Project Setup

Start by cloning the repository and moving into the project directory:

gitclone https://github.com/Studio1HQ/superhuman-demo-eg
cd superhuman-demo-eg

Next, install the project dependencies:

npm install

To enable collaboration features, create a .env.local file in the root of the project and add your Velt API key:

NEXT_PUBLIC_VELT_ID=your_velt_api_key_here

You can generate this key from the Velt dashboard. Once the environment variable is set, start the development server:

npm run dev

Open http://localhost:3000 in your browser to see the Superhuman-style email interface running locally with real-time collaboration enabled.

Why Use Velt?

If you try to add collaboration yourself, you quickly run into hard problems. You need real-time updates, user presence, comments that stay in sync, and notifications that fire at the right moment. That usually means WebSockets, backend services, and a lot of edge cases to manage as more users join.

Velt lets you skip all of that. You plug it into your app and get comments, presence, notifications, and shared context immediately. You don’t worry about syncing users or handling concurrent updates. Your code stays focused on the UI and user experience, not real-time infrastructure.

This is especially useful when you’re building fast. You can take an existing interface like an email preview or document view and make it collaborative in minutes. Features like reactions, read status, and threaded comments work out of the box, so you spend time improving the product instead of rebuilding collaboration from scratch.

Understanding the App Structure

This project follows a clean, layout-first structure using the Next.js App Router. Routing and global configuration live inside the app/ directory, while the main application UI is grouped under the (app) route for clarity.

Global styles and shared providers are defined at the layout level. This ensures theme handling and collaboration setup are available across the entire app without passing props through components.

The UI is built in a component-driven way. Core features like the sidebar, email list, and email preview live in the components folder, while reusable UI primitives are isolated in components/ui. This separation keeps the codebase easy to navigate and ready for collaboration features.

Building the Email UI

Before adding real-time collaboration, the first step is getting the email experience right. This section focuses purely on structure and interaction, keeping the UI fast and familiar, inspired by Superhuman.

Sidebar and Navigation

components/sidebar.tsx
components/top-navigation.tsx

The sidebar is responsible for inbox navigation. It provides quick access to different sections and keeps the layout consistent, which is important for an email workflow where users switch context frequently.

The top navigation handles global actions such as search, theme toggling, and user context. At this stage, it serves purely as a layout and control surface, without any collaboration-related logic.

export function Sidebar({ isOpen, onClose }: SidebarProps) {
  const [isCollapsed, setIsCollapsed] = useState(false);
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const checkMobile = () => {
      setIsMobile(window.innerWidth < 768);
    };

    checkMobile();
    window.addEventListener('resize', checkMobile);
    return () => window.removeEventListener('resize', checkMobile);
  }, []);

Email List and Preview

components/email-list.tsx
components/email-preview.tsx

The email list displays available messages and manages selection. When a user selects an email, the selected data is passed down to the preview component, keeping state flow simple and predictable.

The email preview renders the full content of the selected message. This component is intentionally kept focused on reading and layout, making it a clean and stable foundation before introducing collaborative features later in the app.

export function EmailPreview() {
    return (
        <div className="flex-1 flex bg-background min-w-0 hidden lg:flex">
            {/* Main Email Content */}
            <div className="flex-1 flex flex-col">
                {/* Email Header */}
                <div className="border-b p-6">
                    <div className="flex items-start justify-between mb-4">
                        <div className="flex-1">
                            <h1 className="text-xl font-semibold mb-2">
                                {currentEmail.subject}
                            </h1>
                            <div className="flex items-center gap-4 text-sm text-muted-foreground">
                                <div className="flex items-center gap-2">
                                    <Avatar className="w-6 h-6">
                                        <AvatarImage src={currentEmail.senderAvatar} />
                                        <AvatarFallback className="text-xs">
                                            {currentEmail.sender.charAt(0)}
                                        </AvatarFallback>
                                    </Avatar>
                                    <span className="text-[13px] font-medium text-foreground">{currentEmail.sender}</span>
                                    <span className="text-[13px] hidden md:inline">&lt;{currentEmail.senderEmail}&gt;</span>
                                </div>
                                <span className="text-[13px] hidden sm:inline">{format(currentEmail.date, 'MMM d, yyyy')}</span>
                                <span className="text-[13px] sm:hidden">{format(currentEmail.date, 'MMM d, yyyy')}</span>
                            </div>
                        </div>

                        <div className="flex items-center gap-1">
                            <Button variant="ghost" size="icon">
                                <Star className={currentEmail.isStarred ? "fill-yellow-400 text-yellow-400" : ""} />
                            </Button>
                            <Button variant="ghost" size="icon">
                                <Archive className="h-4 w-4" />
                            </Button>
                            <Button variant="ghost" size="icon">
                                <Trash2 className="h-4 w-4" />
                            </Button>
                            <Button variant="ghost" size="icon" className="hidden sm:flex">
                                <MoreHorizontal className="h-4 w-4" />
                            </Button>
                        </div>
                    </div>

                    {/* Labels */}
                    <div className="flex gap-2">
                        {currentEmail.labels.map((label) => (
                            <Badge key={label} variant="secondary" className="text-xs">
                                {label}
                            </Badge>
                        ))}
                    </div>
                </div>

                {/* Email Content */}
                <div className="flex-1 p-6 overflow-y-auto max-h-[calc(100vh-330px)]">
                    <EmailPreviewComponent content={currentEmail.content} />
                </div>

                {/* Action Bar */}
                <div className="border-t p-4">
                    <div className="flex items-center gap-2">
                        <Button className="gap-2">
                            <Reply className="h-4 w-4" />
                            <span className="hidden sm:inline">Reply</span>
                        </Button>
                        <Button variant="outline" className="gap-2">
                            <ReplyAll className="h-4 w-4" />
                            <span className="hidden md:inline">Reply All</span>
                        </Button>
                        <Button variant="outline" className="gap-2">
                            <Forward className="h-4 w-4" />
                            <span className="hidden sm:inline">Forward</span>
                        </Button>
                    </div>
                </div>

                {/* Keyboard Shortcuts Helper */}
                <div className="border-t bg-muted/20 p-3 hidden md:block">
                    <div className="flex items-center justify-center gap-6 text-xs text-muted-foreground">
                        <div className="flex items-center gap-1">
                            <kbd className="px-1.5 py-0.5 bg-muted rounded text-xs">r</kbd>
                            <span>Reply</span>
                        </div>
                        <div className="flex items-center gap-1">
                            <kbd className="px-1.5 py-0.5 bg-muted rounded text-xs">a</kbd>
                            <span>Archive</span>
                        </div>
                        <div className="flex items-center gap-1">
                            <kbd className="px-1.5 py-0.5 bg-muted rounded text-xs">s</kbd>
                            <span>Star</span>
                        </div>
                        <div className="flex items-center gap-1">
                            <kbd className="px-1.5 py-0.5 bg-muted rounded text-xs">#</kbd>
                            <span>Delete</span>
                        </div>
                    </div>
                </div>
            </div>

        </div>
    );
}

Reusable UI Components

All reusable UI components live inside the components/ui folder. These components handle common interface patterns such as buttons, inputs, avatars, dropdown menus, and modals that are used across the inbox and email preview.

Instead of building these elements from scratch, the project uses shadcn ui, which is built on top of Radix UI primitives. Radix provides accessibility, keyboard interactions, and predictable behavior, while shadcn ui keeps the components unstyled and flexible so they fit naturally into the design.

This approach keeps the UI consistent across the app. Updating a button, input, or dropdown in one place automatically reflects everywhere it’s used, making the interface easier to maintain as the application grows.

User Management for Collaboration Testing

Next, the app needs a way to represent different users so collaboration can be tested locally. Instead of setting up full authentication, this project uses a simple user store defined in helper/userdb.ts.

The file contains a small set of predefined users with names and avatars. This makes it easy to switch between users and simulate real collaboration scenarios without signing in or managing sessions. When a user is changed, the app updates instantly, which is enough to test presence, comments, and notifications.

For this tutorial, this approach replaces a full authentication system. In a production app, these users would come from your real auth flow, but for learning and experimentation, a lightweight user store keeps the focus on collaboration rather than authentication complexity.

The userdb.ts file look like this:

import { create } from "zustand";
import { persist } from "zustand/middleware";

export type User = {
  uid: string;
  displayName: string;
  email: string;
  photoUrl?: string;
};

export interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
}

export const userIds = ["user001", "user002"];
export const names = ["Nany", "Mary"];

export const useUserStore = create<UserStore>()(
  persist(
    (set) => ({
      user: null,
      setUser: (user) => set({ user }),
    }),
    {
      name: "user-storage",
    }
  )
);

Theme Management

The app includes light and dark theme support using a custom hook defined in hooks/use-theme.tsx. The hook controls the active theme and updates the document state so the UI responds immediately to theme changes.

The selected theme is stored in localStorage, which allows the preference to persist across page reloads and browser sessions. Users return to the same theme without needing to reset it each time.

This theme state is also passed to Velt components. As a result, comments, presence indicators, and notification panels automatically match the app’s light or dark mode, keeping the experience visually consistent.

Introducing Velt into the App

With the email UI in place, the next step is to introduce real-time collaboration. Velt works by wrapping your application with a provider and then identifying who the current user is and what they are collaborating on. Once this is set up, all collaboration features are built on top of it.

Adding the Velt Provider

app/(app)/layout.tsx

The first step is to wrap the application with the VeltProvider. This initializes Velt and makes the collaboration client available throughout the app. Without this provider, features like comments, presence, and notifications will not work.

Add the provider at the layout level, so it applies to every page:

"use client";

import { ThemeProvider } from "@/hooks/use-theme";
import { VeltProvider } from "@veltdev/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_ID || ""}>
      <ThemeProvider>{children}</ThemeProvider>
    </VeltProvider>
  );
}

Adding Collaboration Controls to the Header

components/top-navigation.tsx

The header is the right place for collaboration controls because it’s always visible and shared across the app. It provides global context, showing who is online and surfacing collaboration activity without interrupting the email content.

Velt’s UI components are added directly to the header:

VeltPresence
VeltNotificationsTool
VeltCommentsSidebar
VeltSidebarButton

Once added, these components work automatically with the existing user and document setup, enabling real-time collaboration across the app.

"use client";

import { Search, Command, Menu } from "lucide-react";
import { Input } from "@/components/ui/input";
import { Badge } from "@/components/ui/badge";
import {
  useVeltClient,
  VeltCommentsSidebar,
  VeltNotificationsTool,
  VeltPresence,
  VeltSidebarButton,
} from "@veltdev/react";

import { names, userIds, useUserStore } from "@/helper/userdb";
import { User } from "lucide-react";
import React, { useEffect, useMemo, useRef } from "react";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { ChevronDown } from "lucide-react";
import { Button } from "@/components/ui/button";
import useTheme, { ThemeToggleButton } from "@/hooks/use-theme";

Next, let us see how the Velt components are used.

The VeltPresence component displays avatars of users who are currently viewing the same document. It updates automatically as users join or leave, giving immediate awareness of who is active.

VeltNotificationsTool adds a notification bell that surfaces collaboration events such as replies, mentions, and comment activity. Notifications are grouped and updated in real time, without requiring any custom event handling.

VeltSidebarButton and VeltCommentsSidebar work together to manage discussions. The button toggles the comments sidebar, while the sidebar itself provides a centralized view of all comments across the document. Both components stay in sync with the current user and document context automatically.

Together, these components add presence, notifications, and discussion management to the app with minimal code, relying entirely on the existing Velt setup for user identification and document context.

<div className="flex items-center gap-1">
          <div className="flex items-center space-x-3">
            <DropdownMenu>
              <DropdownMenuTrigger asChild>
                <Button
                  variant="outline"
                  size="sm"
                  className="flex items-center space-x-2 h-8 bg-white  text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 hover:bg-gray-200  dark:border dark:border-white/30 dark:!bg-[#121212] dark:hover:!bg-gray-700"
                >
                  <Avatar className="w-5 h-5">
                    <AvatarImage
                      src={user?.photoUrl || "https://via.placeholder.com/100"}
                      alt={user?.displayName || "User"}
                    />
                    <AvatarFallback className="text-xs">
                      {user?.displayName}
                    </AvatarFallback>
                  </Avatar>
                  <span className="text-sm truncate max-w-[100px]">
                    {user?.displayName}
                  </span>
                  <ChevronDown size={14} />
                </Button>
              </DropdownMenuTrigger>
              <DropdownMenuContent
                align="end"
                className="w-64 bg-white  text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 hover:bg-gray-200  dark:bg-[#121212] dark:border dark:border-white/30"
              >
                <DropdownMenuLabel>Select User</DropdownMenuLabel>
                <DropdownMenuSeparator className="dark:bg-white/40" />
                {predefinedUsers.map((Currentuser) => (
                  <DropdownMenuItem
                    key={Currentuser.uid}
                    onClick={() => setUser(Currentuser)}
                    className="flex items-center space-x-3 p-3 cursor-pointer hover:!bg-gray-100 hover:dark:!bg-[#121212] dark:hover:!bg-gray-700"
                  >
                    <Avatar className="w-8 h-8">
                      <AvatarImage
                        src={Currentuser.photoUrl}
                        alt={Currentuser.displayName}
                      />
                      <AvatarFallback className="text-xs">
                        {Currentuser.displayName}
                      </AvatarFallback>
                    </Avatar>
                    <div className="flex-1 min-w-0">
                      <div className="text-sm font-medium text-gray-900 dark:text-white/70">
                        {Currentuser.displayName}
                      </div>
                      <div className="text-xs text-gray-500 dark:text-white/60">
                        {Currentuser.email}
                      </div>
                      <div className="text-xs text-gray-400 dark:text-white/50">
                        User
                      </div>
                    </div>
                    {user?.uid === Currentuser.uid && (
                      <div className="w-2 h-2 bg-blue-600 rounded-full" />
                    )}
                  </DropdownMenuItem>
                ))}
                <DropdownMenuSeparator />
                <DropdownMenuItem className="flex items-center space-x-2 text-blue-600 hover:dark:bg-[#515881] ">
                  <User size={16} />
                  <span className="hover:dark:text-white/70">Manage Users</span>
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
            <div className="max-md:hidden">
              <VeltPresence />
            </div>
            <VeltNotificationsTool darkMode={theme === "dark"} />
          </div>
          <VeltSidebarButton darkMode={theme === "dark"} />
          <VeltCommentsSidebar />

          <ThemeToggleButton />
        </div>
      </div>
    </div>
  );
}

Identifying Users and Documents

components/top-navigation.tsx

Once the provider is in place, Velt needs to know two things: who the current user is and which document they are collaborating on. This is handled using the Velt client.

When a user is selected from the demo user store, the app identifies them with Velt using client.identify(). At the same time, a document context is set using client.setDocuments(). This document acts as the shared collaboration space.

Here’s the core logic that connects users and documents to Velt:

// Handle Velt client initialization, user identification, and document setting
  useEffect(() => {
    if (!client || !user || isInitializingRef.current) {
      console.log("Velt init skipped:", {
        client: !!client,
        user: !!user,
        initializing: isInitializingRef.current,
      });
      return;
    }

    const initializeVelt = async () => {
      isInitializingRef.current = true;
      try {
        // Detect user switch
        const isUserSwitch = prevUserRef.current?.uid !== user.uid;
        prevUserRef.current = user;

        console.log("Starting Velt init for user:", user.uid, { isUserSwitch });

        // Re-identify the user (handles initial and switches)
        const veltUser = {
          userId: user.uid,
          organizationId: "organization_id",
          name: user.displayName,
          email: user.email,
          photoUrl: user.photoUrl,
        };
        await client.identify(veltUser);
        console.log("Velt user identified:", veltUser.userId);
        await client.setDocuments([
          {
            id: "superhuman-velt",
            metadata: { documentName: "superhuman-velt" },
          },
        ]);
        console.log("Velt documents set: superhuman-velt");
      } catch (error) {
        console.error("Error initializing Velt:", error);
      } finally {
        isInitializingRef.current = false;
      }
    };

Inline comments are implemented at the content level inside the email preview. Presence and notifications are handled separately in the header, where a global collaboration context makes more sense.

EmailPreviewComponent.tsx

Using Velt, the email preview component structure looks like this:

"use client";

import { useEditor, EditorContent, BubbleMenu } from "@tiptap/react";
import {
  TiptapVeltComments,
  renderComments,
  addComment,
} from "@veltdev/tiptap-velt-comments";
import { useCommentAnnotations } from "@veltdev/react";
import { useEffect } from "react";
import { StarterKit } from "@tiptap/starter-kit";
import { Button } from "./button";

import { MessageCircle } from "lucide-react";

const EDITOR_ID = "superhuman-demo-email";

const EmailPreviewComponent = ({content=`<p>Data for custom</p>`}:{content?: string}) => {
  // Initialize Tiptap editor
  const editor = useEditor({
    extensions: [
      TiptapVeltComments.configure({
        persistVeltMarks: false,
      }),
      StarterKit,
    ],
    content,
    autofocus: true,
    immediatelyRender: false,
  });

  // Get annotations
  const annotations = useCommentAnnotations();

  // Render annotations when editor and annotations are both ready
  useEffect(() => {
    if (editor && annotations?.length) {
      renderComments({
        editor,
        editorId: EDITOR_ID,
        commentAnnotations: annotations,
      });
    }
  }, [editor, annotations]);

  // Add comment handler - stop propagation to prevent parent elements from capturing events
  const onClickComments = (e: React.MouseEvent) => {
    e.stopPropagation();
    if (editor) {
      addComment({
        editor,
        editorId: EDITOR_ID,
      });
    }
  };

Running and Testing the App

Start the development server by running:

npm run dev

Once the app is running, open http://localhost:3000 in your browser. To test collaboration, open the same URL in two different browser windows or profiles.

Video Demo

Things to Consider Before Production

Before shipping to production, replace the demo user store with your real authentication system so users are identified securely. Use dynamic document IDs instead of a hardcoded value to scope collaboration to individual emails or threads.

Configure permissions and access control to manage who can view, comment, or interact with content. Finally, add proper error handling and monitor collaboration performance as usage scales.

Demo

Check here: https://superhuman-mail-velt.vercel.app/

When exploring the demo, open it in two browser windows, switch between different users, select the same email, and try adding comments to see presence, notifications, and real-time updates in action.

Conclusion

You’ve built a Superhuman-style email interface with real-time collaboration, including inline comments, user presence, and in-app notifications. More importantly, you did this without building or maintaining any custom backend or real-time infrastructure.

Velt handles the heavy lifting behind the scenes, so your code stays focused on the user experience instead of synchronization, events, and edge cases. This makes it much easier to add collaboration to content-driven apps like email, documents, or dashboards.

If you’re building your own SaaS product or internal tool, you can take this further by adding more Velt features such as reactions, read status, mentions, and threaded discussions. These features plug into the same setup and work out of the box.

To explore what else you can build, check out Velt and start adding real-time collaboration to your app without reinventing the backend.

Resources

Building a Zulip Style Collaborative Chat App with Next.js and Velt

Astrodevil — Tue, 05 May 2026 17:43:33 +0000

Zulip is known for keeping conversations organized. Topic-based threads, clear context, and async-friendly discussions make it a favorite for technical and distributed teams. Unlike traditional chat apps, conversations in Zulip stay readable even as teams scale.

Recreating this experience can be a bit difficult. Real-time messaging, user presence, inline comments, and notifications usually require a complex backend and real-time infrastructure.

In this tutorial, we will build a Zulip-style collaborative chat application using Next.js, Tailwind CSS, and Velt. Next.js powers the UI and application structure, while Velt adds collaboration features like presence, comments, and notifications without writing backend code.

By the end, you will have a working chat interface inspired by Zulip, with real-time collaboration built in and ready to extend.

Why Zulip’s Approach Works

Zulip’s design solves a problem most chat tools struggle with: conversations getting messy over time.

Instead of long, linear message streams, Zulip organizes discussions into topics. Each message belongs to a clear context, so conversations stay focused and easy to follow even days or weeks later.

Three ideas make this work especially well:

Real-time collaboration: Messages, comments, and updates appear instantly for everyone in the channel.
Context-rich discussions: Replies stay tied to a specific topic or message, so feedback does not get lost in the noise.
Visible presence: You always know who is online and actively participating, which makes collaboration feel immediate and shared.

What makes this challenging to build in a SaaS product is not the UI, but the infrastructure behind it. Real-time messaging, presence tracking, comments, and notifications typically require WebSockets, backend event systems, data synchronization, and careful handling of concurrent users. Building and maintaining this reliably can take significant engineering effort.

In this tutorial, we recreate Zulip’s collaborative behavior without building that infrastructure ourselves, by using Velt as the collaboration layer.

What We’re Building With

Before we dive into the code, let’s quickly look at the tools we’ll use and why they fit this project well.

Next.js: Next.js gives us a solid foundation for building interactive applications. With the App Router, we get a clean layout structure and client-side interactivity that works well for chat-style interfaces.
React: React handles the UI composition and state updates. The chat interface, message list, and user interactions all rely on simple, predictable React patterns.
Tailwind CSS: Tailwind helps us build a clean and modern UI quickly. It keeps styling close to the components and makes it easy to adjust layouts, spacing, and themes without writing custom CSS.
shadcn ui (powered by Radix UI): These provide accessible, reusable UI primitives like buttons, dropdowns, and avatars. They give us a polished look without locking us into heavy component libraries.
Zustand: Zustand is used for lightweight state management. In this project, it manages demo users and allows us to switch between them to test real-time collaboration.
Velt: Velt is the key piece. Instead of building real-time infrastructure ourselves, Velt provides presence, comments, notifications, and collaboration out of the box. Once integrated, features like reactions, read status, and threaded comments work automatically without writing extra backend or real-time code.

Together, this stack lets us focus on the chat experience and UI, while Velt handles the collaboration layer behind the scenes.

Prerequisites

To follow along with this tutorial, you’ll need:

Node.js (v16 or later) installed on your machine
Basic familiarity with Next.js, React, and TypeScript
A Velt account (you can sign up for free at velt.dev)
Working knowledge of Tailwind CSS fundamentals

You do not need:

Prior experience with Velt
Any backend or database setup
Experience building real-time systems

We’ll walk through the collaboration setup step by step, and the app runs entirely on the frontend.

Project Setup

Instead of scaffolding a new project from scratch, we’ll start from an existing Zulip style chat app that already has the UI and collaboration logic wired up. This lets us focus on understanding how the pieces fit together.

Clone the Repository

Begin by cloning the project and moving into the directory:

gitclone https://github.com/Studio1HQ/zulip-velt
cd zulip-velt

Install Dependencies

Install all required dependencies using npm:

npm install

This will install Next.js, Tailwind CSS, shadcn ui components, Zustand for state management, and the Velt SDK used for collaboration features.

Configure the Velt API Key

Velt requires a public API key to enable collaboration features like presence, comments, and notifications.

Create a .env.local file in the root of the project and add:

NEXT_PUBLIC_VELT_ID=your_velt_api_key_here

You can generate this key from the Velt dashboard after creating a free account.

Once the key is added, restart the development server if it is already running.

Run the App Locally

Start the development server:

npm run dev

Open your browser and visit:

http://localhost:3000

You should now see a Zulip-style chat interface with channels on the left, a message area in the center, and collaboration controls in the header.

At this point, the UI is already functional. In the next sections, we’ll break down how the app is structured and how Velt is integrated to power real-time collaboration without any backend setup.

Project Setup

At a high level, the project is divided into five main parts:

app: Handles routing, layouts, and global configuration using the Next.js App Router
components: Contains all reusable UI and chat-related components
helper: Manages demo user data and user switching logic
hooks: Stores custom React hooks such as theme management
lib: Holds small utility functions used across the app

Let’s take a closer look at the most important folders we’ll work with in this tutorial.

Understanding the App Router and Layout Setup

This project uses the Next.js App Router, which organizes the application using layouts and pages instead of traditional route files. If you are new to the App Router, don’t worry. We’ll focus only on what matters for this app.

The key idea is simple: layouts wrap pages, and this is where we place Velt and theme handling.

In this project, there are two layout files, each with a different responsibility.

layout.tsx is the root layout for the entire application. It defines the HTML structure, metadata, and global styles.

"use client";

import { ThemeProvider } from "@/hooks/use-theme";
import { VeltProvider } from "@veltdev/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_ID || ""}>
      <ThemeProvider>{children}</ThemeProvider>
    </VeltProvider>
  );
}

page.tsx - This file renders the main chat interface. You’ll see it importing layout and chat components and placing them on the page.

"use client"

import { useState, useEffect } from 'react'
import { Header } from '@/components/layout/header'
import { Sidebar } from '@/components/layout/sidebar'
import { ChatArea } from '@/components/chat/chat-area'

export default function Home() {
  const [isSidebarOpen, setIsSidebarOpen] = useState(true)
  const [isSidebarCollapsed, setIsSidebarCollapsed] = useState(false)
  const [isMobile, setIsMobile] = useState(false)

  useEffect(() => {
    const checkMobile = () => {
      const mobile = window.innerWidth < 768
      setIsMobile(mobile)
      if (mobile) {
        setIsSidebarOpen(false)
        setIsSidebarCollapsed(false)
      }
    }

    checkMobile()
    window.addEventListener('resize', checkMobile)
    return () => window.removeEventListener('resize', checkMobile)
  }, [])

  const toggleSidebar = () => {
    if (isMobile) {
      setIsSidebarOpen(!isSidebarOpen)
    } else {
      if (isSidebarCollapsed) {
        setIsSidebarCollapsed(false)
      } else if (isSidebarOpen) {
        setIsSidebarCollapsed(true)
      } else {
        setIsSidebarOpen(true)
      }
    }
  }

  const closeSidebar = () => {
    if (isMobile) {
      setIsSidebarOpen(false)
    }
  }

  return (
    <div className="h-screen flex flex-col bg-background">
      <Header 
        onToggleSidebar={toggleSidebar}
        isSidebarOpen={isSidebarOpen}
        isMobile={isMobile}
      />
      <div className="flex-1 flex overflow-hidden">
        <Sidebar 
          isOpen={isSidebarOpen}
          isCollapsed={isSidebarCollapsed}
          isMobile={isMobile}
          onClose={closeSidebar}
        />
        <ChatArea />
      </div>
    </div>
  )
}

app/layout.tsx is the global shell
app/(app)/layout.tsx is where Velt is initialized
page.tsx is where the chat UI begins
Providers are placed at layout level so all components can access them

Building the Chat Interface with Components

Most of the Zulip-style experience in this app is built using reusable React components. Each part of the interface has a clear responsibility, which makes the code easier to read and extend.

We’ll focus on three areas:

The chat area where messages appear
The message component itself
The layout components that shape the overall UI

Chat Area:

chat-area.tsx - This component is responsible for rendering the list of messages and attaching collaboration features to them.

message.tsx - Each message in the chat is rendered as its own component. This keeps the UI modular and makes it easy to attach collaboration features at the message level.

Layout Components:

The layout of the app is built using two main components: a header and a sidebar.

The sidebar represents Zulip style channels and navigation.
The header is where collaboration controls live.

Inside the header, you’ll see Velt components like:

<VeltPresence />
<VeltNotificationsTool />
<VeltCommentsSidebar />
<VeltSidebarButton />

What these do:

VeltPresence shows who is currently online
VeltNotificationsTool displays collaboration notifications
VeltCommentsSidebar Opens a panel with all comments
VeltSidebarButton toggles the comments sidebar

All of these work automatically once Velt is initialized at the layout level.

import {
  VeltPresence,
  VeltNotificationsTool,
  VeltSidebarButton,
  VeltCommentsSidebar,
  useVeltClient,
} from "@veltdev/react";
import { names, userIds, useUserStore } from "@/helper/userdb";

interface HeaderProps {
  onToggleSidebar: () => void;
  isSidebarOpen: boolean;
  isMobile: boolean;
}

export function Header({
  onToggleSidebar,
  isSidebarOpen,
  isMobile,
}: HeaderProps) {
  const { theme } = useTheme();
  const { user, setUser } = useUserStore();
  const { client } = useVeltClient();
  const prevUserRef = useRef(user);
  const isInitializingRef = useRef(false); // Prevent overlapping initialization calls

Client Initialization, User Identification, and Document Setting

 // Handle Velt client initialization, user identification, and document setting
  useEffect(() => {
    if (!client || !user || isInitializingRef.current) {
      console.log("Velt init skipped:", {
        client: !!client,
        user: !!user,
        initializing: isInitializingRef.current,
      });
      return;
    }

    const initializeVelt = async () => {
      isInitializingRef.current = true;
      try {
        // Detect user switch
        const isUserSwitch = prevUserRef.current?.uid !== user.uid;
        prevUserRef.current = user;

        console.log("Starting Velt init for user:", user.uid, { isUserSwitch });

        // Re-identify the user (handles initial and switches)
        const veltUser = {
          userId: user.uid,
          organizationId: "organization_id",
          name: user.displayName,
          email: user.email,
          photoUrl: user.photoUrl,
        };
        await client.identify(veltUser);
        console.log("Velt user identified:", veltUser.userId);
        await client.setDocuments([
          {
            id: "zulip-velt",
            metadata: { documentName: "zulip-velt" },
          },
        ]);
        console.log("Velt documents set: zulip-velt");
      } catch (error) {
        console.error("Error initializing Velt:", error);
      } finally {
        isInitializingRef.current = false;
      }
    };

    initializeVelt();
  }, [client, user]); // Re-run on client or user change

Reusable UI Components

To keep the chat interface clean and consistent, this project uses a set of reusable UI components. These components handle common UI patterns like buttons, inputs, avatars, and scroll areas.

Instead of building these from scratch, the project uses shadcn ui, which is a collection of accessible, unstyled components built on top of Radix UI. This approach gives us flexibility while keeping the UI consistent.

All reusable UI components live inside the components/ui folder.

Reusable UI primitives: Shared building blocks like buttons, inputs, avatars, and dropdowns used across the app to keep styling consistent.
Built with shadcn ui (powered by Radix UI): Accessible, unstyled components that provide behavior and keyboard support without locking the design.
Scroll handling for chat: The ScrollArea component manages smooth scrolling for long message lists in the chat view.
Separation of concerns: UI components handle appearance and interaction, while chat and layout components focus on structure and logic.
Easy to extend and customize: Updating a UI component in this folder automatically updates its usage across the entire app.

User Management for Collaboration Testing

To test real-time collaboration features like presence, comments, and notifications, we need a way to simulate multiple users. Instead of setting up a full authentication system, this project uses a simple and beginner-friendly approach with predefined users.

User state is managed using Zustand, a lightweight state management library.

import { create } from "zustand";
import { persist } from "zustand/middleware";

export type User = {
  uid: string;
  displayName: string;
  email: string;
  photoUrl?: string;
};

export interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
}

export const userIds = ["user001", "user002"];
export const names = ["Nany", "Mary"];

export const useUserStore = create<UserStore>()(
  persist(
    (set) => ({
      user: null,
      setUser: (user) => set({ user }),
    }),
    {
      name: "user-storage",
    }
  )
);

Theme Management with `useTheme`

Modern apps usually support both light and dark themes, and this project follows the same pattern. Theme state is managed using a custom React hook, which keeps the logic reusable and easy to maintain.

The theme logic lives inside a single file.

The theme is:

Stored in React state
Loaded from localStorage on page load
Saved back to localStorage when changed

This ensures the user’s theme preference persists across page refreshes.

Syncing Theme with Velt

The theme value is also passed to Velt components, allowing them to automatically switch between light and dark modes.

This means:

The app UI and Velt UI stay visually consistent
No extra styling logic is required for collaboration components
Once the hook is set up, theme changes propagate everywhere.

Utility Functions

The lib folder contains small helper utilities that are shared across the application. In this project, it mainly exists to support reusable UI components and keep common logic out of individual files. The utilities in this file are primarily related to class name handling. When working with Tailwind CSS and reusable components, it’s common to conditionally apply multiple class names.

Running the App and Testing the Output

Now that we’ve walked through the project structure and key files, it’s time to run the app and verify that everything works as expected.

Seeing the app in action makes the collaboration features easier to understand in the next sections.

From the project root, run:

npm run dev

Once the server starts, open your browser and navigate to:

http://localhost:3000

You should see a Zulip style chat interface with:

A sidebar for channels
A header with user controls
A central chat area for messages

To test collaboration features, open the app in two browser windows or one normal window and one incognito window.

Use the user switcher in the header to change between demo users such as Nany and Mary.

Each window should represent a different user.

Try the following actions:

Presence: Notice user avatars appear in the header when multiple users are online.
Comments: Hover over a message and add a comment. The comment should appear instantly in both windows.
Notifications: Add a comment in one window and check the notification bell in the other.
Theme Switching: Toggle between light and dark mode and observe that both the app and Velt components update correctly.

How It Works

Here’s a simple view of what happens when the app runs:

The app loads and initializes Velt using the API key in the layout
A demo user is selected using the Zustand store
Velt identifies the active user and associates them with the app
A shared document context is set for collaboration
Messages render in the chat area
Comments, presence, and notifications are automatically tracked by Velt
Updates sync instantly across all connected clients

The key idea is that the app focuses on UI and user flow, while Velt handles real-time synchronization and collaboration logic.

Collaborative Features You Get Automatically

Once Velt is integrated, collaboration features start working without writing additional backend or real-time code.

These features are available out of the box:

Inline comments: Add comments directly on chat messages and view them in context.
User presence: See who is currently online and active in the chat.
Notifications: Get notified when someone comments or interacts.
Reactions and comment status: React to comments and mark them as resolved or active.
Read awareness: See when comments have been viewed by other users.

All of these features work automatically once Velt is set up.

Things to Note Before Shipping to Production

Before using this setup in a real product, keep the following in mind:

Replace demo users with a real authentication system
Identify users using real user IDs and metadata
Use dynamic document IDs instead of a hardcoded value
Add permissions to control who can view or comment
Handle error states when collaboration services are unavailable
Review Velt customization options to match your product UI
Test performance with multiple concurrent users

These steps ensure the app scales safely beyond a demo environment.

Demo Video

You can see the completed Zulip style chat app with real-time collaboration in action here:

Live Demo:

https://zulip-velt-chat.vercel.app/

This demo shows user switching, comments, presence, notifications, and theme support working together.

Conclusion

Zulip demonstrates how powerful chat can be when collaboration is built into the experience. Organized conversations, clear context, and real-time awareness turn chat from simple messaging into a system teams can rely on.

For builders, the real challenge is not the UI. It is the collaboration layer behind it. Features like real-time sync, presence tracking, inline comments, notifications, and reactions usually require complex infrastructure and long development cycles. This is especially true when building a chat-based SaaS product.

In this tutorial, we focused on that exact problem. Instead of rebuilding collaboration from scratch, we showed how to add Zulip-style collaborative features inside a chat application using Next.js and a modern frontend stack, while delegating the hard real-time problems to Velt.

The result is a working chat app where collaboration feels native, but the code stays simple and frontend-focused.

Key Takeaways

Clean component structure makes complex apps easier to understand
Collaboration does not need custom real-time infrastructure
Velt enables comments, presence, notifications, and more out of the box
Frontend-focused development speeds up experimentation and iteration

If you are building a chat app, internal tool, or collaborative product, Velt lets you focus on your core experience instead of infrastructure.

Try building with Velt and add collaboration to your app in minutes at velt.dev.

How to Build Canva-Like Collaboration with Velt AI Plugin & Fabric.js

Astrodevil — Wed, 15 Apr 2026 15:57:07 +0000

Introduction

Design tools make collaboration hard in a specific way. Every action is about positioning, objects moving, resizing, stacking on top of each other, and when two people do that at the same time on the same canvas, one person's change will quietly overwrite the other's if nothing is managing the conflict.

We built PixFrame, a Canva-like design editor, to see what that looks like in practice. This article explains how the collaboration layer is built, including CRDT sync, live cursors, presence, and comments. We used Velt for the collaboration layer and the Velt Plugin to set it up quickly.

Here is the final result.

This article walks through how the editor is built, how Velt connects to a Fabric.js canvas, and what the Plugin workflow actually looked like.

The Stack

React + Vite: app framework and dev server
**Fabric.js:** canvas engine; handles the object model, transforms, serialization, and everything that makes a design editor feel like a design editor
Zustand: global editor state: layers, undo/redo history, active panel, theme, export settings
Velt: the entire collaboration layer: CRDT sync, live cursors, presence, comments, and notifications
Tailwind CSS: styling
TypeScript: type safety across the canvas and collaboration logic

For the Velt side, I used the Velt Plugin throughout the build. It bundles the MCP server, Agent Skills, and a velt-expert agent persona in one install, so instead of reading through setup docs and manually wiring providers, the agent handled it. Collaboration features that would have required a day or two of SDK work were reduced to a few slash commands.

Get It Running

Clone the repo and drop your Velt API key in a .env file.

git clone https://github.com/Studio1HQ/Canva-style-design-editor-UI
cd Canva-style-design-editor-UI
npm install

VITE_VELT_API_KEY=your_velt_api_key

Run npm run dev and open http://localhost:5173. Get your API key from the Velt dashboard. Now, the rest of the article walks through how the collaboration layer is wired into the editor via the Velt plugin and related components.

How We Added Collaboration

There are two ways to set up Velt, depending on your editor.

On Cursor or Claude Code: install the Velt Plugin. It ships with everything already bundled: MCP server, Agent Skills, rules, and a velt-expert agent persona. Slash commands like /install-velt, /add-comments, and /add-presence show up directly in the editor. One install, nothing else to configure.

On any other editor, the Plugin is not available, so you set up the two pieces it bundles separately. Add the Velt MCP server to feed live Velt API references into your agent's context, and install Agent Skills so the agent knows how to generate correct Velt code for setup, comments, CRDT, and notifications:

npx skills add velt-js/agent-skills
npx -y @velt-js/mcp-installer

Restart the editor, then open your agent chat and type install velt. The agent asks about your project structure, API key location, and which features you need, then generates a plan, shows you a diff, and applies it on approval.

We were on Cursor, so we used the Plugin and ran /install-velt directly in the editor.

Wiring Velt Into the App

Running /install-velt is what generated everything below. The agent scanned the project, detected the component structure, and placed VeltProvider at the root, outside FabricProvider , so the collaboration layer is available across the entire tree before the canvas mounts:

<VeltProvider apiKey={apiKey}>
  <FabricProvider>
    <AppContent currentUser={currentUser} onSwitchUser={handleSwitchUser} />
  </FabricProvider>
</VeltProvider>

Inside AppContent, the agent set up user identification and document context in sequence:

await client.identify(currentUser);
await client.setDocument("pixframe-collaborative-canvas", {
  documentName: "Pixframe Design",
});

identify has to be completed before setDocument runs. identify runs first because Velt needs to know who the user is before it can tie them to a document. If setDocument runs before identify completes, Velt cannot associate the session with the correct user, and collaboration does not attach properly, even if the canvas loads fine.

The demo runs two hardcoded users with a switcher in the top bar. For real auth, replace currentUser with whatever your auth provider returns. Nothing else changes.

How the Canvas Stays in Sync

With the provider set up and users identified, the next question is how canvas changes from one user to reach everyone else. This section covers the CRDT layer that makes that possible, the hook that connects it to Fabric, and the guard that keeps the whole thing from looping back on itself.

What CRDT Means Here

When two users edit the same canvas simultaneously, a mechanism must determine the final state. Without a conflict resolution strategy, one edit silently overwrites the other, and neither user knows it happened.

Velt's CRDT layer handles this internally using Yjs. Every change is recorded as an operation, not a full replacement, so edits from different users merge without one cancelling the other. For libraries such as ReactFlow and SlateJS, Velt offers prebuilt CRDT integrations. Fabric.js is not one of them, so we used Velt's CRDT Core, which gives direct access to the underlying Yjs store without being tied to any specific library.

The Hook That Connects Fabric to Velt

For Velt CRDT integration, we ran /add-crdt in Cursor. The agent detected we were using Fabric, reached for Velt's CRDT Core since there was no prebuilt integration for it, and generated src/hooks/useCollaborativeEditor.ts as the bridge between the canvas and the CRDT store.

The hook sets up a single shared store for the entire canvas state:

const { value, update } = useVeltCrdtStore<string>({
  id: "pixframe-canvas-state",
  type: "text",
  initialValue: "",
  enablePresence: false,
});

type: "text" gives a full replacement store backed by Y.Text. Every snapshot, the serialized Fabric JSON, the layer list, and the canvas dimensions, get stringified and pushed into it as one blob.

Pushing local changes

Every canvas mutation calls pushCanvasState, which is debounced at 150ms. This means rapid, continuous actions like dragging an object only push one update instead of one per frame:

const pushCanvasState = useCallback((canvasJson: string) => {
  if (isRemoteUpdate.current) return;
  if (debounceRef.current) clearTimeout(debounceRef.current);
  debounceRef.current = setTimeout(() => {
    const state = useEditorStore.getState();
    const snapshot = JSON.stringify({
      json: canvasJson,
      layers: JSON.stringify(state.layers),
      canvasSize: state.canvasSize,
    });
    lastPushedRef.current = snapshot;
    update(snapshot);
  }, 150);
}, [update, isRemoteUpdate]);

For discrete actions like delete or layer visibility toggle, there is a separate pushCanvasStateImmediate that skips the debounce entirely and cancels any pending debounced push, because those changes need to land in the CRDT store right away.

Both functions share one thing in common: the first line of each checks isRemoteUpdate.current before doing anything else.

Why `isRemoteUpdate` exists

When the CRDT store delivers a remote snapshot, the hook calls canvas.loadFromJSON to apply it. That triggers Fabric's own change events, the same ones that call pushCanvasState. Without any blocking, the hook would push the remote state back out as a local edit, triggering another snapshot on every peer and firing events again. The loop runs until something breaks.

isRemoteUpdate is a ref that gets set to true before any remote snapshot is applied. Every push function checks it at the top and returns early if it is true:

const pushCanvasState = useCallback((canvasJson: string) => {
  if (isRemoteUpdate.current) return;
  // rest of push logic
}, [update, isRemoteUpdate]);

The flag clears two animation frames after loadFromJSON completes, not immediately. The setLayers call inside applySnapshot triggers a React effect in CanvasArea on the next render. If the flag cleared too early, that effect would see it as false and try to purge objects that were just loaded from the snapshot. The two-frame delay keeps it alive long enough for that effect to bail out correctly.

The Collaboration Layer

With the CRDT sync in place, the next step was adding the visible collaboration features: cursors, comments, presence, and notifications. Each one came from a single slash command in Cursor using the Velt Plugin, /add-cursors, /add-comments, /add-presence, /add-notifications. No manual component wiring, no reading through setup docs for each feature individually.

Live Cursors

VeltCursor is inside CanvasArea, wrapped in an absolutely positioned overlay:

<div className="absolute inset-0 pointer-events-none z-[150]">
  <VeltCursor />
</div>

Placing it here means the cursor tracks within the canvas boundary. If it were at the root, cursor positions would be relative to the full page layout, including the sidebars and toolbar, which would make them inaccurate for anyone working on the canvas.

Comments

VeltComments and VeltCommentsSidebar sit at the app root in App.tsx so comment pins can appear anywhere across the full editor surface, not just over the canvas.

Both have shadowDom={false}:

<VeltComments shadowDom={false} />
<VeltCommentsSidebar shadowDom={false} />

Velt components use Shadow DOM by default, which isolates them from your global CSS. Turning it off is what makes theming work. Once it is off, generate your token set from Velt's theme playground and paste it into your global CSS:

body {
  --velt-light-mode-accent: #6366f1;
  --velt-light-mode-background-0: #ffffff;
  --velt-dark-mode-accent: #6366f1;
  --velt-dark-mode-background-0: #111114;
}

Dark mode stays in sync by calling client.setDarkMode(theme === "dark") whenever the app theme changes. That single call covers all Velt components.

Presence and Notifications

VeltPresence and VeltNotificationsTool both sit in TopBar, inside VeltProvider:

<VeltPresence />
<VeltNotificationsTool />

VeltPresence renders the avatar stack for everyone currently on the document. VeltNotificationsTool shows a bell with a badge that updates on new comments, replies, and mentions.

The CRDT hook handles pushing and applying snapshots, but with Fabric.js, a specific issue makes the wiring less straightforward than it appears.

The Fabric–Velt Bridge

The collaboration layer in the previous section assumes that the hook can distinguish between a local canvas change and a remote change being applied. With Fabric, that assumption does not hold by default.

Fabric fires object:modified, object:added, and object:removed for every canvas change, whether it came from the local user or from loadFromJSON applying a remote snapshot. There is no built-in way to distinguish them.

Without a guard: a remote snapshot arrives, the hook calls loadFromJSON, Fabric fires object:added for each restored object, those events call pushCanvasState, which pushes the remote state back into the CRDT store as a local edit, which triggers another snapshot on every peer. The loop runs until something breaks.

isRemoteUpdate is the guard. It is a ref, not state, because a re-render mid-snapshot would cause more problems than it solves. It flips to true before loadFromJSON runs, and every push function checks it first:

const pushCanvasState = useCallback((canvasJson: string) => {
  if (isRemoteUpdate.current) return;
  // rest of push logic
}, [update, isRemoteUpdate]);

It clears two animation frames after loadFromJSON completes, not immediately. The setLayers call inside applySnapshot triggers a React effect in CanvasArea on the next render. Clearing the flag too early causes the effect to be treated as false and to purge objects that were just loaded. The two-frame delay keeps it alive long enough.

The Bug That Broke Collaboration on Remote Peers

The echo loop was resolved, but a second issue only appeared when a second user joined.

After receiving and applying a snapshot, clicking any canvas object selected nothing. The layers panel went blank. Delete, visibility toggle, crop, all dead. Everything looked fine visually, but the editor was frozen for anyone who joined second.

The root cause was a Fabric 7 quirk. canvas.toJSON(['data']) ignores the propertiesToInclude argument and calls this.toObject() with no arguments internally. The custom data field, which holds each object's id and links canvas objects to Zustand layers, was never included in any snapshot. Every object in every CRDT snapshot had data: undefined.

When the remote peer loaded that snapshot, no object had a data.id. Clicking them set selectedLayerId to null. Every panel check found nothing.

The fix was one line:

// Before — data.id silently dropped
const json = JSON.stringify(canvas.toJSON(['data']));

// After — data.id correctly included
const json = JSON.stringify(canvas.toObject(['data']));

canvas.toObject(['data']) respects propertiesToInclude. canvas.toJSON does not, despite the identical signature. This only surfaces with a second user because the originating peer keeps object references in memory and never depends on the serialized data.id.

The full pattern: push on local mutation, apply on remote value, guard with a ref, and serialize with toObject not toJSON.

What's Next

The full source is on GitHub. Clone it, run it, and the collaboration layer is live from the first load.

A few things worth building on top of this:

Multi-page support: each page as a separate Velt document, with presence scoped per page
PDF export: serialize the canvas per page and pipe it through a headless renderer
Template library: save any canvas state as a named template and load it into a fresh document

The CRDT layer is already there. Most of these are additive, new UI and a document structure change, nothing that touches the sync logic.

How to Build Self-Healing AI Agents with Monocle, Okahu MCP and OpenCode

Astrodevil — Wed, 08 Apr 2026 22:04:48 +0000

Coding agents write code. When that code fails, who debugs it? Right now, that's still you. The agent writes, you interpret error logs, you prompt the agent to fix. The debugging loop stays open.

The fix is giving agents access to their own telemetry. An agent that can query its own traces can verify its work, diagnose failures, and iterate without waiting for a human to read logs.

This tutorial shows you how to build a self-healing agent that runs tests, queries its own production traces via MCP, identifies root causes, and fixes bugs without human intervention.

By the end, you'll have a working demo where:

A buggy Text-to-SQL application fails its test suite
An agent queries its own traces from Okahu Cloud via MCP
The agent identifies and fixes bugs based on trace analysis
All tests pass, without a human reading logs or prompting fixes

What we'll cover:

What is Monocle and why auto-instrumentation matters
What is Okahu MCP and how agents consume telemetry
Setting up the self-healing demo environment
Running the agent and watching it fix itself
Key takeaways for building autonomous debugging loops

Let's start by understanding the two core technologies that make this possible.

What is Monocle?

In traditional software, you read the source code to understand what the application does. The logic is deterministic and inspectable. In agent-driven applications, the code is scaffolding. The actual decision-making happens inside the model at runtime.

An agent that can't access traces is an agent working without documentation. It will guess where failures occur and propose changes based on incomplete information.

Monocle helps developers and platform engineers building or managing generative AI apps monitor these in prod by making it easy to instrument their code to capture traces that are compliant with open-source cloud-native observability ecosystem. It automatically captures traces from LLM SDKs like OpenAI, LangChain, and LlamaIndex without any manual span creation.

Agents won't manually add telemetry to their generated code. If instrumentation requires effort, it won't happen. Monocle solves this by auto-instrumenting supported SDKs the moment they're used.

Here's what it takes to enable automatic trace capture:

from monocle_apptrace import setup_monocle_telemetry

# One line to enable automatic trace capture
setup_monocle_telemetry(workflow_name="text_to_sql_analyst")

That's it. From this point forward, every OpenAI SDK call, every database query, every tool invocation is captured as a trace span.

These traces include:

LLM calls: Inputs, outputs, model name, token usage
App traces: OpenTelemetry compatible for exporting traces/spans from an application.
Tool invocations: Agent framework tool calls and responses
Errors and latency: Exception details and timing data

When something goes wrong, the trace contains everything an agent needs to diagnose the problem. The question is: how does the agent access that trace data?

Zero-config instrumentation using monocle

It is also worthy to note that Monocle does not depend on existing OpenTelemetry instrumentation.

What is Okahu MCP?

Okahu is a cloud observability platform built for AI applications. It ingests traces from Monocle, stores them, and provides dashboards for visualization.

Dashboards are designed for human eyes. They're full of charts, graphs, and interactive trace viewers. An agent can't click through a dashboard. The data exists, but agents can't access it.

**MCP (Model Context Protocol)** is a standard for exposing data sources to AI agents. Okahu MCP turns the observability platform into a programmable API that agents can query directly. Instead of a human clicking through a dashboard, an agent calls /okahu:get_latest_traces and parses the JSON response.

Observability platforms must evolve from human dashboards to programmatic interfaces that agents can consume. MCP is how that happens.

To connect an agent to Okahu MCP, add this configuration:

{
 "mcp": {
  "okahu": {
   "type": "remote",
   "url": "https://mcp.okahu.ai/mcp",
   "headers": {
    "x-api-key": "your-okahu-api-key"
   },
   "enabled": true
  }
 }
}

Now the agent can query its own traces. It sees the same data a human would see in the dashboard, but in a format it can parse, reason about, and act on. Make sure you authenticate the server by running these command:

opencode mcp auth okahu

This will generate a URL and will redirect you to authenticate with Okahu cloud and a successful authentication will show a screen like the one below:

With Monocle capturing traces and Okahu MCP exposing them, we have the infrastructure for self-healing.

Prerequisites

Before starting, make sure you have the following:

Python 3.10+ installed on your system
OpenAI API key for LLM calls (the demo uses GPT-4o)
Okahu API key for trace storage (sign up at okahu.ai)
OpenCode or a similar coding agent with MCP support

Once you have these ready, let's clone the demo repository and set up the environment.

Step 1: Clone and Set Up the Demo

Start by cloning the demo repository and creating a virtual environment:

git clone https://github.com/Arindam200/awesome-ai-apps
cd mcp_ai_agents/telemetry-mcp-okahu

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install monocle_apptrace monocle_test_tools openai fastapi pytest python-dotenv

Next, create a .env file with your API keys:

# .env
OPENAI_API_KEY="your-openai-key"
OPENAI_MODEL="gpt-4o"
OKAHU_API_KEY="your-okahu-key"
MONOCLE_EXPORTER="okahu"

The MONOCLE_EXPORTER=okahu setting tells Monocle to send traces to Okahu Cloud instead of logging them locally. This is important because we're suppressing all local logs to force the agent to use MCP for debugging.

Finally, initialize the sample database:

python setup_db.py

This creates a sales.db SQLite database with users and orders tables. The Text-to-SQL application will generate queries against this database.

Now let's look at what makes this demo interesting: the intentionally buggy application.

Step 2: Understand the Buggy Application

The demo includes a pre-built analyst.py with three intentional bugs. Each bug produces a specific trace signature that the agent must find and interpret:

Bug	What's Wrong	What the Trace Shows
1	Uses `client.completions.create()` instead of `client.chat.completions.create()`	API error: "NotFoundError: /v1/completions not found for gpt-4o"
2	Accesses `.text` instead of `.message.content` on the response	AttributeError in trace span
3	Schema prompt says `customers/products` but DB has `users/orders`	SQL execution error: "no such table: customers"

Why pre-built bugs instead of letting the agent write code from scratch? Two reasons:

Reproducibility: Every demo run starts with the same failures
No guessing: The agent must read traces to understand what's wrong

You can reset to the buggy state anytime with:

python reset_demo.py

This script overwrites analyst.py with the buggy version, ready for the agent to fix.

With the buggy application in place, let's run the tests and see it fail.

Step 3: Run Tests and See Failures

The test suite uses Monocle Test Tools to validate not just outputs, but traces. We're testing that the right LLM calls were made, not just that the code ran.

Here is what the test_analyst.py file looks like and what it tests:

@MonocleValidator().monocle_testcase(sql_generation_test_cases)
def test_generate_sql_with_monocle(my_test_case: TestCase):
    """
    Test SQL generation using Monocle validator.

    This validates:
    - OpenAI inference spans are generated correctly
    - SQL output matches expected patterns (similarity check)

    If this fails, check Okahu MCP traces for:
    - Missing inference spans (wrong API method used)
    - Incorrect SQL generation (schema mismatch)
    """
    MonocleValidator().test_workflow(generate_sql, my_test_case)

# Direct database tests (no monocle validation needed - these test the DB itself)
def test_execute_query_users_table():
    """
    Test direct SQL execution on the actual database.
    This verifies the users table exists and has data.
    """
    sql = "SELECT * FROM users LIMIT 3"
    results = execute_query(sql)

    assert len(results) == 3, "Should return 3 users"
    # Verify column structure: (user_id, username, email)
    assert len(results[0]) == 3, "Each user row should have 3 columns"

def test_execute_query_orders_table():
    """
    Test direct SQL execution on orders table.
    This verifies the orders table exists and has data.
    """
    sql = "SELECT * FROM orders WHERE amount > 100 LIMIT 5"
    results = execute_query(sql)

    assert len(results) > 0, "Should find orders over $100"
    # Verify column structure: (order_id, user_id, amount, order_date)
    assert len(results[0]) == 4, "Each order row should have 4 columns"

Run the tests:

pytest test_analyst.py -v

You'll see output like this:

The direct database tests pass (the database itself is fine), but the LLM-powered SQL generation fails.

Here's what makes this demo realistic: there are no useful local logs. We've suppressed all local logging:

import logging
logging.disable(logging.CRITICAL)

The agent cannot read local logs to debug. It must query Okahu MCP to understand what went wrong. This forces the self-healing loop through observability infrastructure, exactly how it would work in production.

The trace shows exactly what went wrong. The agent queries this via MCP

The trace shows exactly what went wrong. The agent queries this via MCP

Step 4: Configure the Self-Healing Agent

The demo uses an OpenCode agent mode called @analyst_v3. This is a custom agent configuration stored in .opencode/agents/analyst_v3.md with specific rules for self-healing behavior.

Tool access alone isn't enough. The agent needs structured rules that encode how an experienced developer would debug.

Here are the summary of the core rules:

**Self-Healing Rules:**

1. Run tests first, observe failures
2. Wait 5 seconds for trace ingestion
3. Query Okahu MCP: `/okahu:get_latest_traces` with workflow_name='text_to_sql_analyst_v3'
4. Fix bugs based on trace analysis only
5. Archive old code to `versions/analyst_vN.py` before each fix
6. Record the trace ID used to diagnose each fix
7. Repeat until all tests pass

**Critical Constraint:**
NO GUESSING. If no traces are available, STOP and report failure.
Do not attempt to fix code without trace evidence.

The "no guessing" rule is the key constraint. Without it, the agent might make up fixes based on general knowledge. By requiring trace evidence, every fix must be grounded in telemetry. The agent can cite its sources.

The agent also has a list of approved packages it can install if missing:

monocle_apptrace, monocle_test_tools, openai, fastapi, pytest, python-dotenv

If it encounters a ModuleNotFoundError, it can install from this list, but nothing else.

With the agent configured, let's trigger the self-healing loop.

Step 5: Run the Self-Healing Loop

With traces accessible via MCP, the agent can close the loop itself. It runs, fails, queries traces, diagnoses, fixes, and repeats.

Trigger the agent with this prompt:

@analyst_v3 Fix the buggy Text-to-SQL codebase:

The `analyst.py`, `test_analyst.py`, and `main.py` files already exist but have bugs.

1. Run Tests: Execute `pytest test_analyst.py -v` to see failures.
2. Analyze Traces: Wait 5s, then query Okahu MCP with workflow_name='text_to_sql_analyst_v3'.
3. Fix Loop:
    - Archive current `analyst.py` to `versions/analyst_vN.py`
    - Fix the bug based on trace analysis
    - Record the trace ID used to diagnose each fix
    - Run tests again
    - Repeat until all tests pass
4. Final Report: Output a summary table of all issues fixed with their associated trace IDs.

Rules: No debug files. Debug only via Okahu MCP traces. Always call the MCP tool to get the logs from traces, do not use the local logs in the terminal

Here's what happens, completely autonomously:

Agent runs tests → 3 failures detected
Agent waits 5 seconds → Allows traces to be ingested into Okahu
Agent queries Okahu MCP → Retrieves trace data for the failed runs
Agent reads the first trace → Sees "NotFoundError: /v1/completions not found for gpt-4o"
Agent archives analyst.py → Saves to versions/analyst_v1.py
Agent fixes Bug #1 → Changes completions.create() to chat.completions.create()
Agent runs tests → 2 failures remain
Agent queries MCP again → Sees AttributeError for .text access
Agent fixes Bug #2 → Changes .text to .message.content
Agent runs tests → 1 failure remains
Agent queries MCP → Sees "no such table: customers"
Agent fixes Bug #3 → Updates schema in prompt from customers/products to users/orders
Agent runs tests → All 5 tests pass

Agent runs, fails, queries traces, fixes, repeats until all tests pass.

The entire loop runs without human intervention. The agent reads, reasons, and repairs using only its own telemetry.

Step 6: The Fix Summary

The agent produces a traceable summary. Every fix links to the trace that prompted it:

Issue	Description	Trace ID
1	Wrong OpenAI API (completions → chat.completions)	trace_a1b2c3d4...
2	Wrong response attribute (.text → .message.content)	trace_e5f6g7h8...
3	Schema mismatch (customers/products → users/orders)	trace_i9j0k1l2...

You can take any trace ID, look it up in Okahu, and see exactly what error led to that fix. The human's role shifts from doing the debugging to auditing the system that did the debugging.

The archived versions in versions/ show the progression:

analyst_v1.py: Original buggy version
analyst_v2.py: After fixing API method
analyst_v3.py: After fixing response attribute
analyst.py: Final working version

The human wasn't in the debugging loop. The human set up the environment, triggered the agent, and reviewed the summary. The debugging itself was autonomous.

OpenCode agent running test, using monocle traces on Okahu via MCP to debug and fix the buggy app

Key Takeaways

Here's what we've shown and why it matters:

1. Auto-instrumentation is essential for self-healing

Agents won't manually add telemetry to their generated code. If you want agents to debug their own work, instrumentation must be automatic. Monocle captures traces from supported SDKs with a single line of setup.

2. MCP enables agent-native observability

Dashboards are designed for humans. MCP turns observability platforms into programmable APIs that agents can query. Okahu MCP exposes the same trace data a human would see, but in a format agents can parse and act on.

3. "No Trace, No Fix" prevents hallucinated fixes

Without grounding in telemetry, agents might guess at fixes based on general knowledge. The "no trace, no fix" rule ensures every repair is evidence-based. If the agent can't find trace data, it stops and reports the issue rather than guessing.

4. Trace-based testing validates the full pipeline

Monocle Test Tools doesn't just check that code runs. It validates that the right traces exist. If the LLM wasn't called correctly, the inference span won't exist, and the test fails. This catches issues that output-only testing would miss.

5. Human role shifts from debugging to monitoring

The human sets up the environment, triggers the agent, and reviews the fix summary. The iterative debugging loop (run, fail, diagnose, fix, repeat) is fully autonomous. This is a fundamental shift in how we build and maintain AI applications.

The Evolution: Who Consumes Telemetry?

This demo represents a real shift in how software gets built:

Phase	Who Writes Code	Who Reads Telemetry	Human Role
Software 1.0	Human	Human	Everything
Software 2.0	Coding Agent	Human	Prompts + interprets errors
Autonomous	Coding Agent	Coding Agent	Monitors only

Who consumes telemetry data?

In Software 1.0, humans wrote code, read dashboards, and fixed bugs. In Software 2.0, agents write code, but humans still interpret errors and prompt fixes. The agent is the "hands," but the human remains the "brain."

In the autonomous phase, which is what this demo shows, the agent writes, runs, debugs, and fixes. The human monitors the process and reviews outcomes. The agent consumes its own telemetry.

The lesson from every team that has pushed agents toward autonomy is the same: the critical work is never writing code. It's designing the environment, encoding constraints, structuring knowledge, and building feedback loops. As human involvement decreases, the systems that steer and verify agent behavior must become more robust, not less.

This requires a shift in how we build observability platforms. Dashboards aren't enough. Platforms must expose MCP interfaces that agents can query programmatically. The data is the same; the consumer is different.

Conclusion

Self-healing agents are possible when three conditions are met:

Instrumentation is automatic: Monocle captures traces without manual span creation
Telemetry is programmatically accessible: Okahu MCP exposes traces as an API
Testing validates traces, not just outputs: Monocle Test Tools ensures the right calls were made

The result is a coding agent that can debug its own code by querying production telemetry. It runs tests, reads traces, identifies root causes, and applies fixes, closing the loop without human intervention.

The organizations that invest early in giving agents access to telemetry, embedding evaluation into workflows, and exposing programmatic observability interfaces will scale agent-driven development effectively. Those that don't will find their agents operating blind, producing code that looks correct but behaves unpredictably.

The question is no longer "who writes the code?" It's "who consumes the telemetry?" When agents can do both, the loop closes, and we've entered a new phase of software engineering.

Resources

Monocle: pip install monocle_apptrace | GitHub
Monocle Test Tools: pip install monocle_test_tools | Trace-based validation framework
Okahu Cloud: okahu.ai | AI observability platform with MCP support
Demo Repository: GitHub | Full source code for this tutorial
OpenCode: Install here

This article demonstrates a proof-of-concept for autonomous agent debugging. The patterns shown here (auto-instrumentation, MCP-based telemetry access, and trace-driven testing) are the building blocks for self-healing AI systems.

Build Collaborative AI Whiteboard Like Mural Using Velt Agent Skills and MiniMax🔥

Astrodevil — Tue, 07 Apr 2026 16:13:20 +0000

Introduction

Building a real-time collaborative canvas is harder than it looks. The interface seems simple enough, boxes, lines, and cursors moving around. But underneath it is a constant stream of concurrent edits, conflicting updates, and shared state that has to stay consistent for everyone at the same time. The hard part is not drawing on the canvas. It is making sure multiple people can work on the same board simultaneously without things breaking quietly in the background.

In this article, we will build a collaborative whiteboard using Velt that supports shared editing, live presence, comments, and AI-assisted interactions all inside the same canvas. The focus is not just on rendering nodes but on wiring the system in a way that keeps every user in sync without adding friction to the experience.

Here is what the final result looks like.

Now let's look at the stack behind it and how each piece fits together.

The Stack

Next.js for the app framework
ReactFlow for the infinite canvas and custom node types
Velt for CRDT sync, live cursors, presence, comments, and notifications
MiniMax M2.5 for the AI features
Tailwind CSS & Shadcn for styling and dark mode
Zustand for state management

I used Velt Docs MCP and Skills throughout the build. The MCP server pulls Velt's API references directly into your editor context, and Skills are pre-built prompt templates that tell the agent exactly how to set up features like presence, comments, and notifications. Adding collaborative features that would have taken a couple of days ended up taking a few prompts with Skills and Velt Docs MCP.

For the editor side, I paired with GitHub Copilot Agent inside VS Code, it cut down the back-and-forth that usually comes with integrating a new SDK. If you haven't tried the Copilot Agent yet, it's worth a look. It takes multi-step actions in the editor rather than just completing code at the cursor, which works well for integration-heavy projects like this one.

How CRDT Makes This Work

The stack above gives you the canvas and the AI, but collaboration only works if multiple users can edit the same board without stepping on each other. This is handled through Velt’s CRDT-based sync.

CRDT records every change as an operation rather than a replacement, so edits from different users merge naturally, and the document keeps moving forward. Velt builds on Yjs and manages this layer for you. Wrap the app with VeltProvider, call client.setDocument(), and the shared state starts syncing immediately. Node positions, text, cursors, and comments all stay inside the same document.

That sync layer is already running the moment you call setDocument(). Everything else in this build sits on top of it. Before getting into the implementation, here is how to get the project running.

Before You Start

Clone the repo and add your environment variables to get it running locally.

git clone https://github.com/Studio1HQ/claude-velt-mcp-app
cd velt-whiteboard
npm install

Add these three keys to your .env:

NEXT_PUBLIC_VELT_API_KEY=your_velt_key
MINIMAX_API_KEY=your_minimax_key

Then run npm run dev and open localhost:3000.

You can grab your Velt API key from the Velt dashboard and your MiniMax key from the MiniMax platform.

The rest of this post walks through how the project is structured and how each piece is built, so you have the full context of what you are looking at.

Setting Up Velt

We did not write any of the code setup manually. During the building of this project, we used Velt Agent Skills and the Velt MCP server. One prompt handled the entire setup, the agent scanned the project, picked the right provider location, and generated the files.

If you are on Cursor or Claude Code, Velt also has an AI Plugin that bundles the MCP server, skills, rules, and an expert agent in one install, so you can skip even these three steps.

We used VS Code, so we set up the skills and MCP server separately. Here is how:

Step 1: Install Agent Skills

Run this in your project root:

npx skills add velt-js/agent-skills

This pulls four skill sets into your project: setup best practices, comments, CRDT, and notifications. Your agent picks the right one automatically based on what you ask it to do.

Step 2: Add the Velt MCP server to your editor

npx -y @velt-js/mcp-installer

Restart your editor after running this.

Step 3: Start the installation

In your AI agent chat (Copilot, Claude, Cursor, whichever you use), type:

install velt

The agent walks through the setup one step at a time: your project path, API key, which features you want, and where to put VeltProvider. It scans the codebase to detect your auth pattern and document ID source, shows you its findings, and generates an implementation plan before touching anything. You approve the plan, it applies the changes, and then runs a QA pass automatically.

The prompt we used for this project:

Set up Velt collaboration in my Next.js app. I need comments, presence, cursors, and CRDT for ReactFlow. My API key is in .env as NEXT_PUBLIC_VELT_API_KEY.

What would have taken a couple of hours of reading docs came down to that one prompt. The folder structure and code below are exactly what came out of it.

components/
  providers/
    velt-provider-wrapper.tsx  ← wraps the app with VeltProvider
    velt-authenticator.tsx     ← identifies user and sets document
  whiteboard/
    whiteboard.tsx             ← main canvas
    nodes/                     ← StickyNote, TextNode, ShapeNode
  layout/
    header.tsx                 ← where all Velt UI components live
lib/
  ai/
    ai-helpers.ts
    canvas-actions.ts
store/
  whiteboard-store.ts

There are two separate provider files here. VeltProviderWrapper just wraps the app with VeltProvider and passes the API key. VeltAuthenticator sits inside it and handles the actual user identification and document setup.

// velt-authenticator.tsx
await client.identify({
  userId: currentUser.userId,
  name: currentUser.name,
  email: currentUser.email,
  photoUrl: currentUser.photoUrl,
  organizationId: currentUser.organizationId,
});

// runs after identify resolves
client.setDocument(documentId);

The order matters. setDocument only runs after isUserIdentified flips to true, which is tracked with a useState flag. If you call setDocument before the user is identified, Velt won't associate that session correctly with the document; that’s why the agent put these in one order.

The demo uses hardcoded users with a dropdown switcher. If you want to plug in real auth, swap the currentUser object in the store with whatever your auth provider returns, and the rest of the setup stays the same.

The Canvas

The canvas layer is built on two packages, @xyflow/react for the canvas itself and zustand for global state management.

ReactFlow handles the canvas, nodes, edges, and interactions. Zustand is for global state management across the app.

Having everything in a single store makes it much easier to wire up features like AI later, since any part of the app can read or write the same state without prop drilling or extra context layers.

State Management

The store is in lib/store/whiteboard-store.ts. It keeps track of the active tool, selected shape, selected template, a node ID counter, and a few other things. One thing worth noting is how setSelectedTool works. When you switch to "shapes" or "templates", it also flips the corresponding panel open automatically.

setSelectedTool: (tool: ToolType) => {
  set({ selectedTool: tool });
  if (tool === "shapes") set({ isShapesPanelOpen: true });
  if (tool === "templates") set({ isTemplatesPanelOpen: true });
}

The node ID counter is just an incrementing number prefixed with "node-". Simple, but it prevents collisions when multiple nodes are dropped quickly.

Setting Up ReactFlow

In whiteboard.tsx, you register all custom node types before passing them to <ReactFlow>. This maps a string like "sticky" to the actual React component.

const nodeTypes = useMemo(() => ({
  sticky: StickyNote,
  text: TextNode,
  shape: ShapeNode,
}), []);

<ReactFlow
  nodes={nodes}
  edges={edges}
  nodeTypes={nodeTypes}
  onNodesChange={onNodesChange}
  onEdgesChange={onEdgesChange}
  onConnect={onConnect}
  onPaneClick={handlePaneClick}
>
  <Background />
  <Controls />
</ReactFlow>

onPaneClick is where click-to-place logic sits. When a tool or shape is selected in the store, clicking the canvas converts that canvas coordinate to a flow position and creates a new node there.

Building a Node

StickyNote.tsx is a good starting point for understanding how all nodes work. Every node receives data, selected, and id as props via NodeProps. The component keeps its own local state for text, color, and isEditing. On double-click, it switches to a textarea, and on blur, it commits back.

function StickyNote({ data, selected, id }: NodeProps) {
  const [isEditing, setIsEditing] = useState(false);

  return (
    <>
      <NodeResizeControl>...</NodeResizeControl>
      <NodeToolbar>{/* color picker */}</NodeToolbar>
      <Handle type="source" position={Position.Right} />
      {isEditing ? <textarea /> : <div>{text}</div>}
    </>
  );
}

export default memo(StickyNote);

Notice memo() at the bottom. Without it, every canvas interaction re-renders all nodes. ReactFlow recommends this for any non-trivial node. The Handle components on all four sides is what allows edges to connect from any direction. ShapeNode follows the same pattern, but uses a switch on shapeType to render different SVG shapes, rectangles, circles, diamonds, and so on.

Templates

Templates are in lib/constants/templates.ts as a plain array of TemplateType objects. Each template has an id, name, description, and a nodes array. That nodes array is just ReactFlow node definitions with preset positions, types, colors, and labels. No runtime logic.

{
  id: "kanban",
  name: "Kanban Board",
  nodes: [
    { type: "text", position: { x: 50, y: 50 }, data: { text: "📋 Backlog" }, style: { width: 250 } },
    { type: "text", position: { x: 330, y: 50 }, data: { text: "➡️ Up next" }, style: { width: 250 } },
    // ...
  ]
}

When you click a template in the sidebar, it sets selectedTemplate in the store. The next click on the canvas calls getNextNodeId() for each node in the template, offsets all positions relative to where you clicked, and adds them to the ReactFlow nodes array in one go. The template disappears from the selection state immediately after.

To add your own template, you define the layout once by hand and commit it to the array. If the layout is repetitive (like the brainstorm grid), you can use Array.from with a generator to compute positions instead of writing them all out. The existing templates show both approaches.

With the canvas layer in place, the next piece is layering Velt on top of it for real-time collaboration.

Real-Time Collaboration with Velt

Once VeltProvider wraps the app and the document is set, the collaboration layer is essentially ready. The only thing left is placing the right components in the right spots.

Cursors and Presence

VeltCursor and VeltPresence are both mounted inside VeltProviderWrapper in VeltProvider.tsx, sitting alongside the app children. This means they are active across the entire canvas, not scoped to a specific component. Every connected user gets a labeled cursor that moves in real time, and their avatar shows up in the "Online" section of the header.

The Header Tools

All four collaboration controls sit in TopBar.tsx. The component imports VeltCommentTool, VeltPresence, VeltNotificationsTool, and VeltSidebarButton from @veltdev/react and drops them into the header alongside the user switcher dropdown.

import {
  VeltPresence,
  VeltNotificationsTool,
  VeltCommentTool,
  VeltSidebarButton,
} from "@veltdev/react";

// Inside the header JSX:
<VeltCommentTool />
<VeltSidebarButton />
<VeltNotificationsTool />
<VeltPresence />

VeltCommentTool activates the comment pin mode so users can click anywhere on the canvas to leave a comment. VeltSidebarButton toggles a panel that lists every comment on the document in one place. VeltNotificationsTool shows a bell icon with a badge that updates when someone mentions you or replies to your thread. VeltPresence renders the avatar stack at the right side of the header.

Comments

The comment editor Velt ships uses SlateJS under the hood, so it supports rich text out of the box, including @mentions. When a user clicks anywhere on the canvas with comment mode active, a pin drops at that position, and a comment thread opens. The pin stays anchored there, visible to everyone on the document.

Dark Mode

Velt's components use Shadow DOM by default, which means your global CSS won't reach them. To apply custom theming, you first disable Shadow DOM on the components you want to style:

<VeltComments shadowDom={false} />
<VeltCommentsSidebar shadowDom={false} />

Then you use Velt's theme playground to generate your CSS token set. It gives you a full palette for both light and dark mode that you can copy directly. Paste it inside the body tag in globals.css and it covers both themes automatically.

body {
  /* Border Radius */
  --velt-border-radius-xs: 0.5rem;
  --velt-border-radius-sm: 1rem;

  /* Light Mode */
  --velt-light-mode-accent: #e31646;
  --velt-light-mode-background-0: #ffffff;
  --velt-light-mode-text-0: #0a0a0a;

  /* Dark Mode */
  --velt-dark-mode-accent: #e31646;
  --velt-dark-mode-background-0: #000000;
  --velt-dark-mode-text-0: #ffffff;

  /* and so on... */
}

The theme playground is the fastest way to get this right. You pick your accent color, adjust the radius and spacing, and it generates the full token set.

AI on the Canvas

With the canvas rendering and state managed globally, let's add AI to the canvas.

To add AI to the canvas, you need three things:

an API route that calls the model,
a set of structured action types that the model can return, and
a function that converts those actions into ReactFlow nodes.

The AI sidebar in this project connects all three.

The sidebar has four modes.

Ask AI for free-form chat,
Brainstorm to generate ideas as sticky notes,
Summarize to get a read of what's on the board, and
A Template namer that looks at the current layout and suggests what to call it.

You type a prompt, it reads the live canvas state, and either responds with text or drops new nodes directly onto the canvas.

Add Model

The model powering this is MiniMax M2.5, a large context model that's fast and works well for structured output tasks like this one. What made it easy to drop in is that it runs on an Anthropic-compatible API. You get the API key from MiniMax's platform, then point the Anthropic SDK at their base URL and swap the model name. No new SDK, no adapter layer.

const client = new Anthropic({
  apiKey: process.env.MINIMAX_API_KEY,
  baseURL: "https://api.minimax.io/anthropic",
});

const message = await client.messages.create({
  model: "MiniMax-M2.5",
  max_tokens: 2000,
  system: CANVAS_SYSTEM_PROMPT + contextSummary,
  messages: [{ role: "user", content: prompt }],
});

The context window is large enough that you can serialize the entire node list and send it with every request. The current canvas state gets appended to the system prompt as a JSON summary of all nodes, their IDs, types, text, and colors, so the model always knows what's already on the board before it responds.

MiniMax M2.5 in the Editor

Since the same API is Anthropic-compatible, you can also wire it into GitHub Copilot Chat inside VS Code, not just inside the project. During the build, we added MiniMax M2.5 as the active model in Copilot and used it to ask questions and build features directly from the editor.

It works the same way as any other model in Copilot Chat, except it is your own key and your own model.

Canvas Actions

Back to the app, the model needs to do more than just respond with text. It needs to place nodes, update colors, and interact with the canvas in a predictable way. Rather than letting the model return free-form text and trying to parse intent from it, the system prompt instructs it to always return structured JSON with two fields: message and actions. The actions array is a typed list of operations the model wants to perform on the canvas.

{
  message: "Added 5 brainstorming sticky notes",
  actions: [
    {
      type: "add_sticky",
      items: [
        { text: "Reduce onboarding steps", color: "#fef08a" },
        { text: "Add social login", color: "#fef08a" },
      ]
    }
  ]
}

buildNodesFromActions() in canvas-actions.ts takes that actions array plus a canvas anchor point and converts it into ReactFlow nodes, laid out in a grid starting from that position. If the action is update_color, applyColorUpdates() maps over existing nodes and patches their color in place. Both functions are pure, they take nodes in and return nodes out, with no side effects.

The AI does not directly touch the ReactFlow state. It just returns data. The sidebar calls buildNodesFromActions, gets the result, and passes it to setNodes. That separation keeps the AI logic completely independent of how the canvas renders.

With everything wired up, run npm run dev and open localhost:3000. Velt takes a second to initialize on the first load, after that, the canvas is live.
Switch between the two demo users using the dropdown in the header to simulate two people on the same board. Both cursors show up, comments are shared, and the AI sidebar works independently from either user session.

Demo

You can check the deployed version of our app here - https://mural-velt.vercel.app/

Bottom Line

This article covered building a collaborative whiteboard from the canvas layer up, real-time sync with Velt's CRDT, live cursors and comments, and an AI sidebar that reads and writes to the board. The pieces are modular enough that extending it is mostly additive.

A few things worth building on top of this:

Lottie reactions on nodes so collaborators can leave emoji responses without opening a comment thread
Export to PNG or PDF so teams can take the board outside the browser
More node types like embeds, images, or code blocks

The CRDT layer is already there, so most of these would be new node types or toolbar additions rather than architectural changes.

Velt Docs MCP, worth setting up in your IDE before you start a Velt integration
Velt Skills
MiniMax Docs

Build a Real-Time Social Media App with InsForge, MiniMax, and Next.js

Astrodevil — Wed, 25 Mar 2026 18:57:24 +0000

Introduction

In this tutorial, we will build a full-stack social platform where users post, like, repost, follow each other, get real-time notifications, and chat with an in-app AI assistant.

Here is what we will be building:

A Next.js frontend with a real-time feed, post composer, profile pages, notifications, explore, and an AI chat screen
InsForge as the backend platform, managing the database, auth, file storage, real-time pub/sub, and AI gateway from a single place
MiniMax M2.7 via GitHub Copilot as the agent that builds the entire application through InsForge Agent Skills and MCP.
Google Stitch for generating the design reference before the agent builds
Deployment triggered from inside GitHub Copilot, with no manual steps outside the editor

By the end, you will have a working social platform template you can fork and adapt to whatever you are building next.

Let's get started.

What Is InsForge

InsForge is an open-source backend platform that bundles a Postgres database, a REST API layer via PostgREST, an AI model gateway that routes to any OpenRouter-compatible model, a real-time pub/sub system, serverless edge functions, and a CLI, all into a single deployable platform. You can self-host it with Docker or use the managed cloud. You bring the application logic. InsForge handles what's underneath.

What We Are Using InsForge For

Three things in particular make InsForge the right fit for a project like this one.

Agent Skills: When you run insforge create, the CLI installs a .agents/ folder into your project. That folder contains the InsForge SDK documentation, API patterns, and auth setup in a format the agent can read directly. Before the agent writes a single file, it reads that folder. This is why the build prompt can stay short. The agent already knows how to talk to InsForge before you type anything.

The AI gateway: InsForge manages the AI provider keys automatically on the backend, you don’t need to put an OpenRouter key in your frontend .env file. From there, any AI call in your frontend app using the SDK hits one InsForge endpoint and passes a model string. To swap models, you simply change that string; nothing else in the codebase needs to be touched. The backend gateway securely routes the request through OpenRouter, supporting models from OpenAI, Anthropic, Google, DeepSeek, X-AI, and more.

The PostgREST layer: Every table in your InsForge database is automatically a REST endpoint. The agent writes queries against the InsForge SDK. There is no data access layer to build, no custom API routes to wire up. You describe the schema, and the endpoints are there.

Setting Up the Project

Every InsForge project starts with the CLI. Install it once globally, log in, and you are set for every project you build after this.

npm install -g @insforge/cli
insforge login

That is a one-time setup. From here on, every time you want to start a new project, you create a folder and run insforge create inside it.

mkdir ripple
cd ripple
insforge create

The CLI asks you to pick a template. We picked Next.js. After that, it installs the Agent Skills, writes skills-lock.json, and asks if you want to set up deployment now. Say no for now. We will come back to that at the end.

One more thing, before you start building, install the MCP server. The quickest way is through the InsForge VS Code extension. Install it from the marketplace, and it will show you a one-click option to connect the MCP. Once done, you will see the MCP Connected indicator in the top-right corner of your InsForge dashboard, and your agent is ready to act.

Designing with Google Stitch

Before writing a single prompt, we used Google Stitch to design the UI for Ripple. We used this prompt to get started:

Build a social media app called Ripple. Amber gold (#F59E0B) as the primary color.
Screens: feed, composer, profile, notifications, Wave AI chat, auth screens.

Stitch exports a design.md file with the full design system, colors, typography, component structure, and screen layouts.

Copy that file and save it in your project root in VS Code. When you reference it in your agent prompt, the agent has all the visual context it needs upfront, so you are not going back and forth on colors or layout later.

With the design in place, we had everything the agent needed to build the UI and wire the backend in a single pass. Time to write the prompt.

Building the App

We used GitHub Copilot as the agent, running MiniMax M2.7*,* because it handles long multi-step tasks well and stays on track across a full project build. We gave it one prompt:

Build a social media app called Ripple using InsForge as the backend platform.
Use InsForge MCP Server for all operations.

Features:
- Auth: sign up, login with name, @handle, email, password
- Feed: post (called Ripple) with text + image/video upload, like (Wave),
  repost (Spread), reply, bookmark
- Realtime feed updates
- Post composer with draft save
- Profile page with cover, avatar, bio, followers/following
- Notifications: likes, replies, follows, mentions
- Explore: trending topics, suggested users
- Wave AI: chat interface connected to InsForge AI gateway via OpenRouter
- Wave AI has collapsible right panel with chat history and bookmarks
- Deploy on InsForge

Follow the design system in design.md for colors, typography, and components.
Use InsForge for all backend. Read .agents folder for skills.

Before touching any file, the agent read .agents/skills/insforge/ to understand the InsForge SDK, then laid out the full database schema profiles, ripples, waves, spreads, follows, notifications, drafts, ai_chat_history, and more, and created a build plan for itself. Only after that did it start writing code.

The file structure was produced in one pass:

ripple/
├── src/app/
│   ├── feed/page.tsx
│   ├── profile/[handle]/page.tsx
│   ├── notifications/page.tsx
│   ├── ripple/[id]/page.tsx
│   └── wave/page.tsx
├── src/components/
│   ├── ripple/RippleCard.tsx
│   └── ripple/RippleComposer.tsx
├── src/lib/
│   ├── insforge.ts
│   └── auth-context.tsx
└── .agents/
    └── skills/insforge/

What is worth noticing here is that insforge.ts is not a custom wrapper; the agent read the skill and knew exactly how to initialize the InsForge client.

Same with auth-context.tsx: it wired sessions directly to InsForge Auth without any manual setup from us. Now, all of this came from one prompt. But what the agent actually built inside each of these files, how it handled auth sessions, how it wired realtime, how AI talks to the InsForge gateway, that is where things get interesting. So let’s see exactly what agent built inside each of those files.

What InsForge Handled, Feature by Feature

Let's start with auth, since that is what everything else depends on.

Auth

Authentication in Ripple runs entirely through InsForge Auth: sign up, email verification, login, and session management. All the state stays in a single React Context, the agent is generated and wired up in one pass.

Sign-up is a two-step flow. The agent calls insforge.auth.signUp(), checks if email verification is required, and stores the pending profile in localStorage until the OTP is confirmed. Once verified, it inserts the profiles record using the authenticated user ID.

const { data } = await insforge.auth.signUp({ email, password, name });
if (data?.requireEmailVerification) {
  localStorage.setItem("ripple_pending_name", name);
  return { requireEmailVerification: true };
}

// after OTP confirmed
await insforge.database.from("profiles").insert([{
  id: data.user.id, name: pendingName, handle: pendingHandle, email,
}]);

The signup page tracks a step state that switches between the form and the verify screen. Login is simpler, one call to insforge.auth.signInWithPassword() and the session is set.

Database

With auth out of the way, the agent moved on to the database. InsForge runs on PostgreSQL under the hood, and every table gets automatically exposed as a REST endpoint through PostgREST, which means the agent never had to write a single custom API route.

The schema the agent built covers the full surface area of the app. The core tables are profiles, ripples, ripples_media, waves (likes), spreads (reposts), follows, notifications, and ai_chat_history for the Wave AI sessions. The notifications table also has a Postgres trigger attached to it, so every insert immediately fires a real-time broadcast over the WebSocket.

-- setup_trigger.sql
CREATE OR REPLACE FUNCTION notify_new_notification()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM pg_notify(
    'new_notification',
    json_build_object(
      'id', NEW.id,
      'user_id', NEW.user_id,
      'type', NEW.type,
      'actor_id', NEW.actor_id,
      'ripple_id', NEW.ripple_id
    )::text
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

Because PostgREST understands foreign keys, the agent could request deeply nested relational data in a single query rather than chaining multiple fetches. Here is the feed query from page.tsx, which pulls ripples alongside their author profiles, attached media, waves, and spreads in one request:

// page.tsx — fetching the main feed
const { data, error } = await insforge.database
  .from("ripples")
  .select(`
    *,
    profiles (*),
    ripples_media (*),
    waves (*),
    spreads (*)
  `)
  .is("reply_to", null)
  .order("created_at", { ascending: false })
  .limit(50);

The profiles (*) in the select string is where PostgREST detects the foreign key between ripples.user_id and profiles.id and performs the join automatically on the backend, returning the author's data nested inside each post object. The same pattern applies to waves and spreads, so the UI always knows the engagement state of a post without a second request.

Storage

The database takes care of structured data, but for every file, avatars, cover photos, and post media, the agent provisioned three separate InsForge Storage buckets: avatars, covers, and ripples.

InsForge Storage is S3-compatible and sits natively beside the auth and database layers, so the SDK handles uploads, hashing, and public URL generation in a single call without any custom middleware.

For profile photos, the agent used .uploadAuto(), which takes a File object and returns a public URL directly. After each upload resolves, it immediately writes that URL back to the profiles table in the database.

// profile/edit/page.tsx
if (avatar) {
  const { data, error } = await insforge.storage
    .from("avatars")
    .uploadAuto(avatar);
  if (error) throw error;
  avatarUrl = data.url;
}

if (cover) {
  const { data, error } = await insforge.storage
    .from("covers")
    .uploadAuto(cover);
  if (error) throw error;
  coverUrl = data.url;
}

await insforge.database
  .from("profiles")
  .update({ avatar_url: avatarUrl, cover_url: coverUrl })
  .eq("id", user.id);

For post media, the pattern is slightly different because a single ripple can carry up to four attached images. The agent wrote a loop that runs after the post row is created, uploads each file to the ripples bucket, and inserts a matching record into ripples_media that binds the file URL back to the post's ID.

// RippleComposer.tsx
for (const file of media) {
  const { data: uploadData, error } = await insforge.storage
    .from("ripples")
    .uploadAuto(file);

  if (error || !uploadData) throw error;

  await insforge.database.from("ripples_media").insert([{
    ripple_id: ripple.id,
    bucket: uploadData.bucket,
    key: uploadData.key,
    url: uploadData.url,
    type: file.type.startsWith("video") ? "video" : "image",
  }]);
}

Realtime

With the database writing data correctly, the next thing the app needed was for that data to reach every connected client without a page refresh. InsForge Realtime runs on WebSockets, and the agent wired up four live channels: ripples for the global feed, ripples_media for media updates, trending_topics for live topic changes, and notifications:% for per-user alerts.

The feed component subscribes to ripples on mount and handles two event types: INSERT for new posts and UPDATE for engagement count changes.

// page.tsx — feed subscription
const response = await insforge.realtime.subscribe("ripples");

if (response.ok) {
  insforge.realtime.on("INSERT", async (payload) => {
    const newRipple = payload.new as Ripple;
    if (!newRipple.reply_to) {
      const { data } = await insforge.database
        .from("ripples")
        .select("*, profiles (*), ripples_media (*), waves (*), spreads (*)")
        .eq("id", newRipple.id)
        .single();
      if (data) setRipples((prev) => [data as Ripple, ...prev]);
    }
  });

  insforge.realtime.on("UPDATE", (payload) => {
    const updated = payload.new as Ripple;
    setRipples((prev) =>
      prev.map((r) =>
        r.id === updated.id
          ? { ...r, wave_count: updated.wave_count, spread_count: updated.spread_count }
          : r
      )
    );
  });
}

The INSERT payload only carries the raw new row, so the agent does a quick .select() with joins before pushing it into the state, same pattern as the feed query from the Database section. The UPDATE handler just patches the counts in-place without refetching the full post.

For notifications, the Postgres trigger from setup_trigger.sql does the broadcasting on the database side. When a new row hits the notifications table, the trigger publishes directly to notifications:{user_id} over the WebSocket, and realtime-context.tsx picks it up on the frontend to increment the bell count instantly.

AI Gateway

After real-time, the agent focused on the AI gateway. Ripple comes with an in-app AI called Wave AI. Instead of connecting directly to OpenAI or Anthropic, dealing with separate billing, and worrying about exposing keys on the frontend, it uses InsForge's AI gateway. This gateway manages routing, authentication, and model access all in one place.

The gateway call follows the same shape as the OpenAI SDK, so it feels familiar:

const completion = await insforge.ai.chat.completions.create({
  model: "anthropic/claude-sonnet-4-5",
  messages: [
    {
      role: "system",
      content: `You are Wave AI, a helpful assistant on the Ripple social platform. You are talking to ${profile?.name || "a user"}.`,
    },
    ...pastMessages,
    { role: "user", content: userMessage.content },
  ],
});

const reply = completion.choices[0]?.message?.content;

Swapping the model is one line, change "anthropic/claude-sonnet-4-5" to "openai/gpt-4o" or any other model the gateway supports, and nothing else changes.

One thing the AI gateway doesn't do on its own is remember past conversations. Every time you call insforge.ai.chat.completions.create, it only knows what's in the messages array you pass. Close the tab and that's gone.

So the agent added two database tables, ai_chat_sessions to group conversations, and ai_chat_history to store individual messages. Every time the user sends a message, it gets written to the database. Every time Wave AI replies, that gets written too. When you come back to the /ai page later, a useEffect fetches that session and loads all the messages back in. The conversation picks up exactly where it left off.

With auth, database, storage, realtime, and Wave AI all working, the app is ready to run, and it's time to test it locally.

Running Locally

Before deploying, run the app locally to make sure everything works end-to-end.

npm install
npm run dev

Open http://localhost:3000, sign up with a test account, go through the full flow, auth, posting a Ripple, checking the feed. If your InsForge credentials are in .env.local, everything should work on the first run.

Note: InsForge takes care of all the backend wiring, but the frontend is yours to shape. I made a few tweaks to the UI, adjusting the layout and refining some interactions, to make it feel more like my own, and that is the nice part: the backend is handled, so you can spend your time on the experience instead.

Deploying from GitHub Copilot

Once everything worked locally, deploying took one prompt:

Deploy to InsForge.

The agent read the project config, picked up the credentials, and called the create-deployment MCP tool, all from inside Copilot. No browser dashboard, no separate deploy config.

It zipped the source, uploaded it, and InsForge ran npm install and npm run build in a container with the environment variables injected. The live URL came back in the terminal.

What's Next

At this point, you have a fully working social platform running on InsForge. Auth, a real-time feed, media uploads, notifications, and an AI assistant, all live and deployable from inside GitHub Copilot.

From here, the project is yours to extend. Swap the AI model by updating one value in the InsForge dashboard. Replace the schema entirely, and the same SDK patterns, the same Agent Skills, and the same deployment flow all carry forward to whatever you build next. You can fork the project repo and start from there.

To learn more about InsForge, check out the GitHub repo.

Managing Multi Provider AI Workflows in the Terminal with Bifrost CLI

Astrodevil — Sat, 21 Mar 2026 10:52:18 +0000

Command-line tools are still a common way to work with AI. They give better control and fit naturally into everyday workflows, which is why many people continue to use them.

A common issue with CLI-based tools is that they are often tied to a single provider. Switching between options usually means updating configs and handling multiple API keys. In some cases, it may even involve changing tools. This can slow things down and make everyday work feel a bit frustrating.

Bifrost CLI aims to simplify this setup. It provides a single way to connect CLI tools to multiple providers, without changing how the tools are used. In this article, let us look at how it works and how to get started.

What is Bifrost CLI

Bifrost is an open-source AI gateway that works between applications and model providers. It offers provider-compatible endpoints such as OpenAI, Anthropic, and Gemini formats. It manages request routing, API keys, and response formatting in one place, so separate setups for each provider are not required.

Bifrost CLI was recently released to extend this setup to command-line workflows. It allows existing CLI tools to connect through the Bifrost gateway in place of calling providers directly. The CLI tool continues to work in the same way, with only the endpoint updated.

The CLI tool is configured with Bifrost as the base URL. After this, all requests go through the gateway. Bifrost routes each request to the selected provider, converts it into the required API format, and returns a compatible response. The CLI workflow stays the same, with support for multiple providers through a single endpoint.

Key Features of Bifrost CLI

Bifrost CLI brings several practical features that improve how CLI-based workflows are set up and managed:

Automatic Setup for CLI Tools: Configures base URLs, API keys, and model settings for each agent. This reduces manual steps and keeps the environment ready to use.
Model Discovery from Gateway: Fetches available models directly from the Bifrost gateway using the /v1/models endpoint. This ensures the CLI always reflects the current set of available options.
MCP Integration for Tool Access: Attaches Bifrost’s MCP server to tools like Claude Code. This allows access to external tools and extended capabilities from within the CLI.
Session Activity Indicators: Displays activity badges for each tab. It becomes easy to see if a session is running, idle, or has triggered an alert.
Secure Credential Storage: Stores selections and keys securely. Virtual keys are saved in the OS keyring and are not written in plain text on disk.

Getting Started

Bifrost CLI is quick to set up and runs directly from the terminal. The flow includes starting the gateway, launching the CLI, and selecting the agent and model through a guided setup.

Step 1: Start the Bifrost Gateway

Make sure the gateway is running locally (default: http://localhost:8080):

npx -y @maximhq/bifrost

Step 2: Install and Launch Bifrost CLI

In a new terminal, run:

npx -y @maximhq/bifrost-cli

If installed, you can run:

bifrost

Step 3: Enter Gateway Details

Provide the Bifrost endpoint URL.

For local setup, this is usually: http://localhost:8080

If authentication is enabled, you can also enter a virtual key at this stage.

Step 4: Choose a CLI Agent

Select the CLI agent you want to use, such as:

Codex CLI
Claude Code
Gemini CLI
Opencode

The CLI shows which agents are available and can install missing ones during setup.

Step 5: Select a Model

The CLI fetches available models from the gateway and shows them in a searchable list.

You can choose one directly or enter a model name manually.

Step 6: Launch the Session

Review the configuration and start the session. The selected agent runs with the chosen model and setup.

Step 7: Work with Sessions

After launch, the CLI stays open in a tabbed interface.

You can open new sessions, switch between them, or close them without restarting the CLI. Each tab shows the current activity state.

Understanding the Bifrost CLI Session Flow

Bifrost CLI is built for repeated, session-based use in the terminal. You can switch between runs, update settings, and continue your work without having to go through the full setup again each time.

Here are the key steps in the session flow:

Launch: Select the agent and model, then start the session.
Work: Use the agent as usual. All requests go through Bifrost.
Switch Sessions: Press Ctrl + B to open the tab bar, switch between sessions, or start a new one.
Return: When a session ends, the CLI returns to the setup screen with the previous configuration.
Relaunch: Change the agent or model, or rerun the same setup.
Persistence: The last configuration is saved and shown the next time the CLI starts.

Working with Multiple Models

Bifrost CLI makes it easy to work with different models from the same setup. You do not need to change configurations or restart the tool each time you want to try a different option.

During setup, the CLI fetches available models from the Bifrost gateway and shows them in a list. You can select one directly or enter a model name if you already know what you want to use.

If you want to try another model, you can start a new session and choose a different one. Each session runs separately, so you can compare outputs or test different setups side by side.

All requests go through Bifrost, so differences between providers are handled in the background. The CLI experience stays the same across models.

When to Use Bifrost CLI

Bifrost CLI is useful when working with multiple providers or running repeated sessions from the terminal. Since it is built on top of Bifrost, it also brings the benefits of a central gateway into CLI workflows.

Testing Different Models: Try different models across providers from the same setup.
Running Iterative Sessions: Start, stop, and relaunch sessions with minor configuration changes.
Working from the Terminal: Keep the entire workflow inside the CLI, with Bifrost handling routing in the background.
Comparing Outputs: Run multiple sessions side by side and observe how different models respond.
Managing Multiple Providers: Use Bifrost as a single entry point to work across providers in one place.
Centralized Control with Bifrost: Route all requests through Bifrost for consistent handling of API keys, requests, and responses.

This setup helps keep workflows consistent and organized across different providers and sessions.

Conclusion

Bifrost CLI brings multi-provider access into the terminal through a single setup. It keeps existing workflows intact and reduces the need to manage separate configurations.

You can run sessions, switch agents, and try different models from the same interface, with Bifrost handling routing and integration in the background.

To get started or explore more details, check the Bifrost CLI documentation.

DEV Community: Astrodevil

Useful Agent memory for Your Openclaw and Hermes Agent🔥

Building a Hermes Memory Plugin for a Voice-Powered Conference Agent with Weaviate Engram🧠

Building a Hermes Memory Plugin for a Voice-Powered Conference Agent with Weaviate Engram🧠

Introduction

The Conference Agent

Engram: Weaviate’s Memory Solution

Using Engram

Building the Memory Plugin

Implementing the Initialize and Config Methods

Implementing the Hooks

Implementing the Tools

Putting It All Together

Setting Up the Engram Memory Plugin

Engram in Action

Making the Agent Voice-Enabled

Messaging Support for the Conference Agent

Quick Recap

Conclusion

Top Alternatives to Lovable in 2026

TL;DR: Lovable Alternatives Comparison

1. Puck AI

Pros

Cons

When to use Puck AI

2. Bolt.new

Pros

Cons

When to use Bolt

3. Replit AI

Pros

Cons

When to use Replit

4. v0 by Vercel

Pros

Cons

When to use v0

5. Cursor

Pros

Cons

When to use Cursor

Final Notes

Build a Real-Time Excalidraw-like Collaborative Canvas using Velt MCP and Antigravity🎉

What we are building

Why add collaboration to Canvas apps

Why use Velt

Prerequisites

Tutorial: Building Velt-powered Excalidraw-like App

Step 1: Set up Velt MCP

Step 2: Start Velt installation using AI

Step 3: Provide the prompt for MCP

Step 4: Understand the existing project structure

Step 5: Add real-time collaboration features (Using MCP)

Presence and cursors

Canvas comments

Sidebar and UI controls

Notifications and huddle

Step 6: CRDT-based state sync

Step 7: Multi-user simulation

Step 8: Run and test the app

Wrapping up

Build a Dropbox Paper-Style Collaborative Editor with Next.js and Velt💥

Introduction

Tech Stack Overview

Project Structure Walkthrough

What is Velt?

Local Setup (Quick Start)

Wrapping the App with VeltProvider

Adding Inline Comments to TipTap

Adding Presence & Notifications

Multi-User Switching (Simulating Collaboration)

How Everything Works Together

Demo

Final Result & Takeaways

Building a Superhuman-Style Collaborative Email Editor with Next.js and Velt🔥

Introduction

What We’re Building

Tech Stack Overview

Project Setup

Why Use Velt?

Wrapping the App with `VeltProvider`

Theme Management with `useTheme`

Why `isRemoteUpdate` exists