poke-gate 0.1.0 → 0.1.4

package/docs/agents/beeper.md

@@ -0,0 +1,107 @@
+# Beeper Agent
+
+The Beeper agent fetches messages from the last hour via [Beeper Desktop](https://beeper.com)'s local API, groups them by sender, and sends a summary to your Poke agent.
+
+## What it does
+
+Every hour:
+
+1. Calls Beeper's local API at `http://localhost:23373`
+2. Searches for messages from the last 60 minutes
+3. Filters out messages you sent (only shows incoming)
+4. Groups messages by sender name
+5. Formats a summary with sender name, message count, and last 3 messages
+6. Sends the summary to Poke via `sendMessage`
+
+## Prerequisites
+
+- [Beeper Desktop](https://beeper.com) running on your machine
+- Beeper API token (find it in Beeper Desktop > Settings > API)
+- Signed in to Poke (`npx poke login`)
+
+## Install
+
+```bash
+npx poke-gate agent get beeper
+```
+
+When prompted, paste your Beeper token:
+
+```
+BEEPER_TOKEN (Find it in Beeper Desktop > Settings > API): <paste>
+```
+
+## Test
+
+```bash
+npx poke-gate run-agent beeper
+```
+
+Expected output:
+
+```
+[agents] Running agent: beeper (beeper.1h.js)
+[agents] [beeper] Fetching messages from the last hour...
+[agents] [beeper] Found 42 messages
+[agents] [beeper] Sending summary to Poke...
+[agents] [beeper] Summary sent to Poke.
+[agents] [beeper] completed
+```
+
+## What Poke receives
+
+Your Poke agent gets a message like:
+
+> Messages from the last hour (3 people):
+>
+> Alice (5 messages):
+>   - Hey, are you free for lunch?
+>   - The meeting got moved to 3pm
+>   - Can you review my PR?
+>
+> Bob (2 messages):
+>   - Deployed the fix
+>   - All tests passing now
+>
+> Mom (1 messages):
+>   - Don't forget dinner tonight!
+
+## Configuration
+
+### Env variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BEEPER_TOKEN` | yes | Beeper Desktop API token |
+| `BEEPER_BASE_URL` | no | Override default `http://localhost:23373` |
+
+Edit: `~/.config/poke-gate/agents/.env.beeper`
+
+### Change the interval
+
+Rename the file to change how often it runs:
+
+```bash
+# Every 30 minutes
+mv ~/.config/poke-gate/agents/beeper.1h.js ~/.config/poke-gate/agents/beeper.30m.js
+```
+
+Or use the macOS Agents editor.
+
+## Frontmatter
+
+```javascript
+/**
+ * @agent beeper
+ * @name Beeper Message Digest
+ * @description Fetches messages from the last hour via Beeper Desktop and sends a summary to Poke.
+ * @interval 1h
+ * @env BEEPER_TOKEN - Beeper Desktop local API token (Settings > API)
+ * @env BEEPER_BASE_URL - (optional) Override default http://localhost:23373
+ * @author f
+ */
+```
+
+## Source
+
+[View on GitHub](https://github.com/f/poke-gate/blob/main/examples/agents/beeper.1h.js)

package/docs/agents/community.md

@@ -0,0 +1,77 @@
+# Community Agents
+
+Ready-to-use agents you can install with a single command. All agents are open source and included in the [Poke Gate repository](https://github.com/f/poke-gate/tree/main/examples/agents).
+
+## Beeper Message Digest
+
+Fetches messages from the last hour via [Beeper Desktop](https://beeper.com)'s local API, groups them by sender, and sends a summary to Poke. Great for staying on top of conversations across all your messaging platforms without checking each one.
+
+| | |
+|---|---|
+| **File** | `beeper.1h.js` |
+| **Interval** | Every hour |
+| **Requires** | Beeper Desktop running, API token |
+
+```bash
+npx poke-gate agent get beeper
+```
+
+[Full documentation →](/agents/beeper)
+
+---
+
+## Screen Time Report
+
+Sends a daily summary of your Mac usage — currently running apps, uptime, and top processes. Poke learns your work patterns and can answer questions like "what was I doing yesterday?" or "how long have I been working today?".
+
+| | |
+|---|---|
+| **File** | `screentime.24h.js` |
+| **Interval** | Every 24 hours |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get screentime
+```
+
+---
+
+## Battery Guardian
+
+Monitors your battery and alerts you via Poke when it drops below 20% on battery power. Only alerts once per discharge cycle — won't spam you. Resets when you plug in.
+
+| | |
+|---|---|
+| **File** | `battery.30m.js` |
+| **Interval** | Every 30 minutes |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get battery
+```
+
+::: tip Custom threshold
+Set `BATTERY_THRESHOLD` in `.env.battery` to change the alert level (default: 20%).
+:::
+
+---
+
+## WiFi Logger
+
+Tracks which WiFi network you're on and notifies Poke when you switch networks or disconnect. This gives Poke passive context about your location — it knows if you're at home, at the office, or at a cafe without you telling it.
+
+| | |
+|---|---|
+| **File** | `wifi.30m.js` |
+| **Interval** | Every 30 minutes |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get wifi
+```
+
+---
+
+## Want more?
+
+Check the [Sharing Agents](/agents/sharing) page for ideas and instructions on contributing your own agent to the community.

package/docs/agents/creating.md

@@ -0,0 +1,132 @@
+# Creating Agents
+
+This guide walks you through creating an agent from scratch.
+
+## Step 1: Create the file
+
+Agents live in `~/.config/poke-gate/agents/`. Create a file with the naming convention `name.interval.js`:
+
+```bash
+touch ~/.config/poke-gate/agents/hello.1h.js
+```
+
+This creates an agent called "hello" that runs every hour.
+
+## Step 2: Add frontmatter
+
+Start with the frontmatter block. This is optional but recommended — it's displayed in the macOS Agents editor.
+
+```javascript
+/**
+ * @agent hello
+ * @name Hello World
+ * @description Sends a greeting to Poke every hour.
+ * @interval 1h
+ * @author you
+ */
+```
+
+## Step 3: Write your logic
+
+Agents are standard Node.js ESM scripts. They can import the Poke SDK and any globally installed packages.
+
+```javascript
+/**
+ * @agent hello
+ * @name Hello World
+ * @description Sends a greeting to Poke every hour.
+ * @interval 1h
+ */
+
+import { Poke, getToken } from "poke";
+
+const token = getToken();
+if (!token) {
+  console.error("Not signed in. Run: npx poke login");
+  process.exit(1);
+}
+
+const poke = new Poke({ apiKey: token });
+await poke.sendMessage("Hello! This is an automated message from my Hello agent.");
+
+console.log("Sent greeting to Poke.");
+```
+
+## Step 4: Add env variables (optional)
+
+If your agent needs secrets (API tokens, URLs, etc.), create a `.env.<name>` file:
+
+```bash
+nano ~/.config/poke-gate/agents/.env.hello
+```
+
+```env
+# My custom config
+MY_API_KEY=secret_123
+```
+
+Then read them in your script:
+
+```javascript
+const apiKey = process.env.MY_API_KEY;
+```
+
+## Step 5: Test it
+
+Run your agent manually:
+
+```bash
+npx poke-gate run-agent hello
+```
+
+You should see:
+
+```
+[agents] Running agent: hello (hello.1h.js)
+[agents] [hello] Sent greeting to Poke.
+[agents] [hello] completed
+```
+
+## Step 6: Let it run
+
+Start Poke Gate normally. Your agent will be discovered and scheduled:
+
+```bash
+npx poke-gate
+```
+
+```
+[agents] Found 1 agent(s):
+  Hello World (every 1h)
+[agents] Running agent: hello (hello.1h.js)
+```
+
+## Tips
+
+- **Keep agents fast.** They have a 5-minute timeout. If your agent takes longer, it'll be killed.
+- **Use `console.log`** for debugging. Output appears in the Poke Gate logs.
+- **Handle errors gracefully.** If your agent throws, it logs the error and continues to the next scheduled run.
+- **Change the interval** by renaming the file (e.g. `hello.1h.js` → `hello.30m.js`) or using the macOS Agents editor.
+
+## Template
+
+Here's a minimal template to copy:
+
+```javascript
+/**
+ * @agent my-agent
+ * @name My Agent
+ * @description What this agent does.
+ * @interval 1h
+ */
+
+import { Poke, getToken } from "poke";
+
+const poke = new Poke({ apiKey: getToken() });
+
+// Your logic here
+const result = "Something useful";
+
+await poke.sendMessage(result);
+console.log("Done.");
+```

package/docs/agents/index.md

@@ -0,0 +1,85 @@
+# Agents
+
+Agents are scheduled scripts that **push information from your computer to Poke**. They run in the background, gather data from local sources (APIs, files, services), and send it to your Poke agent — so Poke learns about what's happening on your machine without you asking.
+
+Think of it this way: **Tools** let Poke pull from your machine (you ask, Poke acts). **Agents** let your machine push to Poke (your computer tells Poke, Poke learns and replies).
+
+::: tip Secure and deterministic
+Agents are **push-only** — they send data to Poke, but Poke cannot reach back into the agent or your computer through them. Each agent is a plain JavaScript file that you write and control. It runs the same way every time, with no AI decision-making involved. The agent doesn't "try" to access your machine — it only does exactly what the script says. This makes agents predictable, auditable, and safe.
+:::
+
+```mermaid
+flowchart LR
+    subgraph YourMac ["Your Mac"]
+        Agent["Agent script"]
+        Local["Local data source"]
+        Local -->|reads| Agent
+    end
+
+    Agent -->|sendMessage| Poke["Poke Agent"]
+    Poke -->|replies| You["You"]
+```
+
+**Example:** A Beeper agent runs every hour, fetches your unread messages, and sends a digest to Poke. Now Poke knows who messaged you — and can answer "did anyone text me?" without needing your machine in real time.
+
+## How agents work
+
+1. You place a `.js` file in `~/.config/poke-gate/agents/`
+2. The filename defines the schedule: `name.interval.js`
+3. When Poke Gate connects, it discovers all agents and starts their timers
+4. Each agent runs once immediately, then repeats on schedule
+5. Agents use the Poke SDK to send messages — pushing data to your agent
+
+## 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 |
+| `digest.24h.js` | Every 24 hours |
+
+**Intervals:** `Nm` (minutes) or `Nh` (hours). Minimum is **10 minutes**.
+
+## Frontmatter
+
+Each agent starts with a JSDoc-style frontmatter block:
+
+```javascript
+/**
+ * @agent beeper
+ * @name Beeper Message Digest
+ * @description Fetches messages from the last hour and sends a summary.
+ * @interval 1h
+ * @env BEEPER_TOKEN - Beeper Desktop local API token
+ * @author f
+ */
+```
+
+The `@name` and `@description` are shown in the macOS app's Agents editor and in the scheduler logs.
+
+## Per-agent env files
+
+Each agent can have a `.env.<name>` file in the same directory:
+
+```
+~/.config/poke-gate/agents/.env.beeper
+```
+
+```env
+BEEPER_TOKEN=your_token_here
+BEEPER_BASE_URL=http://localhost:23373
+```
+
+Variables are injected into the agent's environment automatically. The agent reads them via `process.env.BEEPER_TOKEN`.
+
+## What's next?
+
+- [Creating Agents](/agents/creating) — write your first agent from scratch
+- [Installing Agents](/agents/installing) — download community agents
+- [Beeper Example](/agents/beeper) — full walkthrough of a real agent

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