AFK Mode

Monitor and respond to VS Code Copilot from your phone.

When Copilot's agent mode runs long tasks, it frequently pauses for user input. If you step away, the session stalls. AFK Mode bridges Copilot and your phone through an MCP server — so you can watch progress, get notifications, and respond to prompts without being at your desk.

Quick Start

One-command setup

Run this in your project folder:

npx afk-mode-mcp --setup

This creates .vscode/mcp.json and .github/prompts/afk-workflow.prompt.md — done. Copilot will start AFK Mode automatically when it needs it.

Usage

1. Ask Copilot: "Show me the AFK app link" → scan the QR code on your phone
2. Toggle AFK Mode on in the app
3. Start a task with /afk-workflow — Copilot routes all progress and decisions to your phone

Push notifications work automatically — no extra setup needed.

Manual setup (alternative)

If you prefer to configure manually, add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "afk-mode-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "afk-mode-mcp"],
      "env": {
        "AFK_PORT": "7842"
      }
    }
  }
}

How It Works

AFK Mode is a single Node.js process that serves two roles simultaneously:

1. MCP Server (stdio) — Exposes tools that Copilot calls to report progress and request decisions
2. Web App Server (HTTP + WebSocket) — Serves a React PWA and maintains a real-time connection with your phone

┌──────────────┐     stdio      ┌──────────────────────┐    WebSocket     ┌──────────────┐
│  VS Code     │◄──────────────►│  MCP + Web Server    │◄────────────────►│  Mobile Web  │
│  Copilot     │                │  (single process)    │    HTTP (static) │  App (PWA)   │
│  Agent Mode  │                │                      │◄────────────────►│              │
└──────────────┘                └──────────────────────┘                  └──────────────┘

1. Copilot starts the MCP server → HTTP/WebSocket server starts automatically on port 7842
2. Ask Copilot "Show me the AFK app link" → it calls get_current_web_app_url and renders a QR code
3. Scan the QR code on your phone → the PWA connects via WebSocket
4. Toggle AFK Mode on in the app → Copilot routes interactions through your phone
5. Copilot sends progress updates and decision prompts to your phone in real time
6. Toggle AFK Mode off → Copilot goes back to the normal VS Code chat panel

MCP Tools

The server exposes 4 tools to Copilot:

Tool	Purpose
get_current_web_app_url	Returns the connection URL + QR code for pairing your phone
get_afk_status	Checks if AFK mode is on and a client is connected
notify_session_progress	Sends a progress update to the phone (info, warning, error, success, milestone)
get_user_decision	Asks the user a question and blocks until they respond (confirm, choice, text, or diff review)

notify_session_progress

Sends real-time progress to the phone. Categories control the icon and urgency:

• info — general status (ℹ️)
• success — task completed (✅)
• error — something failed (❌)
• milestone — significant achievement (🎯)
• warning — needs attention (⚠️)

Supports optional progress bars ({ current, total, label }) and file change lists.

get_user_decision

Blocks Copilot until the user responds on their phone. Decision types:

• confirm — Yes/No
• choice — Pick from a list of options
• text — Free-form text input
• diff — Review a code diff and approve/reject

Includes a configurable timeout (default 5 minutes) with an optional default value.

Web App Features

• Dashboard — AFK toggle, live progress feed with category icons and progress bars
• Decision prompts — Modal overlay with countdown timer, vibration alert
• Diff viewer — Unified diff with syntax coloring for code review decisions
• History — Searchable/filterable log of all progress entries (persisted in localStorage)
• Settings — Verbosity, sound, vibration, theme (light/dark/system)
• PWA — Installable to home screen, works offline via service worker (network-first caching)

Push Notifications

Push notifications alert you on your phone even when the browser tab is in the background (e.g., for errors or pending decisions). They work out of the box — no configuration required.

Push uses the Web Push standard with VAPID (Voluntary Application Server Identification). VAPID is an open W3C standard — no Google account, Firebase setup, or API keys required.

How it works

1. Server auto-generates a VAPID key pair on each startup
2. Client fetches the public key from /api/vapid-key and subscribes via the Push API
3. Browser returns an FCM/Mozilla/Apple push endpoint — stored on the server
4. Server sends encrypted payloads to the endpoint when needed
5. Service worker receives the push and shows a system notification

Since VAPID keys are generated per session (and push subscriptions are in-memory), each developer runs an isolated instance — no shared secrets, no cross-talk between team members.

Security

• Session token — 256-bit random token generated per server instance, required for the initial WebSocket connection
• Single device — Only one phone can connect at a time (409 Conflict for second connections)
• Reconnect tickets — Rotating one-time tickets for seamless reconnection after network drops (expires after 5 minutes, invalidated after use)
• Local network only — The server binds to your machine's local IP; no internet exposure

Environment Variables

Variable	Default	Description
AFK_PORT	7842	HTTP/WebSocket server port

Development (for contributors)

git clone <repo-url> && cd afk-mode-mcp
pnpm install

# Run server with hot reload
pnpm dev:server

# Run webapp dev server (Vite, port 5173)
pnpm dev:webapp

# Build everything
pnpm build

# Start production server
pnpm start

# Lint and format
pnpm lint             # Check for lint errors
pnpm lint:fix         # Auto-fix lint errors
pnpm format           # Format all source files
pnpm format:check     # Check formatting without writing

Tech Stack

• Server: Node.js, Express 5, WebSocket (ws), @modelcontextprotocol/sdk
• Web App: React 19, Vite 7, MUI (Material UI) 7, Emotion
• Build: tsup (server), Vite (webapp)
• Lint: ESLint 10 with typescript-eslint + React Hooks plugin
• Format: Prettier
• Push: web-push with VAPID
• QR: qrcode (data-URI PNG)