poke-gate 0.1.0 → 0.1.4

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: Your Mac, controlled by AI — from anywhere.
+  tagline: Give your Poke AI assistant access to your machine. Run commands, read files, take screenshots — all from iMessage, Telegram, or SMS.
+  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
+```