Guide

Setup Guide

Connect your AI tools to PromptBeat in under 60 seconds

Prerequisites

Before you begin, make sure you have:

Python 3.7+ installed on your development machine
At least one AI tool installed: Claude Code, Aider, Codex, Goose, Gemini CLI, or GitHub Copilot CLI
A PromptBeat account — sign up at promptbeat.online/dashboard

Step 1: Get Your API Key

After creating your account, generate an API key:

Open the PromptBeat app or web dashboard
Go to Settings → API Keys
Tap Generate New Key — you'll get a key starting with pb_
Copy it — you'll need it during installation

Step 2: Run the Installer

Open a terminal on your development machine and run:

curl -sS https://promptbeat.online/public/promptbeat-installer.sh | bash

The installer will:

Ask for your API key and server URL
Detect which AI tools you have installed
Let you choose which tools to configure
Set up everything automatically

Step 3: How Each Tool Gets Connected

The installer configures each tool differently based on what it supports:

Claude Code (Native Hook)

Configures ~/.claude/settings.json with a PermissionRequest hook. No changes to your workflow — just start Claude Code as usual and permission requests appear in the app.

Gemini CLI (Native Hook)

Configures ~/.gemini/settings.json with a BeforeTool hook. Same seamless experience — just run gemini as usual.

Aider (Shell Alias)

Creates a promptbeat-aider alias. Use it instead of aider:

promptbeat-aider main.py

Codex (Shell Alias)

Creates a promptbeat-codex wrapper that acts as a JSON-RPC client to codex-app-server. Use it instead of codex:

promptbeat-codex "Fix the bug in main.py"

Goose (Shell Alias)

Creates a promptbeat-goose wrapper that bridges Goose's approval system to PromptBeat:

promptbeat-goose --interactive

GitHub Copilot CLI (Native Hook)

Configures ~/.config/github-copilot/hooks/promptbeat.json with a preToolUse hook. No changes to your workflow — just run copilot as usual and tool approvals route through PromptBeat.

Step 4: Connect Your Phone

Download the PromptBeat app (coming soon to App Store and Play Store)
Sign in with your account
Permission requests will appear instantly via push notifications

You can also use the web dashboard from any browser.

Step 5: Use AI Chat (Optional)

PromptBeat also lets you run full AI chat sessions from your phone or web dashboard. To enable this:

During installation, select Local Agent when prompted
The agent runs in the background on your development machine
Open the app → AI Chat tab → select a tool → start chatting
Supports Claude Code, Aider, Codex, Goose, Gemini, and Copilot CLI

Environment Variables

The installer sets these automatically, but you can configure them manually:

Variable	Description	Default
`PROMPTBEAT_API_KEY`	Your API key (pb_...)	—
`PROMPTBEAT_SERVER`	Server URL	https://promptbeat.online
`PROMPTBEAT_TIMEOUT`	Seconds to wait for mobile response	120
`PROMPTBEAT_POLL_INTERVAL`	Seconds between poll attempts	2
`PROMPTBEAT_ENCRYPTION_KEY`	Optional E2E encryption passphrase	—

End-to-End Encryption (Optional)

For extra security, enable E2E encryption so tool inputs are encrypted before leaving your machine:

export PROMPTBEAT_ENCRYPTION_KEY="your-secret-passphrase"

Then set the same passphrase in the mobile app under Settings → Encryption. The server never sees plaintext tool inputs.

Troubleshooting

Permission requests not appearing

Check that PROMPTBEAT_API_KEY is set: echo $PROMPTBEAT_API_KEY
Verify the server is reachable: curl https://promptbeat.online/api/config
For Claude/Gemini/Copilot CLI, check the settings/hooks file was created correctly
Make sure you sourced your shell profile: source ~/.zshrc

AI Chat not connecting

Ensure the local agent is running: check ~/.promptbeat/agent.log
Restart the agent: python3 ~/.promptbeat/agent.py
Make sure the AI tool CLI is installed and in your PATH