showboat

README

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.

Usage

showboat init <file> <title>             Create a new demo document
showboat build <file> commentary [text]  Append commentary (text or stdin)
showboat build <file> run <lang> [code]  Run code and capture output
showboat build <file> image [script]     Run script, capture image output
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 build commands to recreate file

Build subcommands accept input from stdin when the text/code argument is omitted:

echo "Hello world" | showboat build demo.md commentary
cat script.sh | showboat build demo.md run bash

Global options

• --workdir <dir> — Set working directory for code execution (default: current)
• --version — Print version and exit
• --help, -h — Show help message

Build run output

The build run subcommand prints the captured shell output to stdout and exits with the same exit code as the executed command. This lets agents see what happened during execution and react to errors. The output is still appended to the document regardless of exit code.

$ showboat build demo.md run bash "echo hello && exit 1"
hello
$ echo $?
1

Popping entries

showboat pop removes the most recent entry from a document. For a run or image entry this removes both the code block and its output. For a commentary entry it removes the single commentary block.

This is useful when a build command produces an error that shouldn't remain in the document — the agent can inspect the output, decide the entry was a mistake, and pop it:

# A command fails
showboat build demo.md run bash "some-broken-command"

# Remove the failed entry from the document
showboat pop demo.md

Example

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

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

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

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

# Capture a screenshot
showboat build demo.md image "python screenshot.py http://localhost:8000"

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 showboat init and showboat build 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 build demo.md commentary 'First, let'\''s create a virtual environment.'
showboat build demo.md run bash 'python3 -m venv .venv && echo '\''Done'\'''
showboat build demo.md run 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

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