Code Companion

Use your phone to control GitHub Copilot CLI running on your own computer.

It works like this:

1. Install Code Companion on your Mac
2. Sign in to GitHub Copilot CLI
3. Run one command to start the desktop companion
4. Scan the QR code with the phone app
5. Chat from your phone while the real coding session runs on your computer

Quick Start

What you need

• A Mac
• Node.js 20+
• A GitHub Copilot account
• The Code Companion mobile app

Install it globally

npm install -g @senoldogann/code-companion

You normally do not need to install GitHub Copilot CLI separately. code-companion login uses the bundled Copilot CLI login flow.

If you are upgrading from an older global install, reinstall the latest package before restarting the companion:

npm install -g @senoldogann/code-companion@latest
code-companion down
code-companion up

After that, you can use the global command:

code-companion

First-time setup

Run these commands on the computer you want to control:

code-companion login
code-companion up
code-companion doctor

What these commands do:

• code-companion login opens the official GitHub Copilot CLI sign-in flow
• code-companion up starts the desktop companion and prints a QR code
• code-companion doctor checks that everything is ready

Then on your phone:

1. Open the app
2. Tap Connect With QR
3. Scan the QR code from your computer

That is it.

Everyday Use

If you already installed the package globally, these are the main commands:

code-companion up
code-companion status
code-companion qr
code-companion doctor
code-companion logs
code-companion down

What each command does

| Command | What it does | | --- | --- | | code-companion login | Sign in to GitHub Copilot CLI | | code-companion up | Start the desktop companion and show a pairing QR | | code-companion status | Show whether the desktop companion is running | | code-companion qr | Print a fresh QR code | | code-companion doctor | Check auth, daemon, and connection health | | code-companion logs | Show desktop companion logs | | code-companion down | Stop the desktop companion |

Supported computers

• macOS: runs through a LaunchAgent

Simple troubleshooting

code-companion command not found

Install the package globally:

npm install -g @senoldogann/code-companion

Then open a new terminal and try:

code-companion doctor

Copilot is not signed in

Run:

code-companion login

spawn copilot ENOENT

This means Code Companion could not start the Copilot CLI binary.

First try:

npm install -g @senoldogann/code-companion@latest

If it still fails, install GitHub Copilot CLI manually:

npm install -g @github/copilot

The phone cannot connect

Run:

code-companion doctor
code-companion qr

Then scan the new QR code.

Mobile commands fail with unexpected user permission response

Update to @senoldogann/[email protected] or newer. This version uses the current Copilot SDK permission response format required by recent Copilot CLI releases.

npm install -g @senoldogann/code-companion@latest
code-companion down
code-companion up

Shell commands do not run from the phone

Check that the mobile app is using an agent mode that can execute tools and that the permission level is set to Bypass or Autopilot when you want commands to run without prompts.

Streaming stops after reopening the mobile app

Update to the latest desktop companion and restart it. Current versions intentionally reconnect with auth.resume after the mobile app returns from the background so missed streaming events can be replayed.

npm install -g @senoldogann/code-companion@latest
code-companion down
code-companion up

I changed to a different computer

Scan the QR code from the new computer. The mobile app now keeps chat and workspace cache scoped to the connected companion so different machines should not mix together.

How it works

• Your phone is the remote control
• Your computer runs the real Copilot CLI session
• The bridge server talks to @github/copilot-sdk
• Pairing happens through a QR code
• Reconnect and session continuity are supported

Development

Install dependencies:

pnpm install

Useful commands:

pnpm test
pnpm test:mobile
pnpm typecheck
pnpm build:shared
pnpm build:bridge
pnpm build:desktop

For the relay docs, see:

• docs/cloudflare-relay.md

For desktop companion notes, see:

• docs/desktop-companion.md