shellshare AGENTS.md

Using shellshare from scripts and AI agents

Contributing to this repository? See CLAUDE.md for build, lint, and test instructions. This file documents how to use shellshare programmatically — e.g. an AI agent sharing a live terminal with its user.

shellshare broadcasts a terminal session to a web link in one command. No signup, no configuration: run it, parse the link, hand the link to a human. Viewers see the terminal live in their browser, read-only.

Install

npx shellshare --help                    # no install (Node.js)
curl -sLo shellshare https://get.shellshare.net/ && chmod +x shellshare   # static binary (auto-detects OS)

Binaries exist for Linux x64/arm64, macOS x64/arm64, and Windows x64 (https://get.shellshare.net/?os=linux|linux-arm|mac|mac-arm|windows).

The machine-readable contract: --json

With --json, shellshare prints newline-delimited JSON events to stdout:

• First line, before any terminal output: {"event":"sharing","room":"<room>","server":"https://shellshare.net","url":"https://shellshare.net/r/<room>"}
• Last line: {"event":"end","exit_code":0}

Errors are printed to stderr as ERROR: ... and the process exits non-zero. Parse the url field from the first stdout line — that is the link to give to your user.

Recipes

Share one command and exit when it finishes (the usual agent case — e.g. let the user watch a long build, test run, or migration live):

shellshare exec --json -- npm test

exec runs the command in a PTY, streams it live, and exits with the command's exit code (a signal-killed command reports exit code 1). Note the -- separator before the command.

This works for commands that finish immediately, too — dmesg | shellshare --json leaves a working link after dmesg exits. You do not need to hold the process open with a sleep.

Stream a log or pipe (no PTY; a non-TTY stdin auto-detects this and reads stdin until EOF):

tail -f build.log | shellshare --json