{"id":47875394,"url":"https://github.com/davedev42/teleprompter","last_synced_at":"2026-05-10T19:10:33.596Z","repository":{"id":348571310,"uuid":"1188572655","full_name":"DaveDev42/teleprompter","owner":"DaveDev42","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-22T12:46:45.000Z","size":2725,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T13:33:27.887Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://teleprompter-flame.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaveDev42.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T09:20:49.000Z","updated_at":"2026-04-22T12:46:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DaveDev42/teleprompter","commit_stats":null,"previous_names":["davedev42/teleprompter"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/DaveDev42/teleprompter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fteleprompter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fteleprompter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fteleprompter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fteleprompter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaveDev42","download_url":"https://codeload.github.com/DaveDev42/teleprompter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveDev42%2Fteleprompter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32254714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T04:23:17.126Z","status":"ssl_error","status_checked_at":"2026-04-25T04:21:53.360Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T01:12:11.084Z","updated_at":"2026-05-10T19:10:33.571Z","avatar_url":"https://github.com/DaveDev42.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teleprompter\n\n[![CI](https://github.com/DaveDev42/teleprompter/actions/workflows/ci.yml/badge.svg)](https://github.com/DaveDev42/teleprompter/actions/workflows/ci.yml)\n[![Deploy Relay](https://github.com/DaveDev42/teleprompter/actions/workflows/deploy-relay.yml/badge.svg)](https://github.com/DaveDev42/teleprompter/actions/workflows/deploy-relay.yml)\n[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD_2--Clause-blue.svg)](./LICENSE)\n\nRemote Claude Code session controller with E2EE relay, dual Chat/Terminal UI, and voice input.\n\n## Quick Start\n\n### macOS (Homebrew)\n\n```bash\nbrew install davedev42/tap/tp\n```\n\n### macOS / Linux (curl)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DaveDev42/teleprompter/main/scripts/install.sh | bash\n```\n\n### Windows\n\nNative Windows is not supported. Run `tp` inside [WSL](https://learn.microsoft.com/windows/wsl/) using the Linux installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DaveDev42/teleprompter/main/scripts/install.sh | bash\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/DaveDev42/teleprompter.git\ncd teleprompter\npnpm install\npnpm build:cli:local    # → dist/tp\n```\n\n## Usage\n\n### Passthrough Mode (simplest)\n\nRun Claude Code through the teleprompter pipeline:\n\n```bash\ntp -p \"explain this code\"\ntp --tp-sid my-session -p \"fix the login bug\"\n```\n\n`--tp-*` flags are consumed by tp; everything else is forwarded to claude.\n\n### Connect Your Phone\n\n```bash\n# Generate pairing data (QR code) — default relay: wss://relay.tpmt.dev\ntp pair\n\n# Or use a custom relay\ntp pair --relay wss://relay.example.com\n```\n\nScan the QR code with the Teleprompter app (iOS TestFlight / Android Internal / [tpmt.dev](https://tpmt.dev)). The app connects to your daemon **through the relay** with end-to-end encryption — no direct local connection.\n\n### Auto-start on Login\n\n```bash\ntp daemon install      # macOS launchd / Linux systemd\ntp daemon uninstall    # Remove\n```\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `tp` | Run Claude through tp pipeline (default — bare invocation drops you into Claude) |\n| `tp [flags] [claude args]` | Run Claude with passthrough args (e.g. `tp -p \"...\"`, `tp --model sonnet`) |\n| `tp -- \u003cclaude args\u003e` | Forward args directly to claude, bypassing the daemon |\n| `tp --help` / `-h` | Print tp's banner, then `claude --help` underneath |\n| `tp --version` / `-v` | Print tp + claude versions (same as `tp version`) |\n| `tp pair [--relay URL] [--label NAME]` | Generate QR pairing data (alias for `tp pair new`) |\n| `tp pair list` | List registered pairings (label + daemon ID) |\n| `tp pair rename \u003cid-prefix\u003e \u003clabel...\u003e` | Rename a pairing (notifies peer) |\n| `tp pair delete \u003cid\u003e [-y]` | Delete a pairing (daemon-id prefix accepted) |\n| `tp session list` | List stored sessions (running + stopped) |\n| `tp session delete \u003csid\u003e [-y]` | Delete a session (sid prefix accepted) |\n| `tp session prune [--older-than 7d] [--all] [--dry-run] [-y]` | Bulk-delete stopped sessions |\n| `tp status` | Show daemon status and sessions |\n| `tp logs [session]` | Tail live session output |\n| `tp doctor` | Environment diagnostics + relay E2EE check, then runs `claude doctor` |\n| `tp upgrade` | Upgrade tp binary, then runs `claude update` |\n| `tp version` | Print tp + claude versions |\n| `tp daemon start [opts]` | Start daemon in foreground |\n| `tp daemon install` | Register as OS service (launchd / systemd) |\n| `tp daemon uninstall` | Remove OS service |\n| `tp relay start [--port]` | Start a relay server (self-hosted) |\n| `tp completions \u003cbash\\|zsh\\|fish\u003e` | Print shell completion script |\n| `tp completions install [shell]` | Install completion into the current shell rc / profile |\n| `tp completions uninstall [shell]` | Remove installed completion |\n| `tp auth` / `mcp` / `install` / `update` / `agents` / `auto-mode` / `plugin` / `setup-token` | Forward to `claude` (daemon bypass) |\n\n## Architecture\n\n```\nRunner ──IPC──→ Daemon ──WSS (E2EE)──→ Relay ──WSS (E2EE)──→ App\n (PTY)          (Store)                (forwarder)           (Expo)\n```\n\n- **Runner**: Spawns Claude Code in a PTY, collects io streams and hooks events, communicates with Daemon via IPC (Unix domain socket)\n- **Daemon**: Manages sessions, stores records, encrypts with libsodium per-frontend keys, connects to Relay(s) as a client\n- **Relay**: Stateless ciphertext forwarder (zero-trust, 10 encrypted frames cached per session). Never sees plaintext.\n- **App**: Expo app (iOS/Web/Android) with Chat + Terminal + Voice UI. Connects to paired daemon(s) via Relay only.\n\n**All frontend↔daemon traffic flows through the Relay with E2EE.** Daemon does not run a WebSocket server; the App does not connect directly to the Daemon. Pairing (QR/JSON) delivers the Daemon's public key and relay URL offline; frontend pubkey is exchanged in-band via `relay.kx`.\n\n## Monorepo Structure\n\n```\napps/\n  cli/            # Unified `tp` binary\n  app/            # Expo app (iOS + Web + Android)\npackages/\n  daemon/         # Session management, Store, IPC server, Relay client\n  runner/         # PTY management, hooks collection\n  relay/          # WebSocket ciphertext relay\n  protocol/       # Shared types, codec, crypto, pairing\n  tsconfig/       # Shared TypeScript configs\nscripts/\n  build.ts        # Multi-platform bun build --compile\n  install.sh      # curl-pipe-sh installer (macOS/Linux; Windows users run under WSL)\n```\n\n## Development\n\n```bash\npnpm install\n\n# Run all bun:test suites across the workspace (unit + integration)\npnpm test\n\n# Run Playwright E2E specs (CI subset — daemon-free)\npnpm test:e2e:ci\n\n# Run Playwright E2E specs (local — full, includes real-daemon flows)\npnpm test:e2e\n\n# Type check every workspace package\npnpm type-check:all\n\n# Build CLI binary\npnpm build:cli:local    # current platform\npnpm build:cli          # every release target (see scripts/build.ts TARGETS)\n\n# Frontend dev server\npnpm dev:app\n\n# Build frontend for production\npnpm build:web\n\n# Environment diagnostics\npnpm doctor\n```\n\n## Key Technologies\n\n- **TypeScript** — single stack across all components\n- **Bun** — runtime for Runner, Daemon, Relay\n- **Expo** — React Native + Web frontend\n- **libsodium** — X25519 key exchange + XChaCha20-Poly1305 AEAD encryption\n- **ghostty-web** — terminal rendering (libghostty WASM, Canvas 2D)\n- **OpenAI Realtime API** — voice input/output with STT + TTS\n\n## Security\n\n- End-to-end encrypted (E2EE) communication\n- QR-based pairing with X25519 ECDH key exchange\n- Per-session ephemeral key ratchet\n- Relay sees only ciphertext (zero-trust)\n- API keys stored in OS Keychain/Keystore (native) or localStorage (web)\n\n## Documentation\n\n- [Getting Started](./docs/GETTING-STARTED.md) — installation, first session, phone pairing, and app walkthrough\n- [FAQ](./docs/FAQ.md) — Installation, connection, sessions, daemon, voice, upgrading, and development\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for release notes.\n\n## Verifying downloads\n\nAll release binaries are built in GitHub Actions from tagged commits. You can verify three layers of integrity:\n\n### 1. Checksum (basic)\n\n```bash\n# Download the binary and checksums\ncurl -fsSL -O https://github.com/DaveDev42/teleprompter/releases/download/vX.Y.Z/tp-linux_x64\ncurl -fsSL -O https://github.com/DaveDev42/teleprompter/releases/download/vX.Y.Z/checksums.txt\n\n# Verify (Linux)\nsha256sum --check --ignore-missing checksums.txt\n# Verify (macOS)\nshasum -a 256 --check --ignore-missing checksums.txt\n```\n\n### 2. Cosign keyless signature (recommended)\n\nVerifies that `checksums.txt` was signed by this repo's CI workflow. Protects against a compromised GitHub account re-uploading a doctored `checksums.txt`.\n\nInstall [cosign](https://docs.sigstore.dev/cosign/installation/), then:\n\n```bash\ncurl -fsSL -O https://github.com/DaveDev42/teleprompter/releases/download/vX.Y.Z/checksums.txt\ncurl -fsSL -O https://github.com/DaveDev42/teleprompter/releases/download/vX.Y.Z/checksums.txt.sig\ncurl -fsSL -O https://github.com/DaveDev42/teleprompter/releases/download/vX.Y.Z/checksums.txt.pem\n\ncosign verify-blob \\\n  --certificate checksums.txt.pem \\\n  --signature checksums.txt.sig \\\n  --certificate-identity-regexp 'https://github.com/DaveDev42/teleprompter/\\.github/workflows/release\\.yml@.*' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n  checksums.txt\n```\n\nExpected: `Verified OK`. Then run the checksum check from step 1.\n\n### 3. SLSA build provenance (advanced)\n\nEvery binary has a GitHub-native attestation linking it to the exact commit and workflow run that built it. Requires [GitHub CLI](https://cli.github.com/).\n\n```bash\ngh attestation verify tp-linux_x64 --owner DaveDev42\n```\n\n## License\n\n[BSD 2-Clause](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavedev42%2Fteleprompter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavedev42%2Fteleprompter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavedev42%2Fteleprompter/lists"}