Claude Code + Greenlight Setup Guide

Claude Code's permission system keeps you in control of what the agent does. Greenlight extends it to your phone — permission requests arrive as push notifications, and you can approve, deny, or create always-allow rules from anywhere.

This guide covers installation, configuration, and how to get the most out of the rules system.

What You'll Need

• Claude Code installed and working
• An iPhone with Greenlight installed
• jq and curl on your machine (pre-installed on most macOS and Linux systems)

Check with:

jq --version
curl --version

If either is missing: brew install jq on macOS, or apt install jq on Ubuntu/Debian.

Step 1: Get Your Device ID

Open Greenlight on your phone and go to the About tab. Tap your Device ID to copy it to the clipboard. You'll paste this into the hook configuration next.

Step 2: Install the Hook Script

curl -o ~/greenlight-hook.sh https://getgreenlight.github.io/greenlight-hook.sh
chmod +x ~/greenlight-hook.sh

This is a shell script that Claude Code calls whenever it needs permission. It forwards the request to Greenlight's relay server and waits for your response.

Step 3: Configure Claude Code

Add a hook to your per-project settings file. Create or edit .claude/settings.local.json in your project root:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/greenlight-hook.sh --device-id YOUR_DEVICE_ID --project myproject --activity"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "~/greenlight-hook.sh --device-id YOUR_DEVICE_ID --project myproject"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/greenlight-hook.sh --device-id YOUR_DEVICE_ID --project myproject --activity"
          }
        ]
      }
    ]
  }
}

Replace YOUR_DEVICE_ID with the ID from the app. Replace myproject with whatever you want the project badge to say in the app.

What the flags do

Flag	Purpose
--device-id	Routes requests to your phone. Required.
--project	Adds a project badge so you know which codebase the request is from. Rules are scoped per-project.
--activity	Streams Claude's transcript to the Activity tab so you can see what Claude is doing in real time. Requires Greenlight Pro. Optional.

The Notification hook

The Notification hook with idle_prompt matcher sends a push notification when Claude has finished and is waiting for your next prompt. Optional but useful if you're away from the terminal.

The UserPromptSubmit hook

The UserPromptSubmit hook starts the transcript streamer as soon as you submit a prompt, so the activity stream begins immediately rather than waiting for the first permission request. Recommended if you use --activity.

Global vs. per-project

Do not add the hook to your global config (~/.claude/settings.json). Claude Code merges global and project settings, so you'd get duplicate requests. Keep it per-project.

Step 4: Test It

claude "list files in /etc"

You should see a request appear on your phone. Tap Allow and Claude will continue. If you tap Always Allow, a rule is created and Claude won't ask again for that class of command in this project.

How the Rules Work

Rules are the core of the system. Tapping "Always Allow" doesn't just approve the request — it generates a pattern that auto-approves future matching commands without interrupting you.

Pattern generation

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

Destructive command safety

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, not rm -rf /tmp/coverage /etc.

Compound commands

When Claude runs git add . && git commit -m "msg" && git push, the system splits it into three segments and generates a separate pattern for each. All segments must have matching rules for the compound command to auto-approve. If you've granted git add and git commit but not git push, the compound command still comes to your phone.

In the app, each segment is color-coded by risk (green/orange/red) and segments already covered by rules show a checkmark overlay — so you can see at a glance which part of the command is the one that needs your attention.

File operations

For Read, Write, and Edit tools, patterns match on the directory. Granting an edit to /home/user/project/src/main.go creates the pattern Edit(/home/user/project/src/**), which covers future edits in that directory.

Interactive Prompts

Greenlight handles Claude Code's interactive features too:

• AskUserQuestion — renders as radio buttons (single-select) or checkboxes (multi-select) with an "Other" free-text option, right on your phone.
• ExitPlanMode — shows Claude's plan with full markdown rendering (headers, bullets, code blocks) and the allowed actions.

Tips

• The first few sessions generate the most requests. Once you've built up rules for your common patterns, interruptions drop off quickly.
• Check the Grants tab to see your rules grouped by project. Swipe left to delete any rule.
• If you're in a Focus mode on iOS, make sure Time Sensitive notifications are allowed for Greenlight — permission requests use this priority.
• The timeout is 590 seconds by default. Adjust with --timeout SECONDS in the hook command.

Troubleshooting

See the troubleshooting section of the support page for common issues.

Questions?

Email greenlight@dnmfarrell.com.