{"_id":"@denifia/copilot-uplink","name":"@denifia/copilot-uplink","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@denifia/copilot-uplink","version":"1.0.2","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/denifia/copilot-uplink.git"},"engines":{"node":">=22.14.0"},"bin":{"copilot-uplink":"dist/bin/cli.js"},"scripts":{"dev":"vite","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","build":"npm run clean && tsc -p tsconfig.server.json && vite build","prepack":"npm run build","test":"vitest run","test:watch":"vitest","test:e2e":"playwright test","test:all":"npm run lint:css && npm run build && npm test && npm run test:e2e","lint:css":"stylelint \"src/**/*.css\""},"dependencies":{"@fontsource/jetbrains-mono":"^5.2.8","@preact/signals":"^2.8.1","commander":"^14.0.3","debug":"^4.4.3","express":"^5.2.1","highlight.js":"^11.11.1","marked":"^17.0.3","material-symbols":"^0.40.2","preact":"^10.28.4","qrcode-terminal":"^0.12.0","ws":"^8.18.0"},"devDependencies":{"@playwright/test":"^1.58.2","@preact/preset-vite":"^2.10.3","@testing-library/jest-dom":"^6.9.1","@testing-library/preact":"^3.2.4","@types/debug":"^4.1.12","@types/express":"^5.0.0","@types/node":"^22.10.0","@types/ws":"^8.5.13","@vitest/coverage-v8":"^4.0.18","jsdom":"^28.1.0","stylelint":"^17.4.0","stylelint-config-standard":"^40.0.0","stylelint-declaration-strict-value":"^1.11.1","tsx":"^4.8.1","typescript":"^5.7.0","vite":"^7.3.1","vitest":"^4.0.18"},"gitHead":"9171f6749e149165d73c0375a5f5267df56fe329","_id":"@denifia/copilot-uplink@1.0.2","description":"**Remote control for GitHub Copilot CLI from your phone or any browser.**","bugs":{"url":"https://github.com/denifia/copilot-uplink/issues"},"homepage":"https://github.com/denifia/copilot-uplink#readme","_nodeVersion":"25.7.0","_npmVersion":"11.10.1","dist":{"integrity":"sha512-fF/Kdn7c2wyRhiSWHn0w7MY/MWpIs+vHL9I/ArncZYktKsXsWERww4ycKw4Mzh7VT6pRJzyYE/Z1TbzYU620dw==","shasum":"118c15c5c5f48b197751f469ca84979eac55a139","tarball":"https://registry.npmjs.org/@denifia/copilot-uplink/-/copilot-uplink-1.0.2.tgz","fileCount":43,"unpackedSize":4350102,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDinbPIANyYrbDIRUZNqK5mkLN6aGmYwCsonfsZlYAvogIgX3C4MQI1LfojVYQ9WjTEcsU/5bvpG+/qqzkXHP+uGRY="}]},"_npmUser":{"name":"denifia","email":"mr.l.wale@gmail.com"},"directories":{},"maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/copilot-uplink_1.0.2_1773835483551_0.19409963929680485"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T12:04:43.442Z","1.0.2":"2026-03-18T12:04:43.850Z","modified":"2026-03-18T12:04:44.009Z"},"maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"description":"**Remote control for GitHub Copilot CLI from your phone or any browser.**","homepage":"https://github.com/denifia/copilot-uplink#readme","repository":{"type":"git","url":"git+https://github.com/denifia/copilot-uplink.git"},"bugs":{"url":"https://github.com/denifia/copilot-uplink/issues"},"license":"MIT","readme":"# <img src=\"src/client/public/icon.svg\" alt=\"orbit\" width=\"28\" height=\"28\" /> Copilot Uplink\r\n\r\n**Remote control for GitHub Copilot CLI from your phone or any browser.**\r\n\r\n[![Build](https://img.shields.io/github/actions/workflow/status/denifia/copilot-uplink/ci.yml?branch=main)](https://github.com/denifia/copilot-uplink/actions)\r\n[![npm](https://img.shields.io/npm/v/@denifia/copilot-uplink)](https://www.npmjs.com/package/@denifia/copilot-uplink)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\r\n\r\n## Quick Start\r\n\r\n```bash\r\ncd ~/your/project/\r\n\r\n# With remote access via devtunnel\r\nnpx @denifia/copilot-uplink@latest --tunnel\r\n```\r\n\r\n## What Is This?\r\n\r\nCopilot Uplink gives you a full chat interface to GitHub Copilot CLI from your phone, a tablet, or any browser.\r\n\r\nA lightweight Node.js bridge spawns `copilot --acp --stdio` as a child process, translates between WebSocket and NDJSON\r\n(the ACP wire format), and serves a Progressive Web App that renders streaming responses, tool calls, permissions, and\r\nagent plans. Add a Microsoft Dev Tunnel and the whole thing is reachable from anywhere.\r\n\r\n```mermaid\r\ngraph LR\r\n    PWA[\"PWA Client<br/>(browser)\"] <-->|\"HTTPS / WSS<br/>via devtunnel\"| Bridge[\"Bridge Server<br/>(Node.js)\"]\r\n    Bridge <-->|\"stdio / NDJSON<br/>child process\"| Copilot[\"copilot --acp<br/>--stdio\"]\r\n    Bridge -.-|\"Serves PWA static files<br/>+ WebSocket endpoint\"| PWA\r\n```\r\n\r\n## Features\r\n\r\n- 💬 **Chat** with streaming responses\r\n- 🔧 **Tool call visibility** — see reads, edits, executes, and more with kind icons and status\r\n- 🔐 **Permission approve / deny** — surface permission requests with option buttons\r\n- 📋 **Agent plan tracking** — view plan entries with priority and status\r\n- 📱 **PWA** — installable on your phone's home screen\r\n- 🌐 **Remote access** via Microsoft Dev Tunnel\r\n- 🔄 **Auto-reconnect** with exponential backoff (1 s → 30 s max)\r\n- 🌙 **Dark / light theme**\r\n\r\n<p align=\"center\">\r\n  <img src=\"docs/demo.gif\" alt=\"Uplink demo - chat, model switching, and plan mode\" width=\"300\" />\r\n</p>\r\n\r\n## Installing Dev Tunnels\r\n\r\nDev Tunnels are required for remote access (`--tunnel`). Install for your platform:\r\n\r\n### macOS\r\n\r\n```bash\r\nbrew install --cask devtunnel\r\n```\r\n\r\n### Linux\r\n\r\n```bash\r\ncurl -sL https://aka.ms/DevTunnelCliInstall | bash\r\n```\r\n\r\n### Windows\r\n\r\n```powershell\r\nwinget install Microsoft.devtunnel\r\n```\r\n\r\nAfter installing, authenticate once:\r\n\r\n```bash\r\ndevtunnel user login\r\n```\r\n\r\n## Getting the PWA on Your Phone\r\n\r\n1. **Start with tunnel:**\r\n   ```bash\r\n   npx @denifia/copilot-uplink@latest --tunnel\r\n   ```\r\n2. **Scan the QR code** printed in your terminal with your phone's camera.\r\n3. **Add to Home Screen** — your browser will offer an \"Install\" or \"Add to Home Screen\" prompt because the app ships a\r\n   Web App Manifest and Service Worker.\r\n\r\nThe tunnel URL is **stable per project** — Uplink derives a deterministic tunnel name from your working directory and\r\nreuses it on every run. The installed PWA always connects to the same URL. If the bridge is offline the cached app shell\r\nstill opens instantly; it shows a reconnection banner and retries automatically.\r\n\r\n### Using Your Own Tunnel\r\n\r\nIf you need explicit control over the tunnel name (e.g., sharing a stable URL across machines), create\r\na tunnel yourself and hand it to Uplink:\r\n\r\n```bash\r\n# One-time setup\r\ndevtunnel create my-tunnel\r\ndevtunnel port create my-tunnel -p 8080\r\n\r\n# Every session — Uplink reads the tunnel's port and adapts to it\r\nnpx @denifia/copilot-uplink@latest --tunnel-id my-tunnel\r\n```\r\n\r\nUplink reads your tunnel's configured port and starts the server there automatically. You can override\r\nthe port for a single session with `--port`, but Uplink will **never modify** your tunnel's configuration.\r\n\r\n> [!NOTE]\r\n> Auto-persistent tunnels (`--tunnel`) are owned and managed by Uplink. It creates the\r\n> tunnel, assigns a port, and keeps the configuration in sync. `--tunnel-id` is for tunnels\r\n> **you** manage.\r\n\r\n## CLI Reference\r\n\r\n```\r\nnpx @denifia/copilot-uplink@latest [options]\r\n```\r\n\r\nIf you install the package globally instead of using `npx`, invoke it as:\r\n\r\n```bash\r\ncopilot-uplink [options]\r\n```\r\n\r\n| Flag | Description | Default |\r\n|---|---|---|\r\n| `--port <n>` | Port for the bridge server | random |\r\n| `--tunnel` | Start a devtunnel for remote access (auto-persistent per project) | off |\r\n| `--no-tunnel` | Explicitly disable tunnel | — |\r\n| `--tunnel-id <name>` | Use a pre-created devtunnel (reads its port; implies `--tunnel`) | — |\r\n| `--allow-anonymous` | Allow anonymous tunnel access (no GitHub auth) | off |\r\n| `--cwd <path>` | Working directory for the Copilot subprocess | current dir |\r\n| `--help` | Show help and exit | — |\r\n\r\n## Commands\r\n\r\nType `/` in the prompt to see all available commands:\r\n\r\n| Command | Description |\r\n|---|---|\r\n| `/model <name>` | Switch AI model |\r\n| `/agent` | Default agent mode |\r\n| `/plan` | Plan mode |\r\n| `/autopilot` | Autonomous mode (auto-continues until done) |\r\n| `/theme <dark\\|light\\|auto>` | Set color theme |\r\n| `/yolo <on\\|off>` | Auto-approve all permission requests |\r\n| `/session <list\\|new\\|rename>` | Manage sessions |\r\n| `/clear` | Clear conversation history |\r\n| `/debug` | Download a debug log (see below) |\r\n\r\n### Debug Logs\r\n\r\n`/debug` downloads a JSON file (`uplink-debug-{timestamp}.json`) containing structured\r\ntelemetry from both the client and server. This is useful for reporting bugs.\r\n\r\nYou can analyze the file with the built-in viewer:\r\n\r\n```bash\r\nnpx tsx bin/debug-viewer.ts uplink-debug-*.json            # summary\r\nnpx tsx bin/debug-viewer.ts uplink-debug-*.json timeline    # merged client+server events\r\nnpx tsx bin/debug-viewer.ts uplink-debug-*.json conn        # connection events only\r\n```\r\n\r\n> **Privacy warning:** Debug logs may contain personal information including session IDs,\r\n> file paths, tool call titles, model names, and localStorage contents. Review the file\r\n> before sharing.\r\n\r\n## Contributing\r\n\r\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, build, and testing instructions.\r\n\r\n## How It Works\r\n\r\n1. **Copilot CLI** runs locally in ACP mode (`copilot --acp --stdio`), speaking newline-delimited JSON-RPC over\r\n   stdin/stdout.\r\n2. **Bridge server** spawns the CLI as a child process and bridges messages between its stdin/stdout and a WebSocket\r\n   endpoint.\r\n3. **PWA** connects over WebSocket, drives the full ACP lifecycle (`initialize` → `session/new` → `session/prompt`), and\r\n   renders the streaming response.\r\n4. **Dev Tunnel** (optional) exposes the bridge server over HTTPS so you can reach it from your phone or any remote\r\n   browser.\r\n\r\nFor detailed architecture documentation — including bridge lifecycle, eager initialization, session resume, and\r\nlogging — see [ARCHITECTURE.md](ARCHITECTURE.md).\r\n\r\n## Limitations (v1)\r\n\r\n- **Single session only** — one browser client at a time.\r\n- **No file system / terminal proxying** — the PWA does not provide client-side FS or terminal capabilities back to the\r\n   agent.\r\n- **No authentication** beyond devtunnel's built-in defaults.\r\n\r\n## Roadmap Ideas\r\n\r\n- Multi-session support (multiple browser tabs / devices)\r\n- File explorer integration\r\n- Push notifications for long-running tasks\r\n- Syntax-highlighted diffs in tool call output\r\n","readmeFilename":"README.md","_rev":"1-6e45443c79f5f4166dd73198e8685add"}