Building AI Agent Tools: The Complete Showboat Ecosystem Guide

Key Takeaways

• Showboat remote publishing enables real-time document streaming from Claude Code and other AI agents to your own web server
• Chartroom simplifies chart generation for AI agents, supporting bar charts, line charts, scatter plots, and histograms with automatic alt text
• datasette-showboat plugin provides an easy deployment mechanism for receiving and viewing Showboat documents in Datasette
• The modular tool ecosystem demonstrates how loosely-coupled CLI tools can work seamlessly together through simple conventions
• AI-driven development is dramatically accelerated when agents can demonstrate their work in real-time through documentation and visualization

Understanding the Showboat Ecosystem: Why It Matters for Modern Development

The landscape of AI-assisted coding has fundamentally changed over the past year. Developers and data scientists now have access to powerful coding agents like Claude Code that can autonomously create solutions, but there's been a critical gap: demonstrating what these agents have built.

This is where Showboat enters the picture. Introduced just days before this ecosystem expansion, Showboat is a specialized CLI tool designed to help coding agents create Markdown documents that showcase the code they've produced. But Showboat itself is only the beginning. What makes it truly revolutionary is how it's evolved into a complete ecosystem of complementary tools that work together seamlessly.

The three new tools released alongside Showboat—Chartroom, ** datasette-showboat**, and the remote publishing feature—represent a fundamental shift in how we think about agent-generated documentation. Rather than forcing developers to wait hours for agents to finish their work and commit results to version control, these tools enable ** real-time collaboration between humans and AI agents**, with live updates streaming directly to a viewer.

This ecosystem is particularly powerful because it's built on a simple principle: loosely-coupled conventions rather than tightly-integrated architecture. Any tool that can output text can integrate with Showboat. Any tool that can generate an image can be embedded in Showboat documents. This flexibility makes the ecosystem extensible and future-proof, requiring minimal coordination between different tools.

Remote Publishing: Streaming Live Updates from Your AI Agents

How Remote Publishing Works

The traditional workflow with Showboat required patience. You'd prompt Claude Code to use Showboat to demonstrate something, but you couldn't see the results until the agent committed everything to GitHub and pushed it to a branch. Then you'd have to navigate to GitHub, find the right file, and view it there. This created a significant friction point in the development loop.

The new remote publishing feature in Showboat v0.6.0 solves this by allowing agents to stream document updates to your own server in real-time. Instead of waiting for the entire process to complete, you can watch the Showboat document build itself chunk by chunk as the agent works.

Configuration is remarkably simple—just set a single environment variable:

export SHOWBOAT_REMOTE_URL=https://www.example.com/submit?token=xyz

From that point forward, every Showboat command your agent runs—whether it's showboat init, showboat note, showboat exec, or showboat image—will POST the resulting document fragments to your remote endpoint while simultaneously updating the local Markdown file.

The API design is intentionally minimal and elegant. It uses standard POST form variables for regular content and multipart form uploads for images attached to showboat image commands. This simplicity means you can implement a Showboat receiver in virtually any web framework or environment. The full technical details are available in the Showboat README, but the core concept is straightforward: your agent tells Showboat where to send updates, and Showboat handles the rest.

Real-World Impact on Development Speed

The practical implications of this feature are substantial. Consider a typical data analysis session: you tell Claude Code to download a SQLite database, run exploratory queries, and create a Showboat document demonstrating its findings. Normally, you'd wait until the entire process completed. With remote publishing, you see the document building in real-time. If you spot an issue or want to adjust the analysis direction, you can provide immediate feedback while the agent is still working—cutting development cycles from hours to minutes.

This is particularly valuable for iterative tasks. An agent might discover interesting patterns in data, add screenshots of visualizations, and include code snippets showing the analysis steps. Rather than discovering problems at the end of the process, you can catch them in progress and course-correct immediately.

Datasette-Showboat: Easy Deployment and Real-Time Viewing

What Datasette-Showboat Provides

While remote publishing establishes the mechanism for streaming updates, you still need a receiver to handle those updates and display the documents attractively. Rather than force every user to build their own receiver endpoint, the solution was to create a Datasette plugin that provides both the receiving infrastructure and a polished viewing interface.

datasette-showboat adds two critical endpoints to any Datasette instance:

• /-/showboat: A web interface for browsing and viewing Showboat documents
• /-/showboat/receive: An API endpoint that accepts streaming updates from Showboat

The plugin stores all incoming Showboat fragments in a SQLite database, automatically organizing them by document UUID and timestamp. This means you not only get live viewing capability, but also a permanent historical record of every document your agents have created and every iteration they've made.

Getting Started with Datasette-Showboat

The quickest way to try datasette-showboat is through a single command:

uvx --with datasette-showboat --prerelease=allow \
  datasette showboat.db --create \
  -s plugins.datasette-showboat.database showboat \
  -s plugins.datasette-showboat.token secret123 \
  --root --secret cookie-secret-123

This creates a Datasette instance with the showboat plugin enabled, ready to receive documents. The console output provides a sign-in link where you can authenticate as root, then navigate to http://127.0.0.1:8001/-/showboat to see the interface.

Once your instance is running, point Showboat to it:

export SHOWBOAT_REMOTE_URL="http://127.0.0.1:8001/-/showboat/receive?token=secret123"

Initialize a new document:

uvx showboat init demo.md "Showboat Feature Demo"

Refresh the datasette-showboat interface, and your document appears immediately. The plugin manages all the complexity of receiving, parsing, and storing fragment updates—you just point your agents at the endpoint and everything works.

Why Datasette Was the Ideal Foundation

The decision to build datasette-showboat as a Datasette plugin rather than a standalone web application reflects sophisticated architectural thinking. Datasette is already optimized for exploring and visualizing data, already handles database management, already provides authentication and API access, and already has proven deployment mechanisms. Rather than reinvent all of this, the plugin approach leverages existing infrastructure.

This is particularly important because most developers who would benefit from Showboat already use Datasette for data exploration and publishing. They have existing Datasette instances, familiar deployment patterns, and established security configurations. Adding Showboat support is simply a matter of installing a plugin.

For production deployments, users can run datasette-showboat on cloud platforms like Fly.io (as the creator does), private servers, or containerized environments. The Datasette ecosystem provides the entire necessary infrastructure for this, from database handling to TLS termination.

Chartroom: Intelligent Chart Generation for AI Agents

The Challenge: Visualizing Data Through Agents

As AI agents became capable of complex data analysis tasks, a new problem emerged: how could agents produce charts and visualizations to accompany their analysis? It's one thing for an agent to run SQL queries and produce numeric results. It's far more valuable if it can also generate visualization images that make those patterns immediately obvious.

While matplotlib is the dominant Python charting library, it's complex and flexible to the point where directing an agent to use it directly often leads to inefficient approaches or verbose code. An agent asked to generate a chart might write dozens of lines of matplotlib setup code when a much simpler command-line tool would suffice.

Chartroom solves this by providing a deliberately constrained, agent-friendly charting interface. Instead of exposing matplotlib's full complexity, Chartroom offers specific chart types optimized for common use cases, accepting data in simple formats and producing publication-ready images with minimal configuration.

Chartroom's Core Features

Supported Chart Types: Chartroom currently supports four chart types that cover the vast majority of data visualization needs:

1. Bar charts: Ideal for comparing values across categories
2. Line charts: Perfect for showing trends over time or relationships
3. Scatter charts: Excellent for displaying correlations and distributions
4. Histograms: Great for understanding data distributions and frequencies

Each chart type can be customized through command-line options for titles, axis labels, and styling—but the defaults are sensible enough that many charts can be generated with minimal specification.

Simple Data Input: Chartroom accepts data from multiple sources:

echo 'name,value
Alice,42
Bob,28
Charlie,35
Diana,51
Eve,19' | uvx chartroom bar --csv \
  --title 'Sales by Person' --ylabel 'Sales'

This single command produces a professional-looking bar chart. Data can come from CSV files, TSV input, JSON, or directly from SQL queries against SQLite databases. The flexibility means agents can integrate Chartroom into existing data pipelines without complex data transformation.

Accessibility and Alt Text Generation

A particular strength of Chartroom is its thoughtful approach to accessibility. Every chart it generates includes automatically produced alt text describing the data, axes, and patterns. This isn't just good practice—it's essential when agents are creating documents that humans need to understand.

You can retrieve just the alt text for a chart:

echo 'name,value
Alice,42
Bob,28
Charlie,35
Diana,51
Eve,19' | uvx chartroom bar --csv \
  --title 'Sales by Person' --ylabel 'Sales' -f alt

This outputs: Sales by Person. Bar chart of value by name — Alice: 42, Bob: 28, Charlie: 35, Diana: 51, Eve: 19

Or request HTML or Markdown output directly, which includes both the image and proper alt text:

![Sales by Person. Bar chart of value by name — Alice: 42, Bob: 28, Charlie: 35, Diana: 51, Eve: 19](/path/to/chart.png)

This means agents can generate complete, accessible documentation without additional effort. The documents they produce work well for everyone, not just sighted users viewing on screens.

Styling and Customization

Chartroom includes support for different matplotlib style sheets, allowing agents to generate charts that match different visual preferences or branding requirements. A comprehensive demo document (itself built with Showboat and Chartroom) showcases all available styles, making it easy for agents to select appropriate styling.

The styling system demonstrates another important principle in the Showboat ecosystem: tools should be opinionated about defaults while remaining flexible for customization. Chartroom's default styling produces good-looking charts suitable for most purposes, but agents can easily apply different styles for specific needs.

How Chartroom Was Built: AI-Driven Development in Action

The creation of Chartroom perfectly exemplifies how Showboat and related tools enable rapid, AI-driven development. Rather than writing Chartroom manually, the creator used Claude Code for web with a specific development approach.

The workflow started with a clear specification written in a prompt:

We are building a Python CLI tool which uses matplotlib to generate a PNG image containing a chart. It will have multiple sub commands for different chart types, controlled by command line options. Everything you need to know to use it will be available in the single "chartroom --help" output.

It will accept data from files or standard input as CSV or TSV or JSON, similar to how sqlite-utils accepts data—clone simonw/sqlite-utils to /tmp for reference there. Clone matplotlib/matplotlib for reference as well

It will also accept data from --sql path/to/sqlite.db "select ..." which runs in read-only mode

Start by asking clarifying questions—do not use the ask user tool though it is broken—and generate a spec for me to approve

Once approved proceed using red/green TDD running tests with "uv run pytest"

Also while building maintain a demo/README.md document using the "uvx showboat --help" tool—each time you get a new chart type working commit the tests, implementation, root level README update and a new version of that demo/README.md document with an inline image demo of the new chart type (which should be a UUID image filename managed by the showboat image command and should be stored in the demo/ folder

Make sure "uv build" runs cleanly without complaining about extra directories but also ensure dist/ and uv.lock are in gitignore

This prompt accomplished several remarkable things simultaneously:

1. It established clear requirements without being overly prescriptive, allowing Claude Code to ask clarifying questions
2. It specified development methodology (red/green TDD with pytest)
3. It required documentation generation using Showboat itself, creating a feedback loop where the tool being built was used to document its own development
4. It set quality standards (clean builds, proper gitignore configuration)

Claude Code used this specification to generate the core implementation, then follow-up prompts and pull requests refined the tool further. The entire development process was dramatically accelerated because the agent could see its work in real-time through Showboat, and could iterate based on feedback provided while it was still working.

This approach—using Showboat to document agent development—creates a virtuous cycle. Agents produce better code because they're generating documentation that makes their decisions visible. Humans can provide more targeted feedback because they can see the intermediate results. The final products are better documented because documentation was created alongside the code rather than afterward.

The Growing Showboat Ecosystem: Composable Tools for Modern Development

Design Philosophy: Loose Coupling, Simple Conventions

The Showboat ecosystem currently consists of four primary tools:

1. Showboat: Core tool for creating documented code demonstrations
2. Rodney: CLI browser automation designed to work with Showboat
3. Chartroom: Chart generation designed to work with Showboat
4. datasette-showboat: Datasette plugin for streaming remote documents

Despite these tools having different purposes and implementations, they work together seamlessly. This isn't because of complex shared libraries or tightly-integrated architecture. Rather, it's because they follow simple, deliberate conventions:

• Image Convention: If a tool outputs a path to an image, Showboat can include it in a document
• Text Convention: Any tool that outputs text can be used with Showboat's note or exec commands
• Streaming Convention: Any tool can stream updates to the remote publishing endpoint

These loose conventions are far more powerful than tight integration would be. They allow tools to be developed independently, deployed separately, and versioned independently. A new tool can join the ecosystem simply by respecting the conventions—no coordination with the Showboat team is required.

Practical Synergies Between Tools

When Rodney (the browser automation tool built specifically for Showboat) combines with Showboat's image embedding capability, agents can create documents that demonstrate web interface interactions through screenshots. When Chartroom generates charts and Showboat embeds them as Markdown images, agents can produce complete data analysis documents with minimal manual intervention.

The most powerful examples emerge when multiple tools are combined. Consider a realistic workflow:

1. Claude Code uses Rodney to navigate to a web application and capture screenshots
2. The same session queries a SQLite database to extract data
3. Chartroom generates visualizations of that data with accessible alt text
4. Showboat documents the entire process, embedding screenshots and charts
5. datasette-showboat streams the developing document to a server in real-time
6. The human reviewing the work can provide feedback immediately, while the agent adjusts its approach

This workflow would require significant manual integration if each tool were designed in isolation. Because they're designed around simple conventions, it works naturally.

Future Expansion: The Extension Mechanism

The environment variable mechanism used for remote publishing (SHOWBOAT_REMOTE_URL) represents something more than just a document streaming feature. It's effectively a webhook extension mechanism for the entire Showboat ecosystem.

Currently, it's used primarily to stream documents somewhere else. But the same mechanism could support many other use cases that haven't been conceived yet:

• Notifications: Alerting you when agents complete specific milestones
• Quality gates: Automatically running tests or checks on generated documents
• Integration with other systems: Sending data to monitoring systems, project management tools, or data warehouses
• AI-driven workflows: Having documents trigger additional agent tasks based on their content

The beauty of this approach is that these capabilities don't require changes to Showboat itself. They're enabled by the extension mechanism that's already built in.

Connecting These Tools to Your Own Development Workflow

Setting Up Local Experimentation

The ecosystem is designed to be approachable for experimentation. Getting started requires just a few steps:

1. Start a datasette-showboat instance running locally
2. Set the environment variable in Claude Code for web pointing to your instance
3. Tell Claude Code to use Showboat in your prompts
4. Watch in real-time as the document builds

The friction of testing and iteration has been almost entirely eliminated. Rather than wondering if your tools work correctly, you can see them working as they develop.

Production Deployment Considerations

While local experimentation is simple, production deployment requires slightly more infrastructure:

• Host datasette-showboat somewhere accessible: Fly.io, AWS, Google Cloud, or any other environment where you can run a Python web application
• Configure HTTPS: Use proper TLS certificates for secure communication
• Set authentication tokens: Use strong, unique tokens for each deployment or use Datasette's built-in authentication
• Plan for storage: Consider how long you want to retain historical documents and plan database capacity accordingly

The good news is that Datasette handles much of this complexity. It's designed for production deployment and includes features like authentication, HTTPS support, and database management out of the box.

Integration with Existing Tools

The beauty of the Showboat ecosystem is that it doesn't require replacing existing tools. It adds new capabilities without disrupting existing workflows:

• Version control still works normally; agents can still commit their work to GitHub
• Local development is unaffected; Showboat and related tools are entirely optional
• CI/CD pipelines can incorporate Showboat outputs if desired, but don't require them
• Existing documentation systems can coexist with Showboat-generated documents

This non-disruptive approach makes adoption low-risk and gradual.

Conclusion

The Showboat ecosystem represents a fundamental shift in how AI agents can document and demonstrate their work. By combining real-time streaming (remote publishing), accessible viewing infrastructure (datasette-showboat), intelligent visualization (Chartroom), and browser automation (Rodney), developers now have tools to collaborate with agents in ways that were previously impossible.

The ecosystem's strength lies not in any single tool, but in how they work together through simple conventions. This approach makes the ecosystem extensible—new tools can be created and added without requiring coordination. It's also future-proof, as the underlying conventions remain stable even as individual tools evolve.

Whether you're using Claude Code for web, exploring data with Datasette, or building complex automation, the Showboat ecosystem provides practical tools that make AI-assisted development faster, more visible, and more collaborative. Start experimenting locally with datasette-showboat, try creating a simple Showboat document with Chartroom visualization, and you'll quickly see how these tools can transform your development workflow into something fundamentally more interactive and productive.

---

Original source: Two new Showboat tools: Chartroom and datasette-showboat

powered by osmu.app