showboat

Showboat

Create executable demo documents that show and prove an agent's work.

Showboat helps agents build markdown documents that mix commentary, executable code blocks, and captured output. These documents serve as both readable documentation and reproducible proof of work. A verifier can re-execute all code blocks and confirm the outputs still match.

Example

Here's an example Showboat demo document that demonstrates shot-scraper. It was created by Claude Code, as shown by this transcript.

Installation

This Go tool can be installed directly from PyPI using pip or uv.

You can run it without installing it first using uvx:

uvx showboat --help

Or install it like this, then run showboat --help:

uv tool install showboat
# or
pip install showboat

You can also install the Go binary directly:

go install github.com/simonw/showboat@latest

Or run it without installation like this:

go run github.com/simonw/showboat@latest --help

Compiled binaries are available on the releases page. On macOS you may need to follow these extra steps to use those.

Help

…

bash python3 -m venv .venv && echo 'Done'

```output
Done

print('Hello from Python')

Hello from Python

screenshot.png

## Example

```bash
# Create a demo
showboat init demo.md "Setting Up a Python Project"

# Add commentary
showboat note demo.md "First, let's create a virtual environment."

# Run a command and capture output
showboat exec demo.md bash "python3 -m venv .venv && echo 'Done'"

# Run Python and capture output
showboat exec demo.md python "print('Hello from Python')"

# Add a screenshot
showboat image demo.md screenshot.png

# Add a screenshot with alt text
showboat image demo.md ''
```

This produces a markdown file like:

````markdown
# Setting Up a Python Project

*2026-02-06T15:30:00Z*

First, let's create a virtual environment.

```bash
python3 -m venv .venv && echo 'Done'
```

```output
Done
```

```python
print('Hello from Python')
```

```output
Hello from Python
```

Verifying

showboat verify re-executes every code block in a document and checks that the outputs still match:

showboat verify demo.md

Extracting

showboat extract emits the sequence of commands that would recreate a document from scratch:

showboat extract demo.md

For the example above this would output:

showboat init demo.md 'Setting Up a Python Project'
showboat note demo.md 'First, let'\''s create a virtual environment.'
showboat exec demo.md bash 'python3 -m venv .venv && echo '\''Done'\'''
showboat exec demo.md python 'print('\''Hello from Python'\'')'

By default the commands reference the original filename. Use --filename to substitute a different filename in the emitted commands:

showboat extract demo.md --filename copy.md

Remote Document Streaming

When the SHOWBOAT_REMOTE_URL environment variable is set, each init, note, exec, image, and pop command will POST its content to the specified URL. This enables real-time streaming of document updates to a remote viewer as the document is built.

Each document created with showboat init receives a UUID that ties all subsequent commands together into a single document stream. The UUID is stored as an HTML comment in the markdown:

Configuration

Set the environment variable to your receiver's URL:

export SHOWBOAT_REMOTE_URL=https://www.example.com/showboat

Authentication can be handled by an optional query string argument:

export SHOWBOAT_REMOTE_URL=https://www.example.com/showboat?token=secret-token-here

Remote POST errors are printed as warnings to stderr but never fail the main command. If the URL is unset or empty, no POSTs are made.

POST Body Format

All POSTs use application/x-www-form-urlencoded except image, which uses multipart/form-data. Every POST includes uuid and command fields.

Command	Content-Type	Form Fields
init	application/x-www-form-urlencoded	uuid, command=init, title
note	application/x-www-form-urlencoded	uuid, command=note, markdown
exec	application/x-www-form-urlencoded	uuid, command=exec, language, input, output
image	multipart/form-data	uuid, command=image, input, alt, image (file upload)
pop	application/x-www-form-urlencoded	uuid, command=pop

For exec, language is the interpreter name (e.g. bash, python3), input is the source code, and output is the captured stdout/stderr. For image, the image field is the copied image file. For note, markdown contains the rendered markdown of the commentary block.

Building the Python wheels

The Python wheel versions are built using go-to-wheel:

uvx go-to-wheel . \
  --readme README.md \
  --description "Create executable documents that demonstrate an agent's work" \
  --author 'Simon Willison' \
  --license Apache-2.0 \
  --url https://github.com/simonw/showboat \
  --set-version-var main.version \
  --version 0.1.0