Whiteboard IDE: Open-Source Canvas for Thoughtful Software Design

Whiteboard is an open-source desktop application that aims to revolutionize software design by providing a collaborative canvas for humans and AI agents. It integrates with existing tools and offers unique features for architectural clarity and code review.

Binary Buddies · 5 min read · 7 views

The Challenge of AI-Assisted Software Design

As artificial intelligence becomes more capable of generating and understanding code, a new challenge emerges: how do we effectively collaborate with these agents to design and architect software? Traditional development environments, while powerful for line-by-line coding, often fall short when it comes to visualizing complex architectures, tracing AI-driven decisions, and understanding the nuances of code changes proposed by an agent. The gap between an agent's abstract reasoning and its concrete implementation can be vast, leading to misunderstandings, inefficient workflows, and a loss of critical design context.

This disconnect is particularly pronounced when dealing with AI-generated code. While tools can suggest implementations, the rationale behind those suggestions, the trade-offs considered, and the evolutionary path of the design can be difficult to reconstruct. Without a common workspace that bridges the gap between human intent and agent execution, the full potential of AI in software architecture remains largely untapped. This is the problem that Whiteboard, an open-source IDE, seeks to solve.

Whiteboard positions itself as an open-source canvas for thoughtful software design. It's built to facilitate collaboration between human developers and AI agents, providing a visual and interactive environment for architecting software. By plugging into existing tools and offering agents an SDK to draw and describe their work directly onto an in-app canvas, Whiteboard aims to make the AI-assisted development process more transparent and manageable.

Architecting with AI Agents

Whiteboard is designed as a collaborative workspace where both humans and AI agents can architect software together. The core idea is to provide a common ground for understanding and shaping software designs. Agents, such as Claude Code or Codex, can be connected directly within the application. Once connected, they are given an SDK that allows them to interact with an in-app canvas. This means agents can visually represent their thought processes, proposed solutions, and explanations directly within the Whiteboard environment, making their contributions more tangible and easier for human developers to interpret.

The application supports the integration of various coding agents. To get started, users download Whiteboard, open the app, and connect their chosen agent from the welcome screen. A typical workflow might involve asking the agent to review a current development branch against the main branch and then opening the results within Whiteboard. This allows for immediate visualization and analysis of proposed changes, fostering a more dynamic feedback loop between developer and agent. The prompt engineering is crucial here; for instance, asking an agent to review an API change might involve requesting proposed examples, motivations, and then diving into implementation details, all of which can be visualized on the whiteboard.

For optimal performance and intelligence, Whiteboard guides users towards models like GPT-6 Sol and Claude Opus 5.5, citing their balance of intelligence, cost, and speed. This guidance highlights the importance of selecting the right AI model for complex design tasks. The open-source nature of Whiteboard is central to its philosophy, with developers actively working to bake in sensible defaults for system prompts, aiming to streamline the agent interaction process over time.

Visualizing Code Changes with a Semantic Diff Viewer

One of the standout features of Whiteboard is its semantic, Abstract Syntax Tree (AST)-aware diff viewer. Traditional diff tools often present a noisy, line-by-line comparison of code changes, which can obscure the actual functional or architectural implications of a modification. Whiteboard's viewer, built in Rust, aims to cut through this noise by understanding the code's structure.

This AST awareness allows Whiteboard to intelligently summarize or collapse certain types of changes. For example, large added functions might be presented as pseudocode, providing a high-level overview without overwhelming the user. Similarly, changes related to unit tests or documentation can be collapsed by default, allowing developers to focus on the core logic changes. This approach is particularly valuable when reviewing code generated or modified by AI, where the sheer volume of changes can be daunting.

Customization is a key aspect of the diff viewer, with a WASM-based plugin system in place. This means users can tailor how changes are presented to suit their specific needs and preferences. While defaults are set for common scenarios, the ability to extend and modify the diffing behavior ensures that Whiteboard can adapt to a wide range of development workflows and project complexities. The goal is to present only the code changes that are relevant to the user, streamlining the review process.

Decision Logging for Traceability

Reasoning about the autonomous decisions made by AI agents during the software development process can be challenging. Whiteboard addresses this by incorporating a decision log feature. This allows AI agents to query and link their own execution traces directly on the Whiteboard canvas, providing a clear audit trail of their actions and the reasoning behind them.

This feature is invaluable for understanding how an agent arrived at a particular solution. Developers can visualize the initial requirements they set for the agent, observe how those requirements were translated into implementation steps, and identify any autonomous decisions the agent made along the way. This level of transparency is crucial for debugging, auditing, and ensuring that the AI's contributions align with the project's goals and established architectural principles.

By linking agent traces to the visual representation on the canvas, Whiteboard creates a narrative of the design process. This not only aids in understanding AI behavior but also serves as a valuable knowledge repository. Future iterations or team members can refer back to these logs to grasp the evolution of the software design, making the development process more collaborative and maintainable, especially in complex AI-assisted projects.

Seamless Integration and Local Execution

Whiteboard is built with the intention of integrating into existing development workflows rather than replacing them entirely. It plugs into tools developers already use, aiming to enhance, not disrupt. By running against local code checkouts, Whiteboard ensures that sensitive information remains on the developer's machine, aligning with common privacy and security practices in software development.

The application is MIT-licensed and runs locally, making it an accessible open-source solution for individual developers and teams. The developers have explicitly chosen to vendor Code OSS (the open-source core of VS Code) as a baseline. This decision was made because coding agents often struggle with patches, and stock VS Code includes many features that are not directly relevant to a code review-focused application. By forking Code OSS, Whiteboard can maintain a cleaner codebase tailored for its specific purpose while still benefiting from the robust foundation of a widely-used open-source editor.

This approach also allows Whiteboard to merge security and feature patches from upstream Code OSS regularly, ensuring that the underlying editor technology remains up-to-date. While a hosted product for teams is planned, the commitment to remaining self-hostable underscores the project's focus on user control and data privacy. This local-first, open-source strategy is key to building trust and adoption within the developer community.

Customization via WASM Plugin System

To further enhance flexibility and cater to diverse development needs, Whiteboard incorporates a WASM (WebAssembly) plugin system. This system allows developers to extend the functionality of the IDE and customize its behavior, particularly in areas like the semantic diff viewer.

The WASM plugin system enables users to write custom logic that can be executed within the Whiteboard environment. This is particularly useful for tailoring how code changes are interpreted, summarized, or highlighted. For instance, a team might develop a plugin to specifically identify and flag certain anti-patterns or to apply custom rules for collapsing code blocks based on project-specific conventions. This level of extensibility makes Whiteboard adaptable to niche requirements or rapidly evolving development practices.

By leveraging WASM, Whiteboard ensures that plugins can be written in various languages that compile to WebAssembly, offering developers a broad choice of tools and familiar programming paradigms. This approach keeps the core application lean while empowering users to build bespoke features. The contribution guidelines, available in CONTRIBUTING.md, provide further details on how to set up the development environment and contribute plugins or other enhancements to the open-source project.

Handling Complex Codebases and Multi-Repo Reviews

Whiteboard's design is optimized for thoughtful software design and review, particularly in the context of AI assistance. However, like any tool, it has areas where its current implementation has known limitations. One such area is working with and browsing files across multiple repositories within a single review session. Currently, this functionality is not well supported, which can be a drawback for developers working on large, modular projects that span several distinct codebases.

Another limitation concerns collaboration and state sharing. While Whiteboard does offer a 'share' button to allow users to share reviews between machines, updates made to a shared review after it has been shared do not appear for other participants. To reflect subsequent changes, the review must be re-shared. This means that real-time, collaborative editing or viewing of ongoing changes is not seamless and requires manual re-sharing, which can interrupt the flow of a synchronized review session.

Furthermore, the application currently does not allow users to directly edit files within Whiteboard. If a developer identifies a need to make direct code modifications during their review process, they would need to switch to a separate editor. The Whiteboard team acknowledges this limitation and encourages users who find this feature desirable to file an issue on their GitHub repository. Feedback and contributions are welcomed to help shape the future development of this open-source tool.

Open Source Philosophy and Community

The Whiteboard project is fundamentally an open-source initiative, licensed under the MIT License. This licensing model ensures that the software is freely available for use, modification, and distribution, fostering a collaborative environment. The project actively encourages contributions from the community, providing detailed guidance in their CONTRIBUTING.md file for setting up the development environment and contributing code through pull requests. A Code of Conduct and a security policy are also in place to ensure a safe and productive community interaction.

The decision to make Whiteboard open-source stems from a desire to build a tool that truly serves the needs of developers. By operating in the open, the project aims for transparency in its development and telemetry practices. While anonymous telemetry is collected, it is designed not to include sensitive data such as code, diffs, prompts, or model output. A comprehensive privacy overview and telemetry reference are available for users who wish to inspect or understand the data collection processes, with the option to disable telemetry at any time.

The project also draws inspiration from the broader discourse on software engineering and AI, referencing influential articles and discussions from figures like Geoffrey Litt and Andrej Karpathy. This intellectual lineage suggests a deep consideration for the evolving landscape of software development, particularly how AI agents are transforming the role of the developer and the nature of code itself. The community aspect is further supported by a Discord server, providing a platform for questions, discussions, and collaboration among users and developers.

Where Whiteboard Might Not Fit

While Whiteboard offers a compelling vision for AI-assisted software design with its open-source canvas, semantic diff viewer, and decision logging, it's important to understand its limitations and where it might not be the optimal tool. For instance, its current inability to directly edit files means it's not a complete replacement for a traditional IDE where rapid iteration and in-place modification are paramount. Developers who prefer to make immediate code changes during a review will need to context-switch to another tool.

The challenges with multi-repository reviews also mean that Whiteboard may not be ideal for developers working on highly distributed or microservices architectures that involve constant cross-repository navigation. Similarly, the limitation regarding real-time updates for shared reviews can hinder workflows that rely on synchronous, collaborative deep-dives into code where multiple people are actively contributing to a single, evolving review session. In such cases, alternative collaborative platforms or screen-sharing methods might be more efficient.

Finally, while Whiteboard excels at visualizing agent-driven design and code changes, it might be overkill for simple code reviews or projects where AI involvement is minimal. Its strengths lie in bridging the gap between abstract AI reasoning and concrete code, and in providing traceability for AI decisions. For straightforward code inspection tasks that don't involve complex AI interactions or architectural diagramming, a more traditional code review tool might suffice and offer a simpler user experience. Developers should evaluate their specific workflow needs against these trade-offs.

  • #AI Agents
  • #IDE
  • #Open Source
  • #code review
  • #semantic diff
  • #software design

Comments

Add a comment
Sign in with Google to join the conversation