Up and running in 60 seconds

Before you start

You’ll need:

• Python 3.7+ on your development machine (used by the hooks)
• One AI agent installed: Claude Code, Codex CLI, Gemini CLI, or GitHub Copilot CLI
• An iPhone or Android phone for the PromptBeat app

Step 1: Get the PromptBeat app

The mobile app is where you sign up, hold your API key, and approve agent requests.

• Download from the App Store (iPhone, iPad — iOS 16+)
• Or Google Play (Android 10+)
• Sign in with one of:
  • Continue with Google — one-tap, no email verification round-trip
  • Continue with Apple (iOS only) — supports Hide My Email relay
  • Email + password — classic flow with email verification

Both apps are launching soon. While we wait, the hosted server at promptbeat.online is live and ready.

Step 2: Get your API key (two ways)

Option A — QR pairing from the terminal (recommended)

Skip copy-pasting an API key altogether. After installing the local agent (Step 3 below), run:

A QR code appears in your terminal. In the app:

• Tap the laptop icon in the top app bar
• Scan the QR with your phone’s camera
• Confirm — an API key gets minted, tagged to your machine’s hostname, and written to ~/.promptbeat/agent.json automatically

The terminal flips to “Connected!” and you’re done. If you’ve previously paired this hostname, the app gives you Replace existing / Keep both / Cancel.

Option B — Generate manually in the app

• Tap Settings → API Keys
• Tap Generate new key — the key starts with pb_
• Copy it — the laptop installer will ask for it

Step 3: Run the laptop installer

Open a terminal on your development machine and run:

The installer will:

• Ask for your API key (skip if you’ll use QR pairing in Step 2 above)
• Detect which AI agents you have installed
• Wire up hooks for the ones you want
• Optionally install the local agent (needed for Remote AI Chat and the QR pairing flow)

How each agent gets connected

The installer configures each agent in its native way — nothing patches the binary.

Claude Code

Adds a PermissionRequest hook to ~/.claude/settings.json. Use Claude Code as normal — permission prompts route through PromptBeat.

Gemini CLI

Adds a BeforeTool hook to ~/.gemini/settings.json. Run gemini as usual.

Codex

Installs a promptbeat-codex wrapper that fronts codex-app-server over JSON-RPC. Use it instead of codex:

GitHub Copilot CLI

Adds a preToolUse hook to ~/.config/github-copilot/hooks/promptbeat.json. Run copilot as usual.

Step 4: Pair your phone

• Already signed in to the app? Approvals will start arriving automatically once your laptop and the phone use the same account.
• Permission requests show up as push notifications — tap to open the prompt, biometric to approve.

Optional: AI Chat from your phone

Want to drive Claude Code or Codex from your phone while you’re away from your desk? The local agent enables it.

• The installer offers to set up the local agent — say yes
• The agent runs in the background on your laptop and connects to the server over WebSocket
• Open AI Chat in the app, pick a project directory, start typing

Things to try once you’re live

• Auto-approve rules — tap Settings → Rules, add a pattern like git status to skip approvals for safe commands
• Approve for session — long-press the Session button to auto-approve matching tool calls for the rest of your chat
• Audit log — tap Settings → Audit to see every request and decision, exportable as CSV
• End-to-end encryption — set PROMPTBEAT_ENCRYPTION_KEY in your shell rc and the app under Settings → Security

Troubleshooting

• Hook not firing? Check that the agent’s settings file references the PromptBeat hook script. The installer prints the path; you can edit it manually.
• Approvals time out? Pending requests die after 2 minutes. Open the app sooner, or add an auto-approve rule for the safe stuff.
• Wrong machine on the API key? Each key is tagged with a hostname. Generate a new one for the new machine and revoke the old.