poke-gate 0.1.1 → 0.1.5

package/docs/agents/installing.md

@@ -0,0 +1,66 @@
+# Installing Agents
+
+You can download community agents from the Poke Gate repository with a single command.
+
+## Install an agent
+
+```bash
+npx poke-gate agent get <name>
+```
+
+For example:
+
+```bash
+npx poke-gate agent get beeper
+```
+
+This does three things:
+
+1. **Downloads the agent script** from GitHub to `~/.config/poke-gate/agents/`
+2. **Downloads the env template** (if one exists)
+3. **Prompts you to fill in env variables** interactively
+
+## Interactive env setup
+
+If the agent needs secrets, you'll be prompted:
+
+```
+Fetching agent "beeper" from GitHub...
+  Saved: ~/.config/poke-gate/agents/beeper.1h.js
+
+  This agent needs 1 env variable(s):
+
+  BEEPER_TOKEN (Find it in Beeper Desktop > Settings > API): █
+
+  Saved: ~/.config/poke-gate/agents/.env.beeper
+
+  Test it: npx poke-gate run-agent beeper
+```
+
+The prompt parses the `.env` template, identifies placeholder values, and asks you for real ones. Comments from the template are shown as hints.
+
+## Test after installing
+
+Always test the agent before relying on it:
+
+```bash
+npx poke-gate run-agent beeper
+```
+
+## Existing env files
+
+If you already have a `.env.<name>` file, it won't be overwritten. You'll see:
+
+```
+.env.beeper already exists, skipped.
+```
+
+## Browse available agents
+
+See all community agents at:
+
+[github.com/f/poke-gate/tree/main/examples/agents](https://github.com/f/poke-gate/tree/main/examples/agents)
+
+## Install via macOS app
+
+You can also manage agents through the macOS app's **Agents** window — browse, edit, and create agents with a built-in syntax-highlighted editor.

package/docs/agents/sharing.md

@@ -0,0 +1,97 @@
+# Sharing Agents
+
+Built a useful agent? Share it with the community by opening a pull request.
+
+## How sharing works
+
+Community agents live in the [`examples/agents/`](https://github.com/f/poke-gate/tree/main/examples/agents) directory of the Poke Gate repository. Anyone can install them with:
+
+```bash
+npx poke-gate agent get <name>
+```
+
+## Submit your agent
+
+### 1. Fork the repo
+
+Go to [github.com/f/poke-gate](https://github.com/f/poke-gate) and click **Fork**.
+
+### 2. Add your agent files
+
+Place your files in `examples/agents/`:
+
+```
+examples/agents/
+  your-agent.1h.js      # The agent script
+  .env.your-agent       # Env template with placeholder values
+```
+
+### 3. Agent checklist
+
+Before submitting, make sure your agent:
+
+- Has a **frontmatter block** with `@agent`, `@name`, `@description`, `@interval`, `@env`, `@author`
+- Uses **placeholder values** in the `.env` file (e.g. `YOUR_TOKEN_HERE`) — never real credentials
+- Has **comments in the `.env`** explaining where to find each value
+- Handles **errors gracefully** — logs useful messages, doesn't crash silently
+- Stays within the **5-minute timeout**
+- Uses `getToken()` from the Poke SDK for authentication (not hardcoded tokens)
+
+### 4. Frontmatter example
+
+```javascript
+/**
+ * @agent your-agent
+ * @name Your Agent Name
+ * @description Clear one-line description of what this agent does.
+ * @interval 1h
+ * @env API_TOKEN - Where to find this token
+ * @env BASE_URL - (optional) Override the default URL
+ * @author your-github-username
+ */
+```
+
+### 5. Env template example
+
+```env
+# Where to find this token: App > Settings > API
+API_TOKEN=your_token_here
+
+# Optional: override the default API URL
+# BASE_URL=http://localhost:8080
+```
+
+Use `your_*_here` as placeholder values — the installer detects these and prompts the user.
+
+### 6. Open a PR
+
+Push to your fork and open a pull request to `f/poke-gate` with:
+
+- **Title:** `agent: add <name>`
+- **Description:** What the agent does, what service it connects to, any prerequisites
+
+```bash
+git checkout -b agent/your-agent
+git add examples/agents/
+git commit -m "agent: add your-agent"
+git push origin agent/your-agent
+```
+
+Then open the PR at [github.com/f/poke-gate/compare](https://github.com/f/poke-gate/compare).
+
+## Agent ideas
+
+Looking for inspiration? Here are some agents the community would love:
+
+| Idea | What it does |
+|------|-------------|
+| **GitHub notifications** | Fetch unread notifications and send a digest |
+| **Calendar summary** | Summarize today's upcoming meetings |
+| **Disk space monitor** | Alert when disk space is below a threshold |
+| **Uptime checker** | Ping a list of URLs and report any downtime |
+| **RSS reader** | Fetch latest articles from your feeds |
+| **Git status** | Report uncommitted changes across your projects |
+| **Docker health** | Check running containers and their status |
+| **Mail digest** | Summarize unread emails from a local mail client |
+
+Build one and share it!

package/docs/cli.md

@@ -0,0 +1,73 @@
+# CLI Reference
+
+## Start the gate
+
+```bash
+npx poke-gate
+```
+
+Starts the MCP server, connects the tunnel, and begins the agent scheduler. On first run, if you're not signed in, opens Poke OAuth in your browser.
+
+### Verbose mode
+
+```bash
+npx poke-gate --verbose
+# or
+npx poke-gate -v
+```
+
+Shows real-time tool calls:
+
+```
+[14:52:01] tool: run_command
+[14:52:01]   $ ls -la ~/Code
+[14:52:03] tool: read_file
+[14:52:03]   read: ~/.zshrc
+```
+
+## Run an agent
+
+```bash
+npx poke-gate run-agent <name>
+```
+
+Runs a single agent script immediately and exits. Useful for testing.
+
+**Example:**
+
+```bash
+npx poke-gate run-agent beeper
+```
+
+Finds `~/.config/poke-gate/agents/beeper.*.js` and runs it with the env from `.env.beeper`.
+
+## Install an agent
+
+```bash
+npx poke-gate agent get <name>
+```
+
+Downloads an agent from the [community repository](https://github.com/f/poke-gate/tree/main/examples/agents) and saves it to `~/.config/poke-gate/agents/`.
+
+If the agent has an `.env` file, you'll be prompted to fill in the values:
+
+```
+Fetching agent "beeper" from GitHub...
+  Saved: ~/.config/poke-gate/agents/beeper.1h.js
+
+  This agent needs 1 env variable(s):
+
+  BEEPER_TOKEN (Find it in Beeper Desktop > Settings > API): <you type>
+
+  Saved: ~/.config/poke-gate/agents/.env.beeper
+
+  Test it: npx poke-gate run-agent beeper
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `POKE_API_KEY` | Override the API key (skips OAuth) |
+| `POKE_API` | Override the Poke API base URL |
+| `POKE_FRONTEND` | Override the Poke frontend URL |

package/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting Started
+
+## Install
+
+### Homebrew
+
+The recommended way to install the macOS app:
+
+```bash
+brew install f/tap/poke-gate
+```
+
+### Manual download
+
+Download the latest **Poke.macOS.Gate.dmg** from [GitHub Releases](https://github.com/f/poke-gate/releases/latest), open it, and drag to Applications.
+
+Since the app is not notarized, you may need to run:
+
+```bash
+xattr -cr /Applications/Poke\ macOS\ Gate.app
+```
+
+### CLI only
+
+If you don't need the macOS app:
+
+```bash
+npx poke-gate
+```
+
+## Sign in
+
+Poke Gate uses Poke OAuth to authenticate. On first launch:
+
+1. Open Poke Gate from your menu bar
+2. The app starts and connects automatically
+3. If you're not signed in, a browser window opens for Poke OAuth
+4. After signing in, the connection is established
+
+You can also sign in manually:
+
+```bash
+npx poke login
+```
+
+## Verify it works
+
+Once connected, you'll see a green dot in the menu bar. The popover shows:
+
+> ● Connected to your Poke, [your name]
+
+Now open iMessage or Telegram and message your Poke:
+
+> "What's my hostname?"
+
+Poke will use the `system_info` tool to answer from your machine.
+
+## What's next?
+
+- [How It Works](/how-it-works) — understand the architecture
+- [Tools](/tools) — see all available tools
+- [Agents](/agents/) — set up scheduled automation

package/docs/how-it-works.md

@@ -0,0 +1,56 @@
+# How It Works
+
+Poke Gate bridges your machine to Poke's cloud so your AI assistant can execute tasks locally.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["You (iMessage)"] --> B["Poke Agent"]
+    B --> C["MCP Tunnel"]
+    C --> D["Poke Gate"]
+    D --> E["Executes locally"]
+    E --> C
+    C --> B
+    B --> A
+```
+
+## Step by step
+
+1. **You send a message** to Poke from iMessage, Telegram, or SMS — e.g. "What's running on port 3000?"
+
+2. **Poke's agent processes it** and decides it needs your machine to answer. It picks a tool like `run_command`.
+
+3. **The tool call travels through the MCP tunnel** — a WebSocket connection from Poke's cloud to your machine via the Piko protocol.
+
+4. **Poke Gate receives the call** on your local MCP server (a lightweight HTTP server running on localhost).
+
+5. **The tool executes locally** — runs the shell command, reads the file, takes the screenshot, etc.
+
+6. **The result flows back** through the tunnel to Poke's agent, which formats it and replies to you.
+
+## Key components
+
+### MCP Server
+
+A local HTTP server that implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) using raw JSON-RPC over HTTP. It exposes tools like `run_command`, `read_file`, etc.
+
+### PokeTunnel
+
+A WebSocket-based tunnel from the [Poke SDK](https://www.npmjs.com/package/poke) that connects your local MCP server to Poke's cloud. Uses the Piko protocol with Yamux multiplexing for reliable, multiplexed communication.
+
+### Connection lifecycle
+
+- On startup, Poke Gate creates a connection via `POST /mcp/connections/cli`
+- A WebSocket tunnel is established to the upstream URL
+- Poke's cloud can now route tool calls through the tunnel to your machine
+- If the connection drops, it reconnects automatically
+- Old connections are cleaned up before creating new ones to prevent duplicates
+
+## On-connect notification
+
+When the tunnel connects, Poke Gate sends a message to your Poke agent:
+
+> "Hey! I've connected my computer to you via Poke Gate. You can now run commands, read and write files, list directories, take screenshots, and check system info on my machine."
+
+This ensures the agent knows your machine is available and which tools it can use.

package/docs/index.md

@@ -0,0 +1,63 @@
+---
+layout: home
+
+hero:
+  name: Poke Gate
+  text: A two-way bridge between your Mac and your AI.
+  tagline: Poke pulls from your Mac when you ask. Your Mac pushes to Poke when something happens. Run commands, read files, take screenshots — and automate it all with Agents.
+  image:
+    src: /logo.png
+    alt: Poke Gate
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/f/poke-gate
+
+features:
+  - icon: 🖥️
+    title: Full Shell Access
+    details: Run any terminal command on your machine — ls, git, brew, python, curl, and more.
+  - icon: 📁
+    title: File Operations
+    details: Read, write, and list files and directories. Your Poke agent sees your filesystem.
+  - icon: 📸
+    title: Screenshots
+    details: Capture your screen remotely. Poke can see what you see.
+  - icon: 🤖
+    title: Agents
+    details: Scheduled scripts that run in the background — automate message digests, backups, health checks.
+  - icon: 🌴
+    title: macOS Menu Bar App
+    details: Native SwiftUI app that lives in your menu bar. Auto-connects, auto-restarts, shows real-time status.
+  - icon: ⚡
+    title: MCP Tunnel
+    details: Secure WebSocket tunnel powered by the Poke SDK. Only your authenticated agent can reach your machine.
+---
+
+## Quick install
+
+::: code-group
+
+```bash [Homebrew]
+brew install f/tap/poke-gate
+```
+
+```bash [npm]
+npx poke-gate
+```
+
+```bash [Manual]
+# Download from GitHub Releases
+# https://github.com/f/poke-gate/releases/latest
+```
+
+:::
+
+<br>
+
+::: tip Community project
+Poke Gate is open source and not affiliated with Poke or The Interaction Company of California.
+:::

package/docs/macos-app.md

@@ -0,0 +1,74 @@
+# macOS App
+
+Poke Gate includes a native SwiftUI menu bar app for macOS.
+
+## Menu bar
+
+The app runs in the menu bar only — no Dock icon. Click the door icon to see the popover:
+
+- **Status** — green dot when connected, yellow when connecting, red on error
+- **Personalized** — shows "Connected to your Poke, [name]"
+- **Recent activity** — last few log entries
+- **Action buttons** — Logs, Agents, Settings, Restart/Start, Quit
+- **About** — version, GitHub link
+
+### Status icons
+
+| Icon | Meaning |
+|------|---------|
+| 🚪 (open) | Connected |
+| 🚪 (closed) | Stopped or connecting |
+| ⚠️ | Error |
+
+## Settings
+
+Open Settings from the popover. The settings window shows:
+
+- **Authentication status** — whether you're signed in via Poke OAuth
+- **Sign in button** — runs `npx poke login` and opens a browser window
+- **Connection status** — current state with a Reconnect button
+
+## Logs
+
+The Logs window shows real-time activity:
+
+- Tool calls are highlighted
+- Errors appear in red
+- Copy all logs to clipboard
+- Clear logs
+
+## Agents Editor
+
+The Agents window provides a built-in editor for managing agent scripts — no external editor needed.
+
+<img src="/agents-editor.png" alt="Agents Editor" style="border-radius: 8px; border: 1px solid var(--vp-c-divider); margin: 16px 0;" />
+
+- **Sidebar** — lists agents by `@name` from frontmatter, with interval badges and descriptions
+- **Editor** — native syntax-highlighted code editor for JavaScript and env files
+- **Tab bar** — switch between `.js` file and `.env` file
+- **Interval editor** — change the schedule by typing a new interval (renames the file automatically)
+- **New Agent** — creates a template agent with frontmatter
+- **Delete** — right-click to remove an agent and its env file
+
+Learn more about agents in the [Agents documentation](/agents/).
+
+## Auto-start
+
+The app connects automatically on launch if you've previously signed in. If the connection drops, it reconnects after 2 seconds.
+
+## Building from source
+
+Requires macOS 15+ and Xcode 26+.
+
+```bash
+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 a universal DMG:
+
+```bash
+cd poke-gate
+./build.sh
+```