v0.1.8 — run_agent tool, AI agent generation, stale connection cleanup

- New MCP tool: run_agent — trigger agents from Poke via iMessage
- agent create: sends prompt to Poke, writes code via write_file tool
- macOS app: Generate with Poke UI, direct API call instead of npx
- Stale connection cleanup via connection history tracking
- Delete agent confirmation dialog
- Docs: AI agent generation guide, CLI reference update

Made-with: Cursor

Author: f

bin/poke-gate.js

@@ -21,6 +21,11 @@ async function main() {
     }
     const { downloadAgent } = await import("../src/agents.js");
     await downloadAgent(name);
+  } else if (args[0] === "agent" && args[1] === "create") {
+    const promptIdx = args.indexOf("--prompt");
+    const prompt = promptIdx !== -1 ? args.slice(promptIdx + 1).join(" ") : args.slice(2).join(" ") || null;
+    const { createAgent } = await import("../src/agent-create.js");
+    await createAgent(prompt);
   } else {
     await import("../src/app.js");
   }

clients/Poke macOS Gate/Poke macOS Gate/AgentsView.swift

@@ -247,6 +247,8 @@ class AgentsViewModel: ObservableObject {
 
 struct AgentsView: View {
     @StateObject private var viewModel = AgentsViewModel()
+    @State private var showingGenerate = false
+    @State private var agentToDelete: AgentFile? = nil
 
     var body: some View {
         NavigationSplitView {
@@ -282,20 +284,30 @@ struct AgentsView: View {
                 .tag(agent)
                 .contextMenu {
                     Button("Delete", role: .destructive) {
-                        viewModel.deleteAgent(agent)
+                        agentToDelete = agent
                     }
                 }
             }
             .listStyle(.sidebar)
             .navigationSplitViewColumnWidth(min: 180, ideal: 220)
             .safeAreaInset(edge: .bottom) {
-                Button {
-                    viewModel.addAgent()
-                } label: {
-                    Label("New Agent", systemImage: "plus")
-                        .font(.caption)
+                HStack(spacing: 12) {
+                    Button {
+                        viewModel.addAgent()
+                    } label: {
+                        Label("New", systemImage: "plus")
+                            .font(.caption)
+                    }
+                    .buttonStyle(.plain)
+
+                    Button {
+                        showingGenerate = true
+                    } label: {
+                        Label("Generate with Poke", systemImage: "sparkles")
+                            .font(.caption)
+                    }
+                    .buttonStyle(.plain)
                 }
-                .buttonStyle(.plain)
                 .padding(8)
                 .frame(maxWidth: .infinity, alignment: .leading)
             }
@@ -315,6 +327,153 @@ struct AgentsView: View {
         .onDisappear {
             viewModel.stopWatching()
         }
+        .sheet(isPresented: $showingGenerate) {
+            GenerateAgentView(viewModel: viewModel, isPresented: $showingGenerate)
+        }
+        .alert("Delete Agent", isPresented: Binding(
+            get: { agentToDelete != nil },
+            set: { if !$0 { agentToDelete = nil } }
+        )) {
+            Button("Cancel", role: .cancel) { agentToDelete = nil }
+            Button("Delete", role: .destructive) {
+                if let agent = agentToDelete {
+                    viewModel.deleteAgent(agent)
+                    agentToDelete = nil
+                }
+            }
+        } message: {
+            if let agent = agentToDelete {
+                Text("Are you sure you want to delete \"\(agent.name)\"? This will remove the script\(agent.hasEnv ? " and its .env file" : "").")
+            }
+        }
+    }
+}
+
+struct GenerateAgentView: View {
+    @ObservedObject var viewModel: AgentsViewModel
+    @Binding var isPresented: Bool
+    @State private var prompt: String = ""
+    @State private var isSending: Bool = false
+    @State private var sent: Bool = false
+
+    var body: some View {
+        VStack(spacing: 16) {
+            if sent {
+                Spacer()
+
+                Image(systemName: "checkmark.circle.fill")
+                    .font(.system(size: 40))
+                    .foregroundStyle(.green)
+
+                Text("Request sent to Poke!")
+                    .font(.headline)
+
+                Text("Poke is generating your agent and will save it directly to your Mac. You'll see it appear in the sidebar when it's ready.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+
+                Text("Keep Poke Gate running while Poke works.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fontWeight(.medium)
+
+                Spacer()
+
+                Button("Done") {
+                    isPresented = false
+                }
+                .keyboardShortcut(.defaultAction)
+            } else {
+                HStack {
+                    Image(systemName: "sparkles")
+                        .foregroundStyle(.purple)
+                    Text("Generate Agent with Poke")
+                        .font(.headline)
+                }
+
+                Text("Describe what you want the agent to do. Poke will generate the code and save it to your agents folder.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+
+                TextEditor(text: $prompt)
+                    .font(.system(.body, design: .default))
+                    .padding(8)
+                    .frame(minHeight: 100)
+                    .scrollContentBackground(.hidden)
+                    .background(.quaternary.opacity(0.3))
+                    .cornerRadius(6)
+                    .overlay(
+                        RoundedRectangle(cornerRadius: 6)
+                            .stroke(.quaternary)
+                    )
+
+                HStack {
+                    Button("Cancel") {
+                        isPresented = false
+                    }
+                    .keyboardShortcut(.cancelAction)
+
+                    Spacer()
+
+                    Button("Generate") {
+                        sendPrompt()
+                    }
+                    .keyboardShortcut(.defaultAction)
+                    .disabled(prompt.isEmpty || isSending)
+                }
+            }
+        }
+        .padding(20)
+        .frame(width: 420, height: sent ? 250 : nil)
+    }
+
+    private func sendPrompt() {
+        isSending = true
+
+        Task {
+            do {
+                guard let token = GateService().loadPokeLoginToken() else {
+                    isSending = false
+                    return
+                }
+
+                let message = """
+                Generate a Poke Gate agent based on my description below.
+
+                Write the COMPLETE JavaScript code using the write_file tool to save it directly to ~/.config/poke-gate/agents/<name>.<interval>.js
+
+                RULES:
+                - Valid ES module with imports.
+                - Start with JSDoc frontmatter: @agent, @name, @description, @interval, @author.
+                - Use: import { Poke, getToken } from "poke";
+                - Keep under 100 lines. Intervals: 10m, 30m, 1h, 2h, 6h, 12h, 24h.
+                - Handle errors with try/catch.
+                - Use state files to avoid duplicate sends.
+
+                IMPORTANT: Use the write_file tool to save the agent code now.
+                IMPORTANT: When done, tell me the file name.
+
+                My request: \(prompt)
+                """
+
+                let url = URL(string: "https://poke.com/api/v1/inbound/api-message")!
+                var request = URLRequest(url: url)
+                request.httpMethod = "POST"
+                request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+                request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+                request.httpBody = try JSONSerialization.data(withJSONObject: ["message": message])
+
+                let (_, response) = try await URLSession.shared.data(for: request)
+                let httpResp = response as? HTTPURLResponse
+
+                isSending = false
+                sent = httpResp?.statusCode == 200
+            } catch {
+                isSending = false
+            }
+        }
     }
 }
 

clients/Poke macOS Gate/Poke macOS Gate/GateService.swift

@@ -225,7 +225,7 @@ class GateService: ObservableObject {
         return paths.joined(separator: ":")
     }
 
-    private func findNpx() -> String {
+    func findNpx() -> String {
         let path = shellPath()
         for dir in path.split(separator: ":") {
             let npxPath = "\(dir)/npx"

docs/agents/creating.md

@@ -1,6 +1,34 @@
 # Creating Agents
 
-This guide walks you through creating an agent from scratch.
+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:
+
+```bash
+npx poke-gate agent create --prompt "monitor disk space and alert when above 85%"
+```
+
+Or interactively:
+
+```bash
+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
 

docs/cli.md

@@ -41,6 +41,30 @@ npx poke-gate run-agent beeper
 
 Finds `~/.config/poke-gate/agents/beeper.*.js` and runs it with the env from `.env.beeper`.
 
+## Generate an agent with AI
+
+```bash
+npx poke-gate agent create --prompt "<description>"
+```
+
+Sends your description to Poke with detailed instructions and examples. Poke generates the agent code and saves it directly to `~/.config/poke-gate/agents/` using the `write_file` tool.
+
+**Requires poke-gate to be running** (so Poke can use the `write_file` tool through the tunnel).
+
+**Interactive mode:**
+
+```bash
+npx poke-gate agent create
+```
+
+**Examples:**
+
+```bash
+npx poke-gate agent create --prompt "alert me when disk space is above 85%"
+npx poke-gate agent create --prompt "send me a daily git commit summary across all repos"
+npx poke-gate agent create --prompt "track Spotify listening and log my music taste"
+```
+
 ## Install an agent
 
 ```bash

package.json

@@ -1,6 +1,6 @@
 {
   "name": "poke-gate",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Expose your machine to your Poke AI assistant via MCP tunnel",
   "type": "module",
   "bin": {

src/agent-create.js

@@ -0,0 +1,100 @@
+import { Poke, getToken, isLoggedIn, login } from "poke";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+const CONFIG_DIR = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+const AGENTS_DIR = join(CONFIG_DIR, "poke-gate", "agents");
+
+const SYSTEM_PROMPT = `Generate a Poke Gate agent based on my description below.
+
+Write the COMPLETE JavaScript code using the write_file tool to save it directly to the agents folder.
+
+RULES:
+- Save to: ~/.config/poke-gate/agents/<name>.<interval>.js
+- Valid ES module with imports.
+- Start with JSDoc frontmatter: @agent, @name, @description, @interval, @author.
+- Use: import { Poke, getToken } from "poke";
+- Auth: const token = getToken(); const poke = new Poke({ apiKey: token });
+- Send results: await poke.sendMessage("...");
+- Shell commands: import { execSync } from "node:child_process";
+- State files: ~/.config/poke-gate/agents/.<agent-name>-state.json
+- Only send to Poke when something changed (use state files).
+- Handle errors with try/catch. Log with console.log().
+- Keep under 100 lines. Intervals: 10m, 30m, 1h, 2h, 6h, 12h, 24h.
+- If secrets needed, read from process.env (from .env.<name> file).
+
+EXAMPLE agent (battery monitor):
+/**
+ * @agent battery
+ * @name Battery Guardian
+ * @description Alerts via Poke when battery drops below 20%.
+ * @interval 30m
+ */
+import { Poke, getToken } from "poke";
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const token = getToken();
+if (!token) { console.error("Not signed in."); process.exit(1); }
+const STATE = join(homedir(), ".config", "poke-gate", "agents", ".battery-state.json");
+function load() { try { return JSON.parse(readFileSync(STATE, "utf-8")); } catch { return {}; } }
+function save(s) { writeFileSync(STATE, JSON.stringify(s)); }
+const out = execSync("pmset -g batt", { encoding: "utf-8" });
+const level = parseInt(out.match(/(\\d+)%/)?.[1] || "100");
+const charging = out.includes("AC Power");
+const state = load();
+if (level <= 20 && !charging && !state.alerted) {
+  await new Poke({ apiKey: token }).sendMessage("Battery: " + level + "%, not charging.");
+  save({ alerted: true });
+} else if (level > 20 || charging) { if (state.alerted) save({ alerted: false }); }
+
+Now use the write_file tool via Poke Gate to save the generated agent code. After writing, tell me the file name and what the agent does.
+If you cannot reach out the tunnel, you can send the code via iMessage, Telegram, or SMS.
+
+IMPORTANT: Now write me immediately, before starting that you will write the agent code now and save to your file.
+IMPORTANT: If you have questions to clarify, ask me first.
+IMPORTANT: When you finish writing the agent code, tell user that you created the agent and saved to the file.
+
+My request: `;
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function createAgent(promptArg) {
+  if (!isLoggedIn()) {
+    console.log("  Signing in to Poke...");
+    await login();
+  }
+
+  const token = getToken();
+  if (!token) {
+    console.error("  Not signed in. Run: npx poke login");
+    process.exit(1);
+  }
+
+  const prompt = promptArg || await ask("\n  Describe the agent you want to create:\n  > ");
+  if (!prompt) {
+    console.error("  No description provided.");
+    process.exit(1);
+  }
+
+  console.log("\n  Sending request to Poke...");
+  console.log("  Poke will generate the code and save it using the write_file tool.\n");
+
+  const poke = new Poke({ apiKey: token });
+  await poke.sendMessage(SYSTEM_PROMPT + prompt);
+
+  console.log("  Request sent! Poke will write the agent file to:");
+  console.log(`  ${AGENTS_DIR}/<name>.<interval>.js\n`);
+  console.log("  Watch for Poke's confirmation in your chat.");
+  console.log("  Once created, test it: npx poke-gate run-agent <name>\n");
+}