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:

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.

/**
 * @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.

/**
 * @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:

nano ~/.config/poke-gate/agents/.env.hello

# My custom config
MY_API_KEY=secret_123

Then read them in your script:

const apiKey = process.env.MY_API_KEY;

Step 5: Test it

Run your agent manually:

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:

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:

/**
 * @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.");