{"id":47668648,"url":"https://github.com/f/poke-gate","last_synced_at":"2026-04-02T12:11:08.253Z","repository":{"id":346424122,"uuid":"1189919178","full_name":"f/poke-gate","owner":"f","description":"Expose your machine to your Poke AI assistant via MCP tunnel","archived":false,"fork":false,"pushed_at":"2026-03-24T11:16:10.000Z","size":3319,"stargazers_count":24,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T17:59:31.638Z","etag":null,"topics":["ai","cli","mcp","os","poke","remote","shell","tunnel"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T19:49:45.000Z","updated_at":"2026-03-24T12:24:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/f/poke-gate","commit_stats":null,"previous_names":["f/poke-gate"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/f/poke-gate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fpoke-gate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fpoke-gate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fpoke-gate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fpoke-gate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f","download_url":"https://codeload.github.com/f/poke-gate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fpoke-gate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","mcp","os","poke","remote","shell","tunnel"],"created_at":"2026-04-02T12:11:07.494Z","updated_at":"2026-04-02T12:11:08.240Z","avatar_url":"https://github.com/f.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" width=\"128\" height=\"128\" alt=\"Poke Gate icon\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePoke Gate\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Let your \u003ca href=\"https://poke.com\"\u003ePoke\u003c/a\u003e AI assistant access your machine.\u003cbr\u003e\n  \u003csub\u003eA community project — not affiliated with Poke or The Interaction Company.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/f/poke-gate/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/f/poke-gate?style=flat-square\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/poke-gate\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/poke-gate?style=flat-square\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/f/poke-gate/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/f/poke-gate?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%2015%2B-blue?style=flat-square\" alt=\"Platform\"\u003e\n\u003c/p\u003e\n\n---\n\nRun 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.\n\n## Install\n\n**Homebrew** (recommended)\n\n```bash\nbrew install f/tap/poke-gate\n```\n\n**Install via npx**\n\nIf you have Node.js installed, you can download and install the macOS app with a single command:\n\n```bash\nnpx poke-gate download-macos\n```\n\nThis downloads the latest DMG from GitHub Releases, installs the app to `/Applications`, and clears the quarantine flag automatically.\n\n**Don't have Node.js?** Install it first:\n\n```bash\n# Option 1: Homebrew\nbrew install node\n\n# Option 2: Download from https://nodejs.org\n```\n\n**Manual download**\n\nDownload the latest **Poke.macOS.Gate.dmg** from [Releases](https://github.com/f/poke-gate/releases), open it, and drag to Applications. Since the app is not notarized, you may need to run:\n\n```bash\nxattr -cr /Applications/Poke\\ macOS\\ Gate.app\n```\n\n**CLI only** (no macOS app needed)\n\nIf you just want to run poke-gate from the terminal without the menu bar app:\n\n```bash\nnpx poke-gate\n```\n\n## Setup\n\n1. Open Poke Gate from your menu bar\n2. The **Setup View** guides you through choosing an access mode and granting Accessibility permission\n3. Sign in with Poke OAuth when prompted — a browser window opens automatically\n\nThe app connects automatically and shows a green dot when ready.\n\n## How it works\n\n```mermaid\nflowchart TD\n    A[\"You message Poke\\nfrom iMessage / Telegram / SMS\"] --\u003e B[\"Poke Agent\"]\n    B --\u003e C[\"Agent calls MCP tool\"]\n    C --\u003e D[\"MCP Tunnel (WebSocket)\"]\n    D --\u003e E[\"Poke Gate on your Mac\"]\n    E --\u003e F[\"Runs command / reads file / takes screenshot\"]\n    F --\u003e D\n    D --\u003e B\n    B --\u003e A\n```\n\nPoke 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.\n\n## Tools\n\n| Tool | What it does |\n|------|-------------|\n| `run_command` | Execute any shell command (ls, git, brew, python, curl…) |\n| `read_file` | Read a text file |\n| `read_image` | Read an image file and return it as base64 |\n| `write_file` | Write content to a file |\n| `list_directory` | List files and directories |\n| `system_info` | OS, hostname, architecture, uptime, memory |\n| `take_screenshot` | Capture the screen (requires Screen Recording permission) |\n\n## Examples\n\nFrom iMessage or Telegram, ask Poke:\n\n- \"What's running on port 3000?\"\n- \"Show me the last 5 git commits in my project\"\n- \"How much disk space do I have left?\"\n- \"Read my ~/.zshrc and suggest improvements\"\n- \"Take a screenshot of my screen\"\n- \"Create a file called notes.txt on my Desktop\"\n\n## macOS App\n\nThe native SwiftUI menu bar app manages everything:\n\n- **First-run setup** — guided onboarding to choose an access mode and grant Accessibility permission\n- **Status** — green dot when connected, yellow when connecting, red on error\n- **Personalized** — shows \"Connected to your Poke, [name]\"\n- **Access mode** — switch between Full, Limited, and Sandbox from Settings or the popover\n- **Accessibility-first** — prompts for Accessibility permission (needed for automation) with live status updates\n- **Auto-start** — connects on launch if signed in via OAuth\n- **Auto-restart** — reconnects automatically if the connection drops\n- **Logs** — view real-time tool calls with sandbox status\n- **About** — version pulled dynamically from the app bundle\n\nThe app runs in the menu bar only (no Dock icon). Quit is the only way to stop it.\n\n### Building from source\n\nRequires macOS 15+ and Xcode 26+.\n\n```bash\ngit clone https://github.com/f/poke-gate.git\ncd poke-gate/clients/Poke\\ macOS\\ Gate\nopen Poke\\ macOS\\ Gate.xcodeproj\n```\n\nHit **Run** in Xcode, or build from the command line:\n\n```bash\n./build.sh\n```\n\n## CLI usage\n\nThe CLI requires [Node.js](https://nodejs.org) 18 or later. If you don't have it, install via `brew install node` or download from [nodejs.org](https://nodejs.org).\n\nStart the gate:\n\n```bash\nnpx poke-gate\n```\n\nOn first run, Poke OAuth opens in your browser. Add `--verbose` to see tool calls in real time:\n\n```bash\nnpx poke-gate --verbose\n```\n\nSet the access mode with `--mode`:\n\n```bash\nnpx poke-gate --mode limited\nnpx poke-gate --mode sandbox\n```\n\nInstall or update the macOS app:\n\n```bash\nnpx poke-gate download-macos\n```\n\nConfig is stored at `~/.config/poke-gate/config.json`.\n\n## Agents\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/agents-editor.png\" width=\"600\" alt=\"Agents Editor\"\u003e\n\u003c/p\u003e\n\nAgents are scheduled scripts that run automatically in the background. They live in `~/.config/poke-gate/agents/` and follow a simple naming convention:\n\n```\n\u003cname\u003e.\u003cinterval\u003e.js\n```\n\n| File | Runs |\n|------|------|\n| `beeper.1h.js` | Every hour |\n| `backup.2h.js` | Every 2 hours |\n| `health.10m.js` | Every 10 minutes |\n| `cleanup.30m.js` | Every 30 minutes |\n\nIntervals: `Nm` (minutes) or `Nh` (hours). Minimum is 10 minutes.\n\n### Install an agent\n\nDownload a community agent from the repository:\n\n```bash\nnpx poke-gate agent get beeper\n```\n\nThis downloads `beeper.1h.js` and `.env.beeper` to `~/.config/poke-gate/agents/`. Edit the env file with your credentials and test it:\n\n```bash\nnano ~/.config/poke-gate/agents/.env.beeper\nnpx poke-gate run-agent beeper\n```\n\n### Per-agent env files\n\nEach agent can have a `.env.\u003cname\u003e` file for secrets:\n\n```\n~/.config/poke-gate/agents/.env.beeper\n```\n\n```env\nBEEPER_TOKEN=your_token_here\n```\n\nVariables are injected into the agent process automatically.\n\n### Agent frontmatter\n\nEach agent file starts with a JSDoc-style frontmatter block:\n\n```javascript\n/**\n * @agent beeper\n * @name Beeper Message Digest\n * @description Fetches messages from the last hour and sends a summary to Poke.\n * @interval 1h\n * @env BEEPER_TOKEN - Beeper Desktop local API token\n * @author f\n */\n```\n\n### Creating your own agent\n\nAn agent is just a JS file that runs with Node.js. It has access to:\n\n- `process.env` — variables from `.env.\u003cname\u003e`\n- `poke` package — `import { Poke, getToken } from \"poke\"`\n- Any npm package installed globally or via npx\n\n```javascript\n/**\n * @agent my-agent\n * @name My Custom Agent\n * @description Does something useful every 30 minutes.\n * @interval 30m\n */\n\nimport { Poke, getToken } from \"poke\";\n\nconst poke = new Poke({ apiKey: getToken() });\nawait poke.sendMessage(\"Hello from my agent!\");\n```\n\nSave as `~/.config/poke-gate/agents/my-agent.30m.js` and it runs automatically when poke-gate is connected.\n\nAgents start running when poke-gate connects and run once immediately on startup.\n\n## Access modes\n\nPoke Gate supports three access modes that control what your agent can do:\n\n| Mode | Description |\n|------|-------------|\n| **Full** (default) | All tools available with no approval required. The agent can run commands, write files, and take screenshots directly. |\n| **Limited** | Read-only tools plus a curated set of safe commands (`ls`, `cat`, `grep`, `curl`, etc.). `write_file` and `take_screenshot` are disabled. |\n| **Sandbox** | Broader command support than Limited, but writes are restricted to `~/Downloads` and `/tmp` via macOS `sandbox-exec`. |\n\nSet the mode via CLI flag, environment variable, or the macOS app Settings:\n\n```bash\nnpx poke-gate --mode sandbox\n# or\nPOKE_GATE_PERMISSION_MODE=limited npx poke-gate\n```\n\n## Security\n\n**In full mode, Poke Gate grants full shell access to your Poke agent.** This means:\n\n- Any command can be run with your user's permissions\n- Files can be read and written anywhere your user has access\n- Risky tools require approval in chat before execution\n- Only your Poke agent (authenticated via Poke OAuth) can reach the tunnel\n\nOnly run Poke Gate on machines and networks you trust. Use `limited` or `sandbox` mode if you want tighter restrictions.\n\n## Credits\n\n- [Poke](https://poke.com) by [The Interaction Company of California](https://interaction.co)\n- [Poke SDK](https://www.npmjs.com/package/poke)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff%2Fpoke-gate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff%2Fpoke-gate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff%2Fpoke-gate/lists"}