Keypress CLI

Control AI coding agents from your phone. Start a session on your computer, continue from anywhere.

Keypress wraps your local AI coding agent (Claude Code, Codex, Gemini, OpenCode, or Copilot) and lets you control it remotely from the Keypress app on mobile, web, or desktop. Your code stays local — Keypress just gives you remote access to the session.

Free. Open source. Works with 5 AI agents.

Quick Start

# Install
npm install -g @keypressai/cli

# Start a session (Claude Code by default)
keypress

A QR code appears in your terminal. Scan it with the Keypress app to connect and start coding from your phone.

Prerequisites

• Node.js 20+ (22+ for GitHub Copilot)
• An AI coding agent installed and authenticated (see setup below)
• Keypress app — web, mobile (iOS / Android), or desktop

Supported Agents

| Agent | Command | Install | Auth | |-------|---------|---------|------| | Claude Code | keypress | npm i -g @anthropic-ai/claude-code | claude login | | Codex | keypress codex | npm i -g @openai/codex | keypress connect codex | | Gemini | keypress gemini | npm i -g @google/gemini-cli | keypress connect gemini | | OpenCode | keypress opencode | npm i -g opencode-ai | Configure ~/.config/opencode/opencode.json | | Copilot | keypress copilot | npm i -g @github/copilot | copilot login |

Setup

1. Install Keypress

npm install -g @keypressai/cli

2. Install & authenticate your AI agent

Pick one (or more):

Claude Code (default)

npm install -g @anthropic-ai/claude-code
claude login

Codex

npm install -g @openai/codex
keypress connect codex

Gemini

npm install -g @google/gemini-cli
keypress connect gemini

OpenCode

npm install -g opencode-ai
keypress connect opencode

GitHub Copilot (requires Node.js 22+)

npm install -g @github/copilot
copilot login

3. Start a session

keypress            # Claude (default)
keypress codex      # Codex
keypress gemini     # Gemini
keypress opencode   # OpenCode
keypress copilot    # Copilot

4. Connect from your device

Scan the QR code shown in terminal with the Keypress app, or open the session link on app.keypress.ai.

Commands

Sessions

keypress                        # Start Claude session
keypress codex                  # Start Codex session
keypress gemini                 # Start Gemini session
keypress opencode               # Start OpenCode session
keypress copilot                # Start Copilot session

Authentication

keypress auth login             # Log in to Keypress
keypress auth login --force     # Force re-authentication
keypress auth status            # Check auth status
keypress auth logout            # Log out

Vendor Connections

keypress connect claude         # Verify Claude setup
keypress connect codex          # Connect to OpenAI
keypress connect gemini         # Authenticate with Google
keypress connect opencode       # Verify OpenCode setup
keypress connect copilot        # Verify Copilot setup
keypress connect status         # Show all connection statuses

Background Daemon

Run sessions without keeping a terminal open:

keypress daemon start           # Start background service
keypress daemon stop            # Stop background service
keypress daemon status          # Check daemon status
keypress daemon list            # List active sessions
keypress daemon logs            # View daemon logs

Diagnostics

keypress doctor                 # Run system diagnostics
keypress doctor clean           # Clean up broken state

Options

-m, --model <model>             Claude model to use (default: sonnet)
-p, --permission-mode <mode>    Permission mode: auto, default, or plan
--resume                        Resume previous session
--yolo                          Auto-approve all file operations
--chrome / --no-chrome          Enable/disable Chrome browser access
--claude-env KEY=VALUE          Set environment variable for Claude
--claude-arg ARG                Pass additional argument to Claude CLI
--js-runtime <runtime>          Use bun instead of node
--menu / --no-menu              Show/skip startup launcher
-h, --help                      Show help
-v, --version                   Show version

Gemini Configuration

Personal Google accounts work out of the box.

Google Workspace accounts require a Google Cloud Project:

# Set your project ID
keypress gemini project set <your-project-id>

# Or use an environment variable
GOOGLE_CLOUD_PROJECT=your-project-id keypress gemini

Model selection:

keypress gemini model set gemini-2.5-pro    # Set default model
keypress gemini model get                    # Show current model

Available models: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | KEYPRESS_SERVER_URL | Custom server URL | https://server.keypress.ai | | KEYPRESS_WEBAPP_URL | Custom web app URL | https://app.keypress.ai | | KEYPRESS_HOME_DIR | Data directory | ~/.keypress | | KEYPRESS_STARTUP_MENU | Launcher menu (0/1) | auto | | KEYPRESS_DISABLE_CAFFEINATE | Disable macOS sleep prevention | false | | GEMINI_MODEL | Override Gemini model | — | | GOOGLE_CLOUD_PROJECT | Google Cloud Project ID | — | | GH_TOKEN | GitHub token for Copilot | — |

Troubleshooting

keypress command not found — Ensure npm global bin is in your PATH. Reinstall with npm install -g @keypressai/cli and restart your terminal.

Can't connect to session — Check that the daemon is running (keypress daemon status) or that your terminal session is still active.

Agent won't start — Verify the agent is installed and authenticated: keypress connect <agent>

Gemini auth errors — Re-authenticate with keypress connect gemini. Workspace users: ensure your Google Cloud Project is set.

For more help, run keypress doctor.

Links

• Website
• Documentation
• Web App
• iOS App
• Android App
• GitHub
• Issues

License

See LICENSE for details.