showboat 0.6.1

Create executable documents that demonstrate an agent's work

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> '![alt](path)'   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 ![alt text](path). 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 '![Homepage screenshot](screenshot.png)'

  # 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
  ```

  ![screenshot](screenshot.png)

  ```bash {image}
  ![Homepage screenshot](screenshot.png)
  ```

  ![Homepage screenshot](screenshot.png)

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 '![Homepage screenshot](screenshot.png)'

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