AFK Mode MCP Server

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:

`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-gene