Skip to content
BranchesTags

Repository files navigation

copilot+

npm version npm downloads license: MIT node ≥18 platform GitHub stars

Talk to GitHub Copilot CLI with your voice — share screenshots — switch AI models instantly — and monitor all running sessions from one dashboard.

📦 View on npm · ⭐ Star on GitHub · 🐛 Report a Bug

copilot+ is a drop-in replacement for the copilot command. It wraps Copilot CLI transparently and adds powerful input enhancements:

Hotkey / Command What it does
Ctrl+R Start / stop voice recording → transcription is typed into your prompt
Ctrl+P Screenshot picker → file path is injected as @/path/screenshot.png
Ctrl+K Open command palette — access all features from a searchable menu
Option+Shift+1–4 (macOS Terminal.app) Switch to workhorse model slot 1–4 — requires "Use Option as Meta Key"
Option+Shift+5 (macOS Terminal.app) Toggle ⚡ Auto Mode — model selected per prompt complexity
Ctrl+Shift+1–4 (kitty/WezTerm/Windows Terminal) Switch to workhorse model slot 1–4 on CSI u–capable terminals
Ctrl+Shift+5 (kitty/WezTerm/Windows Terminal) Toggle ⚡ Auto Mode on CSI u–capable terminals
Option+1–9 (macOS Terminal.app) Execute a prompt macro — requires "Use Option as Meta Key"
Ctrl+1–9 (kitty/WezTerm/Windows Terminal) Execute a prompt macro on CSI u–capable terminals
copilot+ --monitor Open the real-time agent dashboard

Everything else — all Copilot features, slash commands, modes — works exactly as normal.

Requirements

macOS Windows
OS macOS 12+ Windows 10/11
GitHub Copilot CLI required required
Node.js ≥ 18 brew install node nodejs.org or winget install OpenJS.NodeJS
ffmpeg brew install ffmpeg winget install Gyan.FFmpeg
whisper.cpp brew install whisper-cpp Manual install

Apple Silicon: The base.en model transcribes in ~1–2 s on M1/M2/M3.

Installation

Option A — npm (macOS + Windows)

npm install -g copilot-plus

Option B — Homebrew (macOS only)

brew tap Errr0rr404/copilot-plus
brew install copilot-plus

macOS — install speech dependencies

brew install ffmpeg whisper-cpp

# Download speech model (Option A — helper script)
whisper-cpp-download-ggml-model base.en

# Download speech model (Option B — direct curl, always works)
mkdir -p ~/.copilot/models
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" \
  -o ~/.copilot/models/ggml-base.en.bin

Windows — install speech dependencies

1. Install ffmpeg:

winget install Gyan.FFmpeg

2. Install whisper-cli:

3. Download the speech model:

mkdir "$env:USERPROFILE\.copilot\models" -Force
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" `
  -o "$env:USERPROFILE\.copilot\models\ggml-base.en.bin"

Verify setup

copilot+ --setup

You should see all green checkmarks. If anything is missing, the setup output tells you exactly what to fix.

The setup wizard also lists all detected audio input devices and lets you pick the right microphone interactively — the choice is saved to ~/.copilot/copilot-plus.json so you never need to edit the file manually.

Quick Start

copilot+

That's it. You're now inside Copilot CLI with voice and screenshot support active.

Using Voice Input

  1. Press Ctrl+R to start recording.
    A system notification appears and your terminal title changes to 🎙 Recording…

  2. Speak your prompt naturally — e.g. "refactor this function to use async await"

  3. Press Ctrl+R again to stop.
    Transcription runs locally (⏳ Transcribing…) — no audio ever leaves your machine.

  4. Your words appear as text in the Copilot prompt. Review and edit if needed, then press Enter to send.

Press Ctrl+C while recording to cancel without transcribing.

Using Screenshots

macOS: Press Ctrl+P — the interactive screenshot overlay opens (same UI as ⌘⇧4). Click and drag to select any area. The file path is injected into your prompt as @/tmp/copilot-screenshots/screenshot-<timestamp>.png.

Windows: Press Ctrl+P — the Snip & Sketch overlay opens (same as Win+Shift+S). Draw a selection; the file path is injected automatically when you complete the snip.

Add context if you want (e.g. "what's wrong with this?"), then press Enter.

First-Run Setup

On your first launch of copilot+, an interactive onboarding wizard will ask about:

  • Voice Activation — hands-free "hey copilot" keyword detection
  • Prompt macros — assign saved prompts to macro slots

Your choices are saved to ~/.copilot/copilot-plus.json. Re-run the wizard anytime:

copilot+ --preferences

Command Palette

Press Ctrl+K to open the command palette — a searchable overlay listing every copilot-plus action:

  • 🎙 Voice Recording
  • 📸 Screenshot
  • 🗣️ Voice Activation (toggle on/off)
  • ⚡ Auto Mode (toggle on/off) + configure Fast / Medium / Powerful model tiers
  • 🤖 Workhorse Models 1–4 (switch or configure model slots)
  • ⌨️ Macros 1–9 (execute or edit inline)
  • ⚙️ Open Preferences

Navigation: ↑↓ to move, type to filter, Enter to select, Esc to close.

Editing items from the palette: Navigate to any workhorse model, auto model tier, or macro entry and press Enter to open an inline editor. Then:

  • Enter — save and immediately activate (switch model / run macro)
  • Tab — save without activating
  • Esc — go back without saving

Agent Monitor

Run copilot+ --monitor in any terminal to open a live dashboard showing every running copilot session on your machine:

copilot+ --monitor
╭──────────────────────────── copilot+ monitor ─────────────────────────────╮
│  3 active  ·  1 need attention      updates every 1.5s  ·  4:36 PM  ·  q  │
│  individual pro  ·  587/1500 premium req  █████░░░░░░░  resets 2026-04-01  │
├────────────────────────────────────────────────────────────────────────────┤
│  ⚠  ATTENTION    pid 46206  claude-sonnet-4.6    ~/projects/api            │
│                8 premium req     started 14m ago  ·  8 msgs  ·  active 1m  │
├────────────────────────────────────────────────────────────────────────────┤
│  ●  IDLE         pid 51111  gpt-4.1               ~/projects/frontend       │
│                3 premium req     started 8m ago  ·  3 msgs  ·  active now  │
├ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┤
│  ●  IDLE         pid 28741  [copilot CLI]         ~/projects/docs           │
│                [unmanaged – no stats]    started 1h ago                     │
╰────────────────────────────────────────────────────────────────────────────╯

What you see:

Item Description
Header quota bar Your plan, premium requests used/remaining this month, and reset date — pulled live from the GitHub Copilot API
Status badge ATTENTION (response waiting >30 s), THINKING (waiting for response), IDLE, RECORDING, TRANSCRIBING, DONE
Premium req count Number of AI exchanges in this session (copilot+ managed sessions only)
[copilot CLI] A bare copilot session not started through copilot+ — no per-session stats available

Controls: q / Q / Ctrl+C / Esc to exit.

Sessions disappear automatically when the copilot process exits. Stale entries older than 5 minutes are pruned.

Workhorse Models

Assign up to 4 AI models to slots so you can switch between them instantly with a single hotkey — no more typing /model each time.

Setup

The easiest way: open the command palette (Ctrl+K), navigate to a Workhorse entry, press Enter, type the model name (e.g. claude-sonnet-4.6), and press Enter to save and switch immediately.

You can also edit ~/.copilot/copilot-plus.json directly:

{
  "workhorseModels": {
    "1": "claude-sonnet-4.6",
    "2": "claude-opus-4.5",
    "3": "gpt-4.1",
    "4": "o3"
  }
}

Switching models

Terminal Hotkey
macOS Terminal.app Option+Shift+1–4 — requires "Use Option as Meta Key" (same as macros)
kitty / WezTerm Ctrl+Shift+1–4 — works natively
Windows Terminal Ctrl+Shift+1–4 — works natively
Any terminal Ctrl+K → navigate to a Workhorse entry → Enter

Switching clears the current input line and sends /model <name> to Copilot CLI, then shows a macOS/Windows notification confirming the switch.

Note: Activating a workhorse slot (1–4) automatically turns Auto Mode off.

⚡ Auto Mode

Auto Mode routes each prompt to the right model automatically — no manual switching required.

How it works

When Auto Mode is on, copilot+ intercepts every Enter keypress, analyses the prompt you typed, picks a model tier, and switches to it (if needed) before submitting:

Tier When selected Example prompts
Fast Short prompts (<80 chars) with question/explanation keywords "explain this function", "what is a closure?"
Powerful Long prompts (>200 chars) or implementation/task keywords "implement", "refactor", "debug", "build", "create"
Medium Everything else general conversation, moderate-length requests

Setup

Configure the three tiers via Ctrl+K → navigate to an Auto entry → Enter → type a model name → Enter.

Or edit ~/.copilot/copilot-plus.json directly:

{
  "autoModels": {
    "fast":     "claude-haiku-4.5",
    "medium":   "claude-sonnet-4.6",
    "powerful": "claude-opus-4.6"
  }
}

If a tier is left empty it falls back to the corresponding workhorse slot (fast/medium → slot 1, powerful → slot 2).

Toggling Auto Mode

Terminal Hotkey
macOS Terminal.app Option+Shift+5 — requires "Use Option as Meta Key"
kitty / WezTerm Ctrl+Shift+5 — works natively
Windows Terminal Ctrl+Shift+5 — works natively
Any terminal Ctrl+K → ⚡ Auto Mode → Enter

When active, the terminal title shows copilot [⚡ auto] and a notification fires on each prompt showing which tier was selected. Switching to a workhorse slot (1–4) automatically turns Auto Mode off.

Prompt Macros

Assign frequently used prompts to macro slots. When triggered, the saved text is instantly injected into your Copilot prompt.

macOS (Apple Terminal)

Macros are triggered with Option+1 through Option+9.

One-time setup: Open Terminal → Settings → Profiles → Keyboard → check "Use Option as Meta Key".

macOS (kitty / WezTerm / iTerm2) and Windows Terminal

Macros are triggered with Ctrl+1 through Ctrl+9 (these terminals support CSI u key encoding natively — no extra setup needed).

Setting macros

The easiest way is via the command palette (Ctrl+K → navigate to a macro → Enter to edit).

You can also set them during onboarding, via copilot+ --preferences, or by editing ~/.copilot/copilot-plus.json directly:

{
  "macros": {
    "1": "Write unit tests for this code",
    "2": "Explain this code step by step",
    "3": "Refactor this to use async/await"
  }
}

Voice Activation

Say "hey copilot" or just "copilot" to start recording hands-free — no accounts, no API keys, no extra installs.

How it works:

  1. Always listens for your wake phrase using whisper.cpp (near-zero CPU when silent)
  2. Phrase detected → recording starts automatically
  3. You speak your prompt
  4. You pause → transcription runs locally → text is injected into copilot
  5. Returns to listening — ready for the next trigger

Setup

Enable during first run or via copilot+ --preferences. Choose any wake phrase:

  • "hey copilot" (default) — or just say "copilot" without the "hey", both work
  • "ok computer", "yo copilot", or any short distinctive phrase

Passing Flags to Copilot

Any arguments after copilot+ are forwarded directly to copilot:

copilot+ --experimental
copilot+ --banner
copilot+ --help

Configuration

Settings are stored at ~/.copilot/copilot-plus.json (created automatically on first run).

{
  "modelPath": "/opt/homebrew/share/whisper.cpp/models/ggml-base.en.bin",
  "audioDevice": ":2",
  "autoSubmit": false,
  "firstRunComplete": true,
  "workhorseModels": {
    "1": "claude-sonnet-4.6",
    "2": "claude-opus-4.5",
    "3": "gpt-4.1",
    "4": "o3"
  },
  "autoModels": {
    "fast":     "claude-haiku-4.5",
    "medium":   "claude-sonnet-4.6",
    "powerful": "claude-opus-4.6"
  },
  "macros": {
    "1": "Write unit tests for this code",
    "2": "Explain this code step by step"
  },
  "wakeWord": {
    "enabled": false,
    "phrase": "hey copilot",
    "chunkSeconds": 2
  }
}
Key Default Description
modelPath auto-detected Path to your whisper .bin model file. Auto-heals if the file moves.
audioDevice auto-detected ffmpeg audio input device. Set interactively via copilot+ --setup. macOS: ":2" index format. Windows: "Microphone (Realtek Audio)" name format.
autoSubmit false true = automatically press Enter after voice transcription
workhorseModels all empty AI model slots 1–4. Edit via Ctrl+K command palette or directly here.
autoModels.fast empty Model for short Q&A prompts. Falls back to workhorse slot 1.
autoModels.medium empty Model for general prompts. Falls back to workhorse slot 1.
autoModels.powerful empty Model for long/complex/task prompts. Falls back to workhorse slot 2.
macros all empty Prompt macros, slots 1–9. Edit via Ctrl+K or --preferences.
wakeWord.enabled false Enable voice activation (wake phrase detection)
wakeWord.phrase "hey copilot" The phrase to listen for
wakeWord.chunkSeconds 2 Audio chunk length for wake phrase scanning

Available whisper models

Model Size Speed (M2) Accuracy
tiny.en 75 MB ~0.5 s Good
base.en 142 MB ~1 s Better
small.en 466 MB ~3 s Best for most 
# macOS
whisper-cpp-download-ggml-model small.en

# Windows — download directly and update modelPath in config
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin" `
  -o "$env:USERPROFILE\.copilot\models\ggml-small.en.bin"

Then update modelPath in ~/.copilot/copilot-plus.json.

How It Works

┌────────────────────────────────────────────────────────────────────┐
│  copilot+ (PTY wrapper)                                            │
│                                                                    │
│  Your keystrokes ──► intercept hotkeys                             │
│                      ├── Ctrl+R         → push-to-talk recording   │
│                      ├── Ctrl+P         → screenshot picker         │
│                      ├── Ctrl+K         → command palette overlay   │
│                      ├── Opt+⇧1–4       → switch workhorse model    │
│                      ├── Opt+⇧5         → toggle ⚡ auto mode        │
│                      ├── Ctrl+⇧1–4      → switch workhorse model    │
│                      ├── Ctrl+⇧5        → toggle ⚡ auto mode        │
│                      ├── Option+1–9     → inject macro (macOS)      │
│                      ├── Ctrl+1–9       → inject macro (CSI u)      │
│                      ▼                                              │
│         ┌─────────────┬──────────────┬───────────────┐             │
│         │ ffmpeg mic   │ screencapture │ whisper+VAD   │            │
│         │ + whisper-cli│ / Snip&Sketch │ (voice activ) │            │
│         └──────┬───────┴──────┬───────┴───────┬───────┘            │
│                └──────────────┴───────────────┘                    │
│                              ▼                                     │
│                   inject text / @filepath / /model cmd             │
│                              │                                     │
│  copilot ◄───────────────────┘                                     │
│  (all other keystrokes pass through unchanged)                     │
└────────────────────────────────────────────────────────────────────┘

Transcription is 100% local — whisper.cpp runs on your machine, nothing is sent to any server.

Troubleshooting

posix_spawnp failed on first run
Run npm install -g copilot-plus again — the postinstall script will fix the permissions automatically.

Microphone not being captured / transcription is always the same word
Your audioDevice is pointing to the wrong input (e.g. a virtual audio device).

macOS — list devices:

ffmpeg -f avfoundation -list_devices true -i "" 2>&1 | grep AVFoundation

Windows — list devices:

ffmpeg -f dshow -list_devices true -i dummy 2>&1 | findstr audio

Set audioDevice in ~/.copilot/copilot-plus.json to the correct device
(macOS: ":2" index format · Windows: "Microphone (Realtek Audio)" name format)

Error: could not open input device (macOS)
Grant microphone access to your terminal:
System Settings → Privacy & Security → Microphone → enable your terminal app

Error: could not open input device (Windows)
Go to Settings → Privacy & Security → Microphone and enable microphone access for your terminal / Node.js.

No whisper model found

# macOS
mkdir -p ~/.copilot/models
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" \
  -o ~/.copilot/models/ggml-base.en.bin

# Windows (PowerShell)
mkdir "$env:USERPROFILE\.copilot\models" -Force
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" `
  -o "$env:USERPROFILE\.copilot\models\ggml-base.en.bin"

Then run copilot+ --setup to confirm it's detected.

Transcription is inaccurate
Switch to a larger model (small.en instead of base.en) and update modelPath in ~/.copilot/copilot-plus.json.

Wake word not triggering
Try a shorter, more distinctive phrase (e.g. "hey copilot" works better than a single common word). You can increase wakeWord.chunkSeconds to 3 or 4 if the phrase gets cut off mid-recording, or download the tiny.en model for faster scanning:

# macOS
mkdir -p ~/.copilot/models
curl -L "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin" \
  -o ~/.copilot/models/ggml-tiny.en.bin

Option+Shift+1–5 model slots / Option+1–9 macros don't work (macOS Apple Terminal)
Open Terminal → Settings → Profiles → Keyboard → check "Use Option as Meta Key".

Model slot hotkey does nothing (kitty/WezTerm/Windows Terminal)
Ensure your terminal is configured to send CSI u key sequences. In kitty this is on by default. In WezTerm, enable_kitty_keyboard = true must be set. In Windows Terminal, enable "Input: Terminal Input Encoding" → application/vnd.ms-terminal.keyboard.v2 in settings.

Screenshot doesn't attach (macOS)
System Settings → Privacy & Security → Screen Recording → enable your terminal app

Screenshot doesn't attach (Windows)
Make sure you drew a selection in the Snip & Sketch overlay — pressing Escape cancels without saving.

License

MIT © Errr0rr404

Changelog

See CHANGELOG.md for release history and upgrade notes.

Roadmap

See ROADMAP.md for planned features and future direction.

Contributing

Found a bug or have a feature idea? Open an issue — PRs welcome.

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

12 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages