[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74653":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":13,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},74653,"showboat","simonw\u002Fshowboat","simonw","Create executable documents that demonstrate an agent's work",null,"Go",1160,44,4,13,0,10,60,12,17.96,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:03:26","# Showboat\n\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fshowboat.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fshowboat\u002F)\n[![Changelog](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fsimonw\u002Fshowboat?include_prereleases&label=changelog)](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat\u002Freleases)\n[![Tests](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat\u002Factions\u002Fworkflows\u002Ftest.yml)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg)](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat\u002Fblob\u002Fmain\u002FLICENSE)\n\nCreate executable demo documents that show and prove an agent's work.\n\nShowboat 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.\n\n## Example\n\nHere's [an example Showboat demo document](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat-demos\u002Fblob\u002Fmain\u002Fshot-scraper\u002FREADME.md) that demonstrates [shot-scraper](https:\u002F\u002Fgithub.com\u002Fshot-scraper). It was created by Claude Code, as shown by [this transcript](https:\u002F\u002Fgisthost.github.io\u002F?29b0d0ebef50c57e7985a6004aad01c4\u002Fpage-001.html#msg-2026-02-06T07-33-41-296Z).\n\n## Installation\n\nThis Go tool can be installed directly [from PyPI](https:\u002F\u002Fpypi.org\u002Fproject\u002Fshowboat\u002F) using `pip` or `uv`.\n\nYou can run it without installing it first using `uvx`:\n\n```bash\nuvx showboat --help\n```\nOr install it like this, then run `showboat --help`:\n```bash\nuv tool install showboat\n# or\npip install showboat\n```\n\nYou can also install the Go binary directly:\n```bash\ngo install github.com\u002Fsimonw\u002Fshowboat@latest\n```\nOr run it without installation like this:\n```bash\ngo run github.com\u002Fsimonw\u002Fshowboat@latest --help\n```\nCompiled binaries are available [on the releases page](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat\u002Freleases). On macOS you may need to [follow these extra steps](https:\u002F\u002Fsupport.apple.com\u002Fen-us\u002F102445) to use those.\n\n## Help\n\n\u003C!-- [[[cog\nimport cog\nimport subprocess\nresult = subprocess.run([\"go\", \"run\", \".\", \"--help\"], capture_output=True, text=True)\ncog.out(\n    \"````\\n{}\\n````\\n\".format(result.stdout.strip())\n)\n]]] -->\n````\nshowboat - Create executable demo documents that show and prove an agent's work.\n\nShowboat helps agents build markdown documents that mix commentary, executable\ncode blocks, and captured output. These documents serve as both readable\ndocumentation and reproducible proof of work. A verifier can re-execute all\ncode blocks and confirm the outputs still match.\n\nUsage:\n  showboat init \u003Cfile> \u003Ctitle>             Create a new demo document\n  showboat note \u003Cfile> [text]              Append commentary (text or stdin)\n  showboat exec \u003Cfile> \u003Clang> [code]       Run code and capture output\n  showboat image \u003Cfile> \u003Cpath>             Copy image into document\n  showboat image \u003Cfile> '![alt](path)'   Copy image with alt text\n  showboat pop \u003Cfile>                      Remove the most recent entry\n  showboat verify \u003Cfile> [--output \u003Cnew>]  Re-run and diff all code blocks\n  showboat extract \u003Cfile> [--filename \u003Cname>]  Emit commands to recreate file\n\nGlobal Options:\n  --workdir \u003Cdir>   Set working directory for code execution (default: current)\n  --version         Print version and exit\n  --help, -h        Show this help message\n\nExec output:\n  The \"exec\" command prints the captured shell output to stdout and exits with\n  the same exit code as the executed command. This lets agents see what happened\n  and react to errors. The output is still appended to the document regardless\n  of exit code. Use \"pop\" to remove a failed entry.\n\n    $ showboat exec demo.md bash \"echo hello && exit 1\"\n    hello\n    $ echo $?\n    1\n\nImage:\n  The \"image\" command accepts a path to an image file or a markdown image\n  reference of the form ![alt text](path). The image is copied into the same\n  directory as the document with a generated filename and an image reference is\n  appended to the markdown. When a markdown reference is provided the alt text\n  is preserved; otherwise it is derived from the generated filename.\n\nPop:\n  The \"pop\" command removes the most recent entry from a document. For an \"exec\"\n  or \"image\" entry this removes both the code block and its output. For a \"note\"\n  entry it removes the single commentary block. This is useful when a command\n  produces an error that shouldn't remain in the document.\n\nVerify:\n  Re-runs every code block (skipping image blocks) and compares actual output\n  against the recorded output. Prints diffs and exits with code 1 if any output\n  has changed; exits 0 if everything matches. Use --output \u003Cfile> to write an\n  updated copy of the document with the new outputs without modifying the\n  original.\n\nExtract:\n  Parses a document and prints the sequence of showboat CLI commands (one per\n  line) that would recreate it from scratch. Output blocks are omitted since\n  they are regenerated by \"exec\". Use --filename \u003Cname> to substitute a\n  different filename in the emitted commands.\n\nStdin:\n  Commands accept input from stdin when the text\u002Fcode argument is omitted.\n  For example:\n    echo \"Hello world\" | showboat note demo.md\n    cat script.sh | showboat exec demo.md bash\n\nExample:\n  # Create a demo\n  showboat init demo.md \"Setting Up a Python Project\"\n\n  # Add commentary\n  showboat note demo.md \"First, let's create a virtual environment.\"\n\n  # Run a command and capture output (output is printed to stdout)\n  showboat exec demo.md bash \"python3 -m venv .venv && echo 'Done'\"\n\n  # Run Python and capture output\n  showboat exec demo.md python \"print('Hello from Python')\"\n\n  # Oops, wrong command — remove the last entry from the document\n  showboat pop demo.md\n\n  # Redo it correctly\n  showboat exec demo.md python3 \"print('Hello from Python')\"\n\n  # Add a screenshot\n  showboat image demo.md screenshot.png\n\n  # Add a screenshot with alt text\n  showboat image demo.md '![Homepage screenshot](screenshot.png)'\n\n  # Verify the demo still works\n  showboat verify demo.md\n\n  # See what commands built the demo\n  showboat extract demo.md\n\nResulting markdown format:\n\n  # Setting Up a Python Project\n\n  *2026-02-06T15:30:00Z*\n\n  First, let's create a virtual environment.\n\n  ```bash\n  python3 -m venv .venv && echo 'Done'\n  ```\n\n  ```output\n  Done\n  ```\n\n  ```python3\n  print('Hello from Python')\n  ```\n\n  ```output\n  Hello from Python\n  ```\n\n  ```bash {image}\n  screenshot.png\n  ```\n\n  ![screenshot](screenshot.png)\n\n  ```bash {image}\n  ![Homepage screenshot](screenshot.png)\n  ```\n\n  ![Homepage screenshot](screenshot.png)\n````\n\u003C!-- [[[end]]] -->\n\n## Example\n\n```bash\n# Create a demo\nshowboat init demo.md \"Setting Up a Python Project\"\n\n# Add commentary\nshowboat note demo.md \"First, let's create a virtual environment.\"\n\n# Run a command and capture output\nshowboat exec demo.md bash \"python3 -m venv .venv && echo 'Done'\"\n\n# Run Python and capture output\nshowboat exec demo.md python \"print('Hello from Python')\"\n\n# Add a screenshot\nshowboat image demo.md screenshot.png\n\n# Add a screenshot with alt text\nshowboat image demo.md '![Homepage screenshot](screenshot.png)'\n```\n\nThis produces a markdown file like:\n\n````markdown\n# Setting Up a Python Project\n\n*2026-02-06T15:30:00Z*\n\nFirst, let's create a virtual environment.\n\n```bash\npython3 -m venv .venv && echo 'Done'\n```\n\n```output\nDone\n```\n\n```python\nprint('Hello from Python')\n```\n\n```output\nHello from Python\n```\n````\n\n## Verifying\n\n`showboat verify` re-executes every code block in a document and checks that the outputs still match:\n\n```bash\nshowboat verify demo.md\n```\n\n## Extracting\n\n`showboat extract` emits the sequence of commands that would recreate a document from scratch:\n\n```bash\nshowboat extract demo.md\n```\n\nFor the example above this would output:\n\n```\nshowboat init demo.md 'Setting Up a Python Project'\nshowboat note demo.md 'First, let'\\''s create a virtual environment.'\nshowboat exec demo.md bash 'python3 -m venv .venv && echo '\\''Done'\\'''\nshowboat exec demo.md python 'print('\\''Hello from Python'\\'')'\n```\n\nBy default the commands reference the original filename. Use `--filename` to substitute a different filename in the emitted commands:\n\n```bash\nshowboat extract demo.md --filename copy.md\n```\n\n## Remote Document Streaming\n\nWhen 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.\n\nEach 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:\n\n```\n\u003C!-- showboat-id: 550e8400-e29b-41d4-a716-446655440000 -->\n```\n\n### Configuration\n\nSet the environment variable to your receiver's URL:\n\n```bash\nexport SHOWBOAT_REMOTE_URL=https:\u002F\u002Fwww.example.com\u002Fshowboat\n```\n\nAuthentication can be handled by an optional query string argument:\n\n```bash\nexport SHOWBOAT_REMOTE_URL=https:\u002F\u002Fwww.example.com\u002Fshowboat?token=secret-token-here\n```\n\nRemote 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.\n\n### POST Body Format\n\nAll POSTs use `application\u002Fx-www-form-urlencoded` except `image`, which uses `multipart\u002Fform-data`. Every POST includes `uuid` and `command` fields.\n\n| Command | Content-Type | Form Fields |\n| --- | --- | --- |\n| `init` | `application\u002Fx-www-form-urlencoded` | `uuid`, `command=init`, `title` |\n| `note` | `application\u002Fx-www-form-urlencoded` | `uuid`, `command=note`, `markdown` |\n| `exec` | `application\u002Fx-www-form-urlencoded` | `uuid`, `command=exec`, `language`, `input`, `output` |\n| `image` | `multipart\u002Fform-data` | `uuid`, `command=image`, `input`, `alt`, `image` (file upload) |\n| `pop` | `application\u002Fx-www-form-urlencoded` | `uuid`, `command=pop` |\n\nFor `exec`, `language` is the interpreter name (e.g. `bash`, `python3`), `input` is the source code, and `output` is the captured stdout\u002Fstderr. For `image`, the `image` field is the copied image file. For `note`, `markdown` contains the rendered markdown of the commentary block.\n\n## Building the Python wheels\n\nThe Python wheel versions are built using [go-to-wheel](https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fgo-to-wheel):\n\n```bash\nuvx go-to-wheel . \\\n  --readme README.md \\\n  --description \"Create executable documents that demonstrate an agent's work\" \\\n  --author 'Simon Willison' \\\n  --license Apache-2.0 \\\n  --url https:\u002F\u002Fgithub.com\u002Fsimonw\u002Fshowboat \\\n  --set-version-var main.version \\\n  --version 0.1.0\n```\n","Showboat 是一个用于创建可执行文档的工具，旨在展示和验证代理的工作成果。它支持在Markdown文档中混合编写注释、可执行代码块以及捕获输出，使得这些文档既作为易读的说明材料，又充当了工作结果的可重现证明。任何验证者都可以重新执行其中的所有代码块，并确认输出是否仍然匹配。项目使用Go语言开发，但也可以通过Python的pip包管理器安装，这为不同技术背景的用户提供了便利。Showboat非常适合需要向他人演示软件功能或算法效果的场景，如教育、技术分享、或是产品功能介绍等。",2,"2026-06-11 03:50:18","high_star"]