Run Poke Gate on your Mac, then message Poke from iMessage, Telegram, or SMS to run commands, read files, take screenshots, and more — all on your machine.

Install

Homebrew (recommended)

brew install f/tap/poke-gate

Install via npx

If you have Node.js installed, you can download and install the macOS app with a single command:

npx poke-gate download-macos

This downloads the latest DMG from GitHub Releases, installs the app to /Applications, and clears the quarantine flag automatically.

Don't have Node.js? Install it first:

# Option 1: Homebrew
brew install node

# Option 2: Download from https://nodejs.org

Manual download

Download the latest Poke.macOS.Gate.dmg from Releases, open it, and drag to Applications. Since the app is not notarized, you may need to run:

xattr -cr /Applications/Poke\ macOS\ Gate.app

CLI only (no macOS app needed)

If you just want to run poke-gate from the terminal without the menu bar app:

npx poke-gate

Setup

1. Open Poke Gate from your menu bar
2. The Setup View guides you through choosing an access mode and granting Accessibility permission
3. Sign in with Poke OAuth when prompted — a browser window opens automatically

The app connects automatically and shows a green dot when ready.

How it works

flowchart TD
    A["You message Poke\nfrom iMessage / Telegram / SMS"] --> B["Poke Agent"]
    B --> C["Agent calls MCP tool"]
    C --> D["MCP Tunnel (WebSocket)"]
    D --> E["Poke Gate on your Mac"]
    E --> F["Runs command / reads file / takes screenshot"]
    F --> D
    D --> B
    B --> A

Poke Gate runs a local MCP server and tunnels it to Poke's cloud. When you ask Poke something that needs your machine, the agent calls the tools, Poke Gate executes them locally, and the result flows back to your chat.

Tools

| Tool | What it does | |------|-------------| | run_command | Execute any shell command (ls, git, brew, python, curl…) | | read_file | Read a text file | | read_image | Read an image file and return it as base64 | | write_file | Write content to a file | | list_directory | List files and directories | | system_info | OS, hostname, architecture, uptime, memory | | take_screenshot | Capture the screen (requires Screen Recording permission) |

Examples

From iMessage or Telegram, ask Poke:

• "What's running on port 3000?"
• "Show me the last 5 git commits in my project"
• "How much disk space do I have left?"
• "Read my ~/.zshrc and suggest improvements"
• "Take a screenshot of my screen"
• "Create a file called notes.txt on my Desktop"

macOS App

The native SwiftUI menu bar app manages everything:

• First-run setup — guided onboarding to choose an access mode and grant Accessibility permission
• Status — green dot when connected, yellow when connecting, red on error
• Personalized — shows "Connected to your Poke, [name]"
• Access mode — switch between Full, Limited, and Sandbox from Settings or the popover
• Accessibility-first — prompts for Accessibility permission (needed for automation) with live status updates
• Auto-start — connects on launch if signed in via OAuth
• Auto-restart — reconnects automatically if the connection drops
• Logs — view real-time tool calls with sandbox status
• About — version pulled dynamically from the app bundle

The app runs in the menu bar only (no Dock icon). Quit is the only way to stop it.

Building from source

Requires macOS 15+ and Xcode 26+.

git clone https://github.com/f/poke-gate.git
cd poke-gate/clients/Poke\ macOS\ Gate
open Poke\ macOS\ Gate.xcodeproj

Hit Run in Xcode, or build from the command line:

./build.sh

CLI usage

The CLI requires Node.js 18 or later. If you don't have it, install via brew install node or download from nodejs.org.

Start the gate:

npx poke-gate

On first run, Poke OAuth opens in your browser. Add --verbose to see tool calls in real time:

npx poke-gate --verbose

Set the access mode with --mode:

npx poke-gate --mode limited
npx poke-gate --mode sandbox

Install or update the macOS app:

npx poke-gate download-macos

Config is stored at ~/.config/poke-gate/config.json.

Agents

Agents are scheduled scripts that run automatically in the background. They live in ~/.config/poke-gate/agents/ and follow a simple naming convention:

<name>.<interval>.js

| File | Runs | |------|------| | beeper.1h.js | Every hour | | backup.2h.js | Every 2 hours | | health.10m.js | Every 10 minutes | | cleanup.30m.js | Every 30 minutes |

Intervals: Nm (minutes) or Nh (hours). Minimum is 10 minutes.

Install an agent

Download a community agent from the repository:

npx poke-gate agent get beeper

This downloads beeper.1h.js and .env.beeper to ~/.config/poke-gate/agents/. Edit the env file with your credentials and test it:

nano ~/.config/poke-gate/agents/.env.beeper
npx poke-gate run-agent beeper

Per-agent env files

Each agent can have a .env.<name> file for secrets:

~/.config/poke-gate/agents/.env.beeper

BEEPER_TOKEN=your_token_here

Variables are injected into the agent process automatically.

Agent frontmatter

Each agent file starts with a JSDoc-style frontmatter block:

/**
 * @agent beeper
 * @name Beeper Message Digest
 * @description Fetches messages from the last hour and sends a summary to Poke.
 * @interval 1h
 * @env BEEPER_TOKEN - Beeper Desktop local API token
 * @author f
 */

Creating your own agent

An agent is just a JS file that runs with Node.js. It has access to:

• process.env — variables from .env.<name>
• poke package — import { Poke, getToken } from "poke"
• Any npm package installed globally or via npx

/**
 * @agent my-agent
 * @name My Custom Agent
 * @description Does something useful every 30 minutes.
 * @interval 30m
 */

import { Poke, getToken } from "poke";

const poke = new Poke({ apiKey: getToken() });
await poke.sendMessage("Hello from my agent!");

Save as ~/.config/poke-gate/agents/my-agent.30m.js and it runs automatically when poke-gate is connected.

Agents start running when poke-gate connects and run once immediately on startup.

Access modes

Poke Gate supports three access modes that control what your agent can do:

| Mode | Description | |------|-------------| | Full (default) | All tools available with no approval required. The agent can run commands, write files, and take screenshots directly. | | Limited | Read-only tools plus a curated set of safe commands (ls, cat, grep, curl, etc.). write_file and take_screenshot are disabled. | | Sandbox | Broader command support than Limited, but writes are restricted to ~/Downloads and /tmp via macOS sandbox-exec. |

Set the mode via CLI flag, environment variable, or the macOS app Settings:

npx poke-gate --mode sandbox
# or
POKE_GATE_PERMISSION_MODE=limited npx poke-gate

Security

In full mode, Poke Gate grants full shell access to your Poke agent. This means:

• Any command can be run with your user's permissions
• Files can be read and written anywhere your user has access
• Risky tools require approval in chat before execution
• Only your Poke agent (authenticated via Poke OAuth) can reach the tunnel

Only run Poke Gate on machines and networks you trust. Use limited or sandbox mode if you want tighter restrictions.

Credits

• Poke by The Interaction Company of California
• Poke SDK

License

MIT