shellshare: Instructions file for Codex

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