shellshare: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Shellshare is a live terminal broadcasting tool that allows users to share their terminal session via web links. The project is a complete Rust rewrite providing both client and server in a single binary.

Build & Development Commands

# Build
make build                     # Same as above

# Lint (pedantic clippy lints are enabled)
make lint                      # Both clippy + check

# Run locally
cargo run -- server            # Start server on 0.0.0.0:3000
cargo run -- server --port 8080 --host 127.0.0.1
cargo run -- --server http://localhost:3000  # Run client
cargo run -- serve             # Share via a local server on localhost:3000

# E2E tests (Python + Playwright)
# Requires a release binary: the suite starts its own servers from it
cargo build --release
cd e2e && uv sync && uv run pytest -n 10

Architecture

Dual-mode binary: shellshare operates as client (default) or server (shellshare server). shellshare serve combines both: it boots the embedded server on a background thread (default localhost:3000, configurable via --host/--port) and runs the client against it, sharing the terminal with no external server. Both serve and server accept --tunnel (src/tunnel.rs): it spawns the user's pre-installed cloudflared against the local server, waits for the https://*.trycloudflare.com URL from its stderr banner, and uses it as the share link (the broadcaster still talks to localhost); missing cloudflared is a fatal error pointing at the install docs, and the tunnel process dies with shellshare.

Scripting surface: shellshare exec -- <cmd> runs one command in the PTY (instead of a shell), broadcasts it, and exits with the command's exit code. The global --json flag switches stdout to newline-delimited JSON events: first one with event sharing (parse its url field), last {"event":"end","exit_code":N} (errors stay on stderr as ERROR: ...). This contract is documented in AGENTS.md and templates/llms.txt and covered by e2e/test_agents.py - the three must stay in lockstep.