Support & Setup Guide

Getting Started

For a detailed walkthrough including how the rules system works, see the setup guide.

1. Install the App

Download Greenlight from the App Store or Google Play and open it. The app will automatically generate a unique device ID and connect to the relay server.

2. Copy Your Device ID

Go to the About tab in the app and tap your Device ID to copy it to the clipboard. You'll need this for the next steps.

3. Install greenlight-cli

Run the install script (requires Go 1.19+):

curl -sSL https://aigreenlight.app/install.sh | bash

This clones the repo, builds from source, and installs the binary to /usr/local/bin.

Alternatively, unsigned pre-built binaries are available from GitHub releases (see that page for macOS Gatekeeper instructions).

Register your device ID (you only need to do this once):

greenlight register YOUR_DEVICE_ID

You can also pass --device-id as a flag or set the GREENLIGHT_DEVICE_ID environment variable.

4. Set Your Default Agent

greenlight agent claude

Supported values: claude, copilot, cursor, codex, gemini, pi. You only need to do this once.

5. Launch

cd your-project
greenlight

greenlight-cli launches your agent in yolo mode so it never blocks on a terminal prompt. Greenlight's libhook permission engine intercepts all reads, writes, network IO, and shell commands — forwarding them to your phone for approval. On first launch, you'll see an enrollment prompt on your phone — tap Allow. After that, new sessions connect automatically.

To resume a previous session:

greenlight --resume SESSION_ID

6. Test It

Ask your agent to do something that requires permission, like writing a file. You should see a request appear in the app.

greenlight-cli Options

Option	Description	Default
--device-id ID	Your device ID from the app	Config file or env var
--project NAME	Project name shown in the app. Rules are scoped per-project.	Current directory name
--resume SESSION_ID	Resume a previous session instead of starting a new one	—

Configuration priority: command-line flag > environment variable (GREENLIGHT_DEVICE_ID) > config file (~/.greenlight/config).

Using the App

Permission Decisions

Each request can be responded to with four actions:

• Always Allow — Approves and creates a rule so future matching requests are auto-approved.
• Allow — Approves this one request.
• Deny — Denies this one request.
• Deny & Stop — Denies and sends a halt signal to stop the agent entirely.

How Rules Work

Tapping "Always Allow" generates a pattern that auto-approves future matching commands without interrupting you.

Patterns are subcommand-aware. The system knows that git push and git status are different operations:

• go build ./cmd/foo → pattern Bash(go build **) — matches any go build
• git push origin main → pattern Bash(git push **) — matches any git push, but not git reset
• aws s3 cp file.txt s3://bucket/ → pattern Bash(aws s3 cp **) — three-word prefix for AWS/GCloud

Commands like rm, sudo, kill, and chmod use exact matching. Granting rm -rf /tmp/coverage creates a rule that matches only that exact string — not rm -rf /home.

For compound commands like git add . && git commit -m "msg" && git push, the system splits into segments and generates a separate pattern for each. All segments must have matching rules for auto-approval. Each segment is color-coded by risk (green/orange/red) and segments already covered by rules show a checkmark overlay.

For Read, Write, and Edit tools, patterns match on the directory (e.g., Edit(/home/user/project/src/**)).

Managing Rules

The Grants tab shows all your "Always Allow" rules grouped by project. Swipe left on any rule to delete it.

Talk to Your Agent from Your Phone

The Activity tab shows an input bar at the bottom. Anything you type is sent directly to your agent session as if you typed it at the terminal. Use this to answer prompts, provide additional context, or nudge your agent in a different direction.

Greenlight Pro adds push notifications, voice input, Pull the Plug, and temporary grants.

Notifications

Greenlight uses Time Sensitive notifications that can break through Focus modes. Make sure notifications are enabled in Settings → Greenlight → Notifications and that Time Sensitive notifications are allowed in your Focus mode settings.

Troubleshooting

Not receiving requests

• Check the About tab — the status should show "Connected" with a green dot.
• Verify your device ID in ~/.greenlight/config matches the one shown in the app.
• Make sure you launched your agent with greenlight.

Session not appearing on phone

• Verify the device ID in your ~/.greenlight/config matches the one in the app's About tab.
• Check the phone's connection status — the About tab should show a green "Connected" dot.
• The session should appear immediately when you run greenlight. If it doesn't, check the greenlight log file for errors.

Talk to Your Agent not working

• You must launch your agent with greenlight connect.
• Check that the Activity tab shows an input bar at the bottom when viewing the session.

Not receiving push notifications

• Check that notifications are enabled: Settings → Greenlight → Notifications.
• If using a Focus mode, make sure Greenlight is in the allowed apps list or Time Sensitive notifications are enabled.
• Push notifications are sent when the app is backgrounded. If the app is in the foreground, requests arrive directly via WebSocket.

Requests timing out

• The default timeout is 590 seconds.
• If the app is not connected and push notifications fail, the request will time out and be denied.

Contact

For bug reports, feature requests, or any questions, email support@aigreenlight.app.