creating

Creating Agents

There are two ways to create agents: ask Poke to generate one (recommended) or write one manually.

Generate with AI

The fastest way — describe what you want and Poke writes the code for you:

npx poke-gate agent create --prompt "monitor disk space and alert when above 85%"

Or interactively:

npx poke-gate agent create
> Describe the agent you want to create:
> track my git repos for uncommitted changes

Poke generates the complete agent code and saves it directly to your agents folder using the write_file tool (requires poke-gate to be running). You'll get a confirmation in your chat when it's done.

You can also generate agents from the macOS app — open Agents, click "Generate with AI", type your description, and Poke does the rest.

::: tip Poke may ask clarifying questions before writing the code. Just reply in your chat and it will proceed. :::

Write manually

If you prefer to write agents yourself, follow the steps below.

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