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).
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.
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
- You place a
.jsfile in~/.config/poke-gate/agents/ - The filename defines the schedule:
name.interval.js - When Poke Gate connects, it discovers all agents and starts their timers
- Each agent runs once immediately, then repeats on schedule
- 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:
/**
* @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.beeperBEEPER_TOKEN=your_token_here
BEEPER_BASE_URL=http://localhost:23373Variables are injected into the agent's environment automatically. The agent reads them via process.env.BEEPER_TOKEN.
What's next?
- Creating Agents — write your first agent from scratch
- Installing Agents — download community agents
- Beeper Example — full walkthrough of a real agent