Weft turns your phone into a secure control surface for GitHub Copilot CLI and local GitHub Copilot app sessions. Follow live work, send prompts, approve tool calls, and connect to existing sessions while the actual process keeps running on your laptop.
Open the app · Read the docs · Try the in-browser demo · View releases
|
|
| Stay in the loop | Stay in control | Stay private |
|---|---|---|
| Watch replies, tool calls, edits, and status stream live. | Prompt, steer, stop, change mode, and answer native approvals from your phone. | Session traffic is encrypted end to end; the relay forwards ciphertext and stores no session content. |
| Resume existing work or launch a session in a registered project. | Use voice, image attachments, clipboard tools, keep-awake controls, and a shared terminal. | Pairing keys, transcripts, and session metadata remain on your devices. |
Files and Changes: Files has separate Current folder and Agent-touched files
trees: browse workspace folders lazily or see files this session read or wrote,
including permitted external paths. Changes shows touched workspace files' Git diffs.
Both trees and chat file links use the same read-only, on-demand viewer.
Opt in through files in the central ~/.weft/weft.config.json, with explicit
named roots and optional exclusions. An allowed Git repository root includes its
verified registered worktrees. Weft exclusions, host directory permissions and
native approvals apply; file sharing does not depend on Copilot's experimental
content-exclusion API.
Weft is not a remote desktop and it does not move your workspace to the cloud. Copilot and your tools continue to run under your account on the laptop; the phone provides a focused, mobile-first interface to that work.
Install the prebuilt extension and Device Station. No repository clone, mobile app-store download, or relay account is required.
# Windows (PowerShell)
irm https://useweft.netlify.app/install.ps1 | iex# macOS / Linux
curl -fsSL https://useweft.netlify.app/install.sh | bashOpen the laptop Control Center:
weftReview Setup, then explicitly choose Start Station on Control.
For terminal-only startup, run weft start instead.
Then open useweft.netlify.app on your phone, choose
Scan QR to pair, and scan the dashboard or terminal QR. On Windows and macOS,
Station runs in the background and you can close this terminal. Use weft status
and weft stop to manage it. Startup is manual, not automatic at boot/sign-in.
Use weft start --foreground for terminal-owned diagnostics; other platforms
retain foreground operation.
Laptop Control Center: run weft (or weft ui) to open a private local app-style window for
Station/relay controls, projects, settings, pairing, and discoverable Copilot
sessions. It works with Station stopped and uses the same management layer as the
CLI. Installed Edge/Chrome/Chromium supplies the window; no desktop framework is required.
Use weft ui --browser for a normal browser tab. If no supported browser is found,
Weft reports the default-browser fallback rather than installing one.
Closing the window does not stop workloads. Windows installs add a Start menu
shortcut; weft ui shortcut adds a desktop shortcut. weft ui status and
weft ui stop manage only the local UI host.
weft help or weft --help shows the complete command reference without opening
the dashboard. Bare weft does not start Station; use the explicit controls or
weft start when you want device-level phone access.
The Control page separates sessions not shared with a phone, sessions awaiting a phone, and confirmed recent mobile links. It shows worker versions/uptime, sanitized relay addresses, forwarding checks and real startup/retry progress. Saved phone trust is not treated as proof of live contact; older workers without these fields remain explicitly unreported until they are restarted on an updated build. It adapts connection information to Dev Tunnel or Supabase and keeps saved pairing visible when Station is stopped. Setup combines registered projects, connection settings and access policy, while retaining separate explicit project actions and configuration saves.
Local diagnostics: logging is on by default for this laptop. Use Setup ->
Local diagnostic logging, or weft set-logging off / weft set-logging on.
weft show-logging checks the setting; weft logs and Diagnostics -> Load
diagnostics show the latest 100 sanitized Station/management entries. Logs include
startup stages, session-list timings and correlated launch outcomes, not prompts,
terminal output, project paths or pairing secrets. Updated Weft writers honor the
switch without a restart; existing files and Copilot's own history are unchanged.
Diagnostics -> Phone traffic shows a live, metadata-only list of the latest 100
messages between this laptop and your phone, with readable event names, direction,
size and reply timing, to diagnose "online but nothing works" problems.
See privacy and retention.
On Windows, phone-launched CLI sessions open an interactive terminal even when Station runs in the background without Windows Terminal. A launched terminal is not yet proof of a connected session; Weft waits for the session runtime handoff. Finish any native Copilot startup prompts in that terminal, including unrelated extension permission requests. Weft does not automatically approve them.
On macOS, phone-launched CLI sessions open in Terminal.app, including when Station has no inherited terminal environment. Clipboard text transfer, bounded Keep Awake leases, and battery/AC status work on Windows and macOS. Running-app lists, shared terminals, and background Station supervision remain Windows-only.
Already paired? Run
weft startnormally. Useweft start --new-deviceonly when replacing the trusted phone or after clearing the phone browser's storage.
Already in Copilot? /weft shows a terminal QR in CLI or a pairing canvas in the
local Copilot app; asking to open Weft pairing works too. Device Station's Resume
screen can connect to local app sessions, but it launches new sessions through CLI.
Cloud and remote-host app sessions are not discovered on this laptop.
- Live Copilot sessions — stream replies and tool calls, send follow-ups, attach up to six images, and use Vox for hands-free prompting.
- Native approval relay — allow once, allow for the session, or deny the exact action Copilot requested.
- Session control — stop an active turn, queue the next instruction, and use supported slash
commands through one searchable command flow. The composer's model dropdown shows the models
your Copilot account offers and the current model's reasoning-effort levels;
/modeland/effortdo the same from the keyboard, and/interactive,/planand/autopilotswitch mode. Weft reports failures from Copilot instead of claiming a change succeeded. - Multi-device workspace — use one phone to move among paired laptops, registered projects, and active or historical sessions.
- Safe launch recovery — reconnect to slow Start and Resume operations instead of silently creating duplicate Copilot processes.
- Shared terminal — open and resume one real shell on supported Windows laptops. See terminal controls and access boundaries.
- Explore between turns — use compact header tiles for Discover, Watch, Play, and Unwind, or swipe left from the right edge of Chat to open Discover and return with one Back. A concise Copilot presence tile shows the current activity and useful live response context without turning Explore into a second debug log. Discover provides a balanced animated swipe deck of 50 offline cards, alongside two lightweight games, guided rest activities, and an optional explicitly loaded third-party short-video widget.
- AES-256-GCM end-to-end encryption. Pairing uses ECDH and a fresh handshake nonce.
- Content-free relay. Supabase Realtime or a self-hosted Dev Tunnel carries encrypted envelopes without storing session content.
- Local continuity. Device configuration and persistent pairing material live under
~/.weft/; phone session data remains in local device storage. - Explicit authority. The phone receives the same approval boundaries exposed by the underlying Copilot session. Weft does not invent an automatic approval policy.
- Explore stays local by default. The live Copilot dock projects data already present in the active encrypted session, while the shuffled Discover deck, reading progress, Play, Unwind, and scores remain on the phone. Attention states return to the canonical chat controls. The optional Watch provider loads only after an explicit tap and receives no Weft prompt, repository, filename, tool, or session context.
Read the full security model, privacy policy, and pairing protocol.
- Every dormant Copilot extension publishes one small user-local presence record and holds one idle local lifecycle endpoint. It performs no remote/network access, pairing cryptography, QR work, logging, diagnostics, polling, heartbeat, retry timer, or other timer.
- Filesystem state provides discovery and crash recovery; the Windows named pipe or Unix-domain socket provides authenticated live commands such as activate, status, controller replacement, and quiesce. Station connects only for a command and then disconnects.
- After pairing, prompts, events, approvals, streaming, and terminal traffic flow directly between the phone and session over the encrypted relay. Active phone traffic does not pass through Device Station or the local lifecycle endpoint.
/clearends the current phone attachment. The replacement Copilot session starts dormant and requires fresh activation through Station or/weft.- Completed lifecycle operations and unclaimed recovery identities are retained for three days, unless still referenced by a live runtime or unresolved operation.
- A confirmed takeover of a responsive runtime replaces the current phone controller immediately without restarting Copilot. Restart-and-Resume is reserved for a separately confirmed, revalidated unresponsive-owner flow.
+------------------------------+ +------------------------------+ +-------------------------------+
| Weft Mobile | | Encrypted relay | | Laptop Copilot host |
| (React PWA + Capacitor) | | Supabase or Dev Tunnel | | CLI or local app (parent) |
| | | private:weft:<channelId> | | └─ extension.mjs (child) |
| • scans QR (channel + grant)| WSS | • in-memory pub/sub | WSS | • joinSession() |
| • ECDH → AES-256-GCM | <----> | • zero DB persistence | <----> | • onPermissionRequest→relay |
| • decrypts token stream | | • RLS-gated private chan | | • on(assistant.message)→push|
| • native-style approval UI | | | | • session.send(phone prompt)|
| • prompt + mode controls | | | | • terminal QR / app canvas |
+------------------------------+ +------------------------------+ +-------------------------------+
all payloads E2E-encrypted; Supabase sees ciphertext only
Three layers, one monorepo:
| Workspace | What it is |
|---|---|
extension/ |
The CLI/app session extension (joinSession) + a local test harness that mimics the phone with no Supabase needed. |
shared/ |
Contracts imported by both ends: message schema, E2E crypto (ECDH→AES-GCM), and pluggable local, Supabase, and WebSocket relay transports. |
mobile/ |
React + Vite + Capacitor app shipped as the supported PWA (useweft.netlify.app), with in-browser camera QR scanning and an Android development shell. |
- Approval = pure relay of native Copilot behavior. The extension forwards the native
permission prompt to the phone via
onPermissionRequestand resolves with the user's tap. No custom policy or automatic decision timeout; the prompt stays pending until answered or the session ends. - Content-free relay storage. Relay infrastructure forwards encrypted envelopes and does not store session content. Providers may still process ordinary connection metadata such as IP addresses, timestamps, and channel identifiers.
- End-to-end encrypted. The QR carries the laptop public key plus a short-lived, single-use pairing grant; ECDH + a fresh handshake nonce derives the AES-256-GCM key. Supabase only ever sees ciphertext.
- Local continuity. The phone stores session metadata, transcript history, preferences,
and pairing keys locally. Persistent Device Station keys and configuration stay under
~/.weft/on the laptop. Removing a session deletes its locally cached phone transcript. - stdout is sacred. The host reserves stdout for JSON-RPC; extension UX uses
session.log()or the pairing canvas.
- The extension is authored in
extension/src/and bundled (esbuild) to a singleextension/dist/extension.mjsplus the lazily importedextension/dist/activeRuntime.mjsand on-demandextension/dist/pairingCanvas.mjs.@github/copilot-sdkis marked external (the Copilot host provides it at runtime); everything else (e.g.@supabase/supabase-js,shared/) is bundled in. - Install copies
extension/dist/into~/.copilot/extensions/weft/, discovered by CLI and local app sessions (seesetup.*/install.*) — that directory holds installed code only. All user config lives separately in~/.weft/:weft.config.json(registered projects, transport choice, device name) andsupabase.json(relay URL + anon key). There is no.env/ env-var override — reinstalling or rebuilding never touches either file, so your chosen transport always survives. Crypto uses Web Crypto — no native deps. - For local development you do not need to install into
~/.copilot: run the harness (extension/harness/) which drives the extension logic againstLocalTransport.
Source builds require Node.js 20 or newer.
npm install --workspaces --include-workspace-root # resolve shared, extension, and mobile
npm test -w @aasis21/weft-shared # crypto + pairing + transport + message tests
node extension/harness/harness.mjs --auto # full relay loop vs a simulated phone (no Supabase)
npm run build -w @aasis21/weft-extension # bundles -> extension/dist/extension.mjs + activeRuntime.mjs
npm run build -w @aasis21/weft-mobile # Vite production build
cd mobile && npm run dev # then pick "Demo / Simulator"
node design/capture.mjs # refresh product screenshots from the hosted appSee docs/setup.md for the full developer guide.
| Doc | What |
|---|---|
docs/setup.md |
install, verify, run, and Supabase wiring |
docs/advanced.md |
/weft, transports, pairing modes, and command reference |
docs/pairing.md |
the ECDH pairing handshake |
docs/security.md |
threat model & cryptography |
docs/mode-switching.md |
runtime interactive/plan/autopilot switching |
docs/hosting.md |
public instance vs self-hosting; operating a relay |
docs/releases.md |
supported PWA, checksums, and laptop updates |
CHANGELOG.md |
notable user-facing changes by release |
CONTRIBUTING.md |
development and pull-request guidance |
PRIVACY.md |
what is stored locally and what the relay can observe |
SECURITY.md |
supported releases and private vulnerability reporting |
SUPPORT.md |
troubleshooting and issue-reporting checklist |
npm test at the root fans out to every workspace. Tests come in two tiers that answer
different questions, so a change is proven where it's cheapest and most reliable:
| Tier | Runner | Lives in | Answers |
|---|---|---|---|
| Contracts + extension | node:test |
shared/**/*.test.mjs, extension/**/*.test.mjs |
Is the crypto / pairing / transport / message protocol and the extension relay logic correct? |
| Mobile unit + scenario | Vitest + jsdom | mobile/src/**/*.test.{ts,tsx} |
Is the logic right for a given message / timer / edge — fast, deterministic, fully mocked? |
| Mobile real-browser e2e | Playwright | mobile/tests/*.spec.ts |
Does the real production build render, scroll, and navigate for a user? |
What goes where (mobile):
- Vitest = breadth. The exhaustive scenario matrix — join, resume-dedupe, remove→re-join,
network drop→catch-up, state snapshot, approvals, elicitations, streaming, the 20s/30s heartbeat
watchdog, persistence-across-restart — drives the real
SessionManagerthrough a mocked transport (FakeWeftClient) with fake timers, so no network, crypto, or Supabase is touched. Plus pure-logic (reduceTimeline,sessions,transcripts,storage) and React component tests (RTL). - Playwright = depth. A few bigger journeys against
dist/in a real phone viewport (412×915), driven by the in-app demo simulator:journey-connect(Landing→Join→Session navigation),journey-stream(a live streaming turn),journey-session-management(drawer + leave-confirm + routing), andjourney-smoke(production boot + layout). It answers what only a real browser can. - Not automated (manual): the real Supabase relay + real WebCrypto E2E + real cross-device pairing. Vitest mocks the transport; Playwright uses the demo. Neither hits the network.
npm test # all workspaces: shared + extension + mobile
npm test -w @aasis21/weft-mobile # just the mobile Vitest unit/scenario suite
npm run coverage -w @aasis21/weft-mobile # mobile coverage table (report-only, no gate)
npm run test:e2e -w @aasis21/weft-mobile # build dist/ + run the Playwright journeys- Releases and changelogs: https://github.com/aasis21/weft/releases
- Update the laptop installation:
weft update --check, thenweft update - General questions and reproducible bugs:
SUPPORT.md - Sensitive vulnerability reports:
SECURITY.md - Data handling:
PRIVACY.md
Apache-2.0 — permissive, with an explicit patent grant and trademark
reservation; see NOTICE for attribution. Operating a hosted relay is a
separate concern from the code license — see docs/hosting.md and
TERMS.md.




