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
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.
Usage:
showboat init <file> <title> Create a new demo document
showboat note <file> [text] Append commentary (text or stdin)
showboat exec <file> <lang> [code] Run code and capture output
showboat image <file> <path> Copy image into document
showboat image <file> '' Copy image with alt text
showboat pop <file> Remove the most recent entry
showboat verify <file> [--output <new>] Re-run and diff all code blocks
showboat extract <file> [--filename <name>] Emit commands to recreate file
Global Options:
--workdir <dir> Set working directory for code execution (default: current)
--version Print version and exit
--help, -h Show this help message
Exec output:
The "exec" command prints the captured shell output to stdout and exits with
the same exit code as the executed command. This lets agents see what happened
and react to errors. The output is still appended to the document regardless
of exit code. Use "pop" to remove a failed entry.
$ showboat exec demo.md bash "echo hello && exit 1"
hello
$ echo $?
1
Image:
The "image" command accepts a path to an image file or a markdown image
reference of the form . The image is copied into the same
directory as the document with a generated filename and an image reference is
appended to the markdown. When a markdown reference is provided the alt text
is preserved; otherwise it is derived from the generated filename.
Pop:
The "pop" command removes the most recent entry from a document. For an "exec"
or "image" entry this removes both the code block and its output. For a "note"
entry it removes the single commentary block. This is useful when a command
produces an error that shouldn't remain in the document.
Verify:
Re-runs every code block (skipping image blocks) and compares actual output
against the recorded output. Prints diffs and exits with code 1 if any output
has changed; exits 0 if everything matches. Use --output <file> to write an
updated copy of the document with the new outputs without modifying the
original.
Extract:
Parses a document and prints the sequence of showboat CLI commands (one per
line) that would recreate it from scratch. Output blocks are omitted since
they are regenerated by "exec". Use --filename <name> to substitute a
different filename in the emitted commands.
Stdin:
Commands accept input from stdin when the text/code argument is omitted.
For example:
echo "Hello world" | showboat note demo.md
cat script.sh | showboat exec demo.md bash
Example:
# 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 (output is printed to stdout)
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')"
# Oops, wrong command — remove the last entry from the document
showboat pop demo.md
# Redo it correctly
showboat exec demo.md python3 "print('Hello from Python')"
# Add a screenshot
showboat image demo.md screenshot.png
# Add a screenshot with alt text
showboat image demo.md ''
# Verify the demo still works
showboat verify demo.md
# See what commands built the demo
showboat extract demo.md
Resulting markdown format:
# 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
```
```python3
print('Hello from Python')
```
```output
Hello from Python
```
```bash {image}
screenshot.png
```
```bash {image}
```
Example
# 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:
# 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:
<!-- showboat-id: 550e8400-e29b-41d4-a716-446655440000 -->
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
