Skip to main content
Once you’ve created an integration, you get a hook command you can drop into any tool that runs a command when it finishes. This page has a ready-to-use recipe for each tool in the integration library, written for macOS.
This page covers macOS. Running Proximate on Windows? See Advanced Integration Recipes for Windows — the commands are different.

​
Before You Start

Create an integration in Proximate first (see the Setup guide). With the platform toggle set to macOS, copy the Success command — it looks like this: 
open "proximate://notify?source=YOUR_ID&status=success"
Everywhere you see YOUR_ID below, use the ID from your own copied command. The status at the end of the URL (success, warning, error, or none) sets the badge color.

​
Two Patterns You’ll Reuse

Most command-line tools don’t have a built-in “when I’m done” hook, so you run the Proximate command right after them. There are two ways to do it. Just tell me when it’s done — chain with &&: 
your-command && open "proximate://notify?source=YOUR_ID&status=success"
Tell me whether it passed or failed — wrap it in if so a failure shows a red badge: 
if your-command; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi
The recipes below plug each tool into one of these patterns. A few tools have a smarter, native hook — those are called out individually.

​
Claude Code CLI

Claude Code has a native Stop hook that fires whenever Claude finishes responding. The short version: add this to ~/.claude/settings.json.
~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "open \"proximate://notify?source=YOUR_ID&status=success\""
          }
        ]
      }
    ]
  }
}

Full Claude Code walkthrough

See the complete step-by-step guide, including how to verify the hook with /hooks.

​
Docker CLI

Docker has no completion hook, so chain the command after a long build or compose up: 
if docker build -t myapp .; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi
The same pattern works for docker compose up --build, docker push, or any other long-running Docker command.

​
FFmpeg

Get a badge the moment a long encode finishes: 
if ffmpeg -i input.mov -c:v libx264 output.mp4; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi

​
Gradle

Chain the command after your Gradle task: 
if ./gradlew build; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi
Avoid the old gradle.buildFinished { … } listener — it’s deprecated (since Gradle 7.4) and doesn’t work with the configuration cache. Chaining the command in the shell is simpler and future-proof.

​
Homebrew

Long brew upgrade runs are a perfect fit: 
brew upgrade && open "proximate://notify?source=YOUR_ID&status=success"

​
Jest

The quick way is to chain it after your test command: 
jest && open "proximate://notify?source=YOUR_ID&status=success" \
     || open "proximate://notify?source=YOUR_ID&status=error"
For a cleaner setup that always reports the right color, add a small custom reporter. Save this as proximate-reporter.js in your project:
proximate-reporter.js
const { execSync } = require('child_process');

class ProximateReporter {
  onRunComplete(contexts, results) {
    const status = results.success ? 'success' : 'error';
    execSync(`open "proximate://notify?source=YOUR_ID&status=${status}"`);
  }
}

module.exports = ProximateReporter;
Then register it in jest.config.js:
jest.config.js
module.exports = {
  reporters: ['default', '<rootDir>/proximate-reporter.js'],
};

​
make

Chain the command after your build: 
make && open "proximate://notify?source=YOUR_ID&status=success"
Or bake it into your Makefile as the last step of a target: 
build:
	# ... your build steps ...
	@open "proximate://notify?source=YOUR_ID&status=success"

​
n8n (Local)

In a self-hosted n8n, add an Execute Command node as the last step of your workflow, so it fires when the workflow finishes.
1

Add an Execute Command node

Add a node and search for Execute Command.
2

Enter the command

In the Command field, enter:
open "proximate://notify?source=YOUR_ID&status=success"
3

Connect it last

Wire it in as the final node in the workflow.
The Execute Command node is disabled by default in n8n v2.0+ and isn’t available on n8n Cloud. If you run n8n in Docker, the command executes inside the container, not on your Mac — run n8n directly on the machine where Proximate is installed.

​
pytest

Add a conftest.py to your project (or extend an existing one) using pytest’s native pytest_sessionfinish hook, which runs after the whole test session and receives the exit status (0 means everything passed):
conftest.py
import subprocess

def pytest_sessionfinish(session, exitstatus):
    status = "success" if exitstatus == 0 else "error"
    subprocess.run(["open", f"proximate://notify?source=YOUR_ID&status={status}"])
Now every pytest run ends with a green badge on pass, red on failure — no shell chaining needed.

​
Rust

Chain the command after cargo build, cargo test, or cargo run: 
if cargo build --release; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi
Cargo’s build.rs runs before compilation, so it’s not the place for a finish notification — chaining in the shell is the right approach.

​
Terraform

Get a badge when a long apply completes: 
if terraform apply -auto-approve; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi

​
Xcode CLI

From the command line (xcodebuild), use the standard pattern: 
if xcodebuild -scheme MyApp build; then
  open "proximate://notify?source=YOUR_ID&status=success"
else
  open "proximate://notify?source=YOUR_ID&status=error"
fi
Inside the Xcode app, you can attach a post-action to a scheme so a badge fires after every build or test:
1

Open the scheme editor

In Xcode, choose Product → Scheme → Edit Scheme… (or press ⌘<).
2

Add a post-action

Expand Build (or Test) in the left list, select Post-actions, then click + → New Run Script Action.
3

Enter the command

Set Provide build settings from to your app target, then enter:
open "proximate://notify?source=YOUR_ID&status=success"
Scheme post-actions run after the phase completes but don’t branch on success or failure, so this is best used as a “build finished” (neutral or success) signal rather than a pass/fail one.

​
A Couple of Edge Cases

  • success && … || error can mislead. With the one-line cmd && open success || open error form, if the open success step itself fails, the error command runs too. The if … then … else … fi form avoids this, which is why the recipes above prefer it whenever pass/fail matters.
  • Keep the quotes. The & in the URL is meaningful to your shell, so the command must stay inside double quotes (open "…"). The card copies it that way already.
Don’t see your tool? Any tool that can run a command on completion works — use one of the two patterns at the top. If a badge isn’t showing up, see Troubleshooting.