palmier 0.8.1 → 0.8.4

package/CLAUDE.md

@@ -7,3 +7,16 @@ Always read `README.md` first before starting any task.
 ## Documentation
 
 When making architectural changes, update `README.md` to reflect the new state.
+
+## Code comments
+
+Default: write no comments. Well-named identifiers already explain WHAT.
+
+Only add a comment when the WHY is non-obvious and would confuse a future reader without it — a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise someone reading the code cold.
+
+Keep comments timeless:
+- Don't reference callers, task names, PRs, issue numbers, or "used by X". That context belongs in commit messages and PR descriptions, and rots as the codebase evolves.
+- Don't narrate the current change ("added for the Y flow", "removed ...").
+- Don't restate type signatures or function names in prose.
+
+When a comment earns its place, keep it short — one or two lines is almost always enough. If a block of code needs a paragraph to explain, consider whether the code itself should be clearer.

package/README.md

@@ -29,12 +29,12 @@ It runs on your machine as a background daemon and connects to a mobile-friendly
 ### Prerequisites
 
 - **Node.js 24+**
-- **Linux with systemd** or **Windows 10/11** (macOS coming soon)
+- **Linux with systemd**, **macOS 13+**, or **Windows 10/11**
 - At least one supported agent CLI
 
 ## How It Works
 
-Palmier runs as a background daemon (systemd on Linux, Task Scheduler on Windows). It invokes your agent CLIs directly, schedules tasks via native OS timers, and exposes an API that the PWA connects to — either directly over HTTP or remotely through a relay server. Agents can interact with the user's mobile device during execution — requesting input, sending push notifications, reading SMS/notifications, managing contacts and calendar, setting alarms, and more.
+Palmier runs as a background daemon (systemd on Linux, launchd on macOS, Task Scheduler on Windows). It invokes your agent CLIs directly, schedules tasks via native OS timers, and exposes an API that the PWA connects to — either directly over HTTP or remotely through a relay server. Agents can interact with the user's mobile device during execution — requesting input, sending push notifications and full-screen alarms, reading SMS/notifications, managing contacts and calendar, and more.
 
 ### MCP Server
 
@@ -48,21 +48,21 @@ Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://loca
 | `notify` | Send a push notification to the user's device | None |
 | `request-input` | Request input from the user (blocks until response) | None |
 | `request-confirmation` | Request confirmation from the user (blocks until response) | None |
-| `device-geolocation` | Get GPS location of the user's mobile device | Location Access |
-| `read-contacts` | Read the contact list from the user's device | Contacts Access |
-| `create-contact` | Create a new contact on the user's device | Contacts Access |
-| `read-calendar` | Read calendar events (with time range filter) | Calendar Access |
-| `create-calendar-event` | Create a calendar event on the user's device | Calendar Access |
-| `send-sms-message` | Send an SMS message from the user's device | SMS Access |
-| `set-alarm` | Set an alarm on the user's device | None |
+| `device-geolocation` | Get GPS location of the user's mobile device | Get Location |
+| `read-contacts` | Read the contact list from the user's device | Manage Contacts |
+| `create-contact` | Create a new contact on the user's device | Manage Contacts |
+| `read-calendar` | Read calendar events (with time range filter) | Manage Calendar |
+| `create-calendar-event` | Create a calendar event on the user's device | Manage Calendar |
+| `send-sms-message` | Send an SMS message from the user's device | Send SMS |
+| `send-alarm` | Trigger a full-screen alarm popup with ringtone on the user's device (pierces DND) | Trigger Alarms |
 | `read-battery` | Get battery level and charging status | None |
-| `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Do Not Disturb Control |
+| `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Set Ringer Mode |
 
 **Available resources:**
 | Resource | URI | Permission | Description |
 |----------|-----|------------|-------------|
-| Device Notifications | `notifications://device` | Notification Access | Recent notifications from the user's Android device |
-| Device SMS | `sms-messages://device` | SMS Access | Recent SMS messages from the user's Android device |
+| Device Notifications | `notifications://device` | Read Notifications | Recent notifications from the user's Android device |
+| Device SMS | `sms-messages://device` | Read SMS | Recent SMS messages from the user's Android device |
 
 Resources support MCP subscriptions — clients can subscribe via `resources/subscribe` and receive real-time `notifications/resources/updated` events via the streamable HTTP transport when the resource changes.
 
@@ -148,11 +148,13 @@ The wizard:
 - Configures access modes (HTTP port, LAN access)
 - Shows a summary (including any existing scheduled tasks to recover) and asks for confirmation
 - Registers with the Palmier server, saves configuration to `~/.config/palmier/host.json`
-- Installs a background daemon (systemd user service on Linux, Task Scheduler on Windows)
+- Installs a background daemon (systemd user service on Linux, LaunchAgent on macOS, Task Scheduler on Windows)
 - Auto-enters pair mode to connect your first device
 
 The daemon automatically recovers existing tasks by reinstalling their system timers on startup.
 
+> **macOS note:** Palmier installs as a user-level LaunchAgent, so it runs without `sudo`. LaunchAgents only run while the user is logged into the GUI session — after a reboot, scheduled tasks stay dormant until you log in at least once. Enable auto-login in System Settings → Users & Groups if you need unattended operation across reboots.
+
 Agents are re-detected on every daemon start. Run `palmier restart` after installing or removing a CLI.
 
 ## CLI Reference
@@ -190,7 +192,7 @@ To fully remove Palmier from a machine:
 
 4. **(Optional) Remove configuration and task data:**
 
-   **Linux:**
+   **Linux / macOS:**
    ```bash
    rm -rf ~/.config/palmier
    rm -rf ~/palmier   # or wherever your Palmier root directory is

package/dist/agents/agent.d.ts

@@ -7,10 +7,6 @@ export interface CommandLine {
     /** Additional environment variables to set for the spawned process. */
     env?: Record<string, string>;
 }
-/**
- * Interface that each agent tool must implement.
- * Abstracts how plans are generated and tasks are executed across different AI agents.
- */
 export interface AgentTool {
     /** Return the command and args for a short, non-interactive prompt (e.g. generating a task name). */
     getPromptCommandLine(prompt: string): CommandLine;

package/dist/agents/claude.js

@@ -20,7 +20,7 @@ export class ClaudeAgent {
         }
         if (followupPrompt) {
             args.push("-c");
-        } // continue mode for followups
+        }
         return { command: "claude", args, stdin: prompt };
     }
     async init() {

package/dist/agents/codex.js

@@ -20,8 +20,8 @@ export class CodexAgent {
         }
         if (followupPrompt) {
             args.push("resume", "--last");
-        } // continue mode for followups
-        args.push("-"); // read prompt from stdin
+        }
+        args.push("-");
         return { command: "codex", args, stdin: prompt };
     }
     async init() {

package/dist/agents/cursor.js

@@ -16,7 +16,7 @@ export class Cursor {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push("-p", prompt);
         return { command: "cursor", args };
     }

package/dist/agents/deepagents.js

@@ -16,7 +16,7 @@ export class DeepAgents {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--non-interactive", prompt);
         return { command: "deepagents", args };
     }

package/dist/agents/gemini.js

@@ -21,8 +21,9 @@ export class GeminiAgent {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
-        args.push("--prompt", "-"); // read prompt from stdin to avoid command line length limits
+        }
+        // Read prompt from stdin to avoid command-line length limits.
+        args.push("--prompt", "-");
         return { command: "gemini", args, stdin: prompt };
     }
     async init() {

package/dist/agents/goose.js

@@ -13,7 +13,7 @@ export class GooseAgent {
         const args = ["run"];
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--text", prompt);
         return { command: "goose", args, ...(yolo ? { env: { GOOSE_MODE: "auto" } } : {}) };
     }

package/dist/agents/hermes.js

@@ -16,7 +16,7 @@ export class Hermes {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push("-q", prompt);
         return { command: "hermes", args };
     }

package/dist/agents/kiro.js

@@ -16,7 +16,7 @@ export class Kiro {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--no-interactive", prompt);
         return { command: "kiro-cli", args };
     }

package/dist/agents/opencode.js

@@ -16,7 +16,7 @@ export class OpenCodeAgent {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push(prompt);
         return { command: "opencode", args };
     }

package/dist/agents/qoder.js

@@ -16,7 +16,7 @@ export class Qoder {
         }
         if (followupPrompt) {
             args.push("-c");
-        } // continue mode for followups
+        }
         args.push("-p", prompt);
         return { command: "qodercli", args };
     }

package/dist/agents/shared-prompt.d.ts

@@ -1,7 +1,4 @@
 import type { ParsedTask } from "../types.js";
-/**
- * Build the full agent prompt: instructions + endpoint docs + task description.
- */
 export declare function getAgentInstructions(task: ParsedTask, skipPermissions?: boolean): string;
 export declare const TASK_SUCCESS_MARKER = "[PALMIER_TASK_SUCCESS]";
 export declare const TASK_FAILURE_MARKER = "[PALMIER_TASK_FAILURE]";

package/dist/agents/shared-prompt.js

@@ -5,9 +5,6 @@ import { loadConfig } from "../config.js";
 import { generateEndpointDocs } from "../mcp-tools.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_INSTRUCTIONS_TEMPLATE = fs.readFileSync(path.join(__dirname, "agent-instructions.md"), "utf-8");
-/**
- * Build the full agent prompt: instructions + endpoint docs + task description.
- */
 export function getAgentInstructions(task, skipPermissions) {
     const port = loadConfig().httpPort ?? 7256;
     const taskDescription = task.frontmatter.user_prompt;

package/dist/commands/info.d.ts

@@ -1,5 +1,2 @@
-/**
- * Print host connection info for setting up clients.
- */
 export declare function infoCommand(): Promise<void>;
 //# sourceMappingURL=info.d.ts.map

package/dist/commands/info.js

@@ -1,21 +1,16 @@
 import { loadConfig } from "../config.js";
 import { loadClients } from "../client-store.js";
-/**
- * Print host connection info for setting up clients.
- */
 export async function infoCommand() {
     const config = loadConfig();
     const clients = loadClients();
     console.log(`Host ID:      ${config.hostId}`);
     console.log(`Project root: ${config.projectRoot}`);
-    // Detected agents
     if (config.agents && config.agents.length > 0) {
         console.log(`Agents:       ${config.agents.map((a) => a.label).join(", ")}`);
     }
     else {
         console.log(`Agents:       (none detected — run \`palmier agents\`)`);
     }
-    // Clients
     console.log(`Clients:      ${clients.length} active`);
     if (clients.length === 0) {
         console.log("");

package/dist/commands/init.d.ts

@@ -1,5 +1,2 @@
-/**
- * Interactive wizard to provision this host.
- */
 export declare function initCommand(): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -10,9 +10,6 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const red = (s) => `\x1b[31m${s}\x1b[0m`;
-/**
- * Interactive wizard to provision this host.
- */
 export async function initCommand() {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
@@ -20,7 +17,6 @@ export async function initCommand() {
         console.log(`\n${bold("=== Palmier Host Setup ===")}\n`);
         console.log(`By continuing, you agree to the ${cyan("Terms of Service")} (https://www.palmier.me/terms)`);
         console.log(`and ${cyan("Privacy Policy")} (https://www.palmier.me/privacy).\n`);
-        // Detect agents first — abort if none found
         console.log("Detecting installed agents...");
         const agents = await detectAgents();
         if (agents.length === 0) {
@@ -31,7 +27,6 @@ export async function initCommand() {
             process.exit(1);
         }
         console.log(`  Found: ${green(agents.map((a) => a.label).join(", "))}\n`);
-        // LAN mode
         const lanAnswer = await ask("Enable LAN access (direct HTTP from local network)? (y/N): ");
         const lanEnabled = lanAnswer.trim().toLowerCase() === "y";
         let httpPort = 7256;
@@ -40,7 +35,6 @@ export async function initCommand() {
         const parsed = parseInt(portAnswer.trim(), 10);
         if (parsed > 0 && parsed < 65536)
             httpPort = parsed;
-        // Display summary and ask for confirmation before making any changes
         console.log(`\n${bold("Setup summary:")}\n`);
         console.log(`  ${dim("Task storage:")}   ${bold(process.cwd())}`);
         console.log(`                  All tasks and execution data will be stored here.\n`);
@@ -52,7 +46,6 @@ export async function initCommand() {
             console.log(`                  Accessible from other devices on your local network. Pairing required.\n`);
         }
         console.log(`  ${dim("Agents:")}         ${agents.map((a) => a.label).join(", ")}\n`);
-        // Check for existing tasks to recover
         const existingTasks = listTasks(process.cwd());
         if (existingTasks.length > 0) {
             console.log(`  ${dim("Recover tasks:")}  ${existingTasks.length} existing task(s) found:`);
@@ -67,7 +60,6 @@ export async function initCommand() {
             rl.close();
             return;
         }
-        // Register with server
         let existingHostId;
         try {
             existingHostId = loadConfig().hostId;
@@ -92,7 +84,6 @@ export async function initCommand() {
                 }
             }
         }
-        // Build and save config
         const config = {
             hostId: registerResponse.hostId,
             projectRoot: process.cwd(),
@@ -107,8 +98,8 @@ export async function initCommand() {
         saveConfig(config);
         console.log(`Config saved to ${dim("~/.config/palmier/host.json")}`);
         getPlatform().installDaemon(config);
-        // Task recovery happens in the daemon (palmier serve) on startup,
-        // since the daemon runs elevated and can create S4U scheduled tasks.
+        // Task recovery runs in the daemon (palmier serve) because that process
+        // is elevated and can create S4U scheduled tasks.
         console.log("\nStarting pairing...");
         rl.close();
         await pairCommand();

package/dist/commands/pair.d.ts

@@ -1,8 +1,5 @@
 export declare const PAIRING_EXPIRY_MS: number;
 export declare function generatePairingCode(): string;
-/**
- * Generate a pairing code and wait for a PWA client to pair.
- * Listens on NATS (server mode) and HTTP (via serve daemon) in parallel.
- */
+/** Listens on NATS (server mode) and HTTP (via serve daemon) in parallel. */
 export declare function pairCommand(): Promise<void>;
 //# sourceMappingURL=pair.d.ts.map

package/dist/commands/pair.js

@@ -1,4 +1,5 @@
 import * as http from "node:http";
+import * as os from "node:os";
 import { StringCodec } from "nats";
 import { loadConfig } from "../config.js";
 import { connectNats } from "../nats-client.js";
@@ -16,11 +17,9 @@ function buildPairResponse(config, label) {
     return {
         hostId: config.hostId,
         clientToken: client.token,
+        hostName: os.hostname(),
     };
 }
-/**
- * POST to the running serve daemon and long-poll until paired or expired.
- */
 function httpPairRegister(port, code) {
     const body = JSON.stringify({ code, expiryMs: PAIRING_EXPIRY_MS });
     return new Promise((resolve) => {
@@ -49,10 +48,7 @@ function httpPairRegister(port, code) {
         req.end(body);
     });
 }
-/**
- * Generate a pairing code and wait for a PWA client to pair.
- * Listens on NATS (server mode) and HTTP (via serve daemon) in parallel.
- */
+/** Listens on NATS (server mode) and HTTP (via serve daemon) in parallel. */
 export async function pairCommand() {
     const config = loadConfig();
     const code = generatePairingCode();
@@ -63,14 +59,12 @@ export async function pairCommand() {
         console.log("Paired successfully!");
     }
     const cleanups = [];
-    // Display pairing info
     console.log("");
     console.log("Enter this code in your Palmier app:");
     console.log("");
     console.log(`  ${code}`);
     console.log("");
     console.log("Code expires in 1 minute.");
-    // NATS pairing (server mode)
     const nc = await connectNats(config);
     const sc = StringCodec();
     const subject = `pair.${code}`;
@@ -98,13 +92,11 @@ export async function pairCommand() {
             onPaired();
         }
     })();
-    // HTTP pairing — register with serve daemon's /pair-register endpoint
     (async () => {
         const result = await httpPairRegister(httpPort, code);
         if (result)
             onPaired();
     })();
-    // Wait for pairing or timeout
     const start = Date.now();
     await new Promise((resolve) => {
         const interval = setInterval(() => {
@@ -114,7 +106,6 @@ export async function pairCommand() {
             }
         }, 500);
     });
-    // Cleanup
     for (const cleanup of cleanups) {
         await cleanup();
     }

package/dist/commands/restart.d.ts

@@ -1,5 +1,2 @@
-/**
- * Restart the palmier serve daemon.
- */
 export declare function restartCommand(): Promise<void>;
 //# sourceMappingURL=restart.d.ts.map

package/dist/commands/restart.js

@@ -1,7 +1,4 @@
 import { getPlatform } from "../platform/index.js";
-/**
- * Restart the palmier serve daemon.
- */
 export async function restartCommand() {
     const platform = getPlatform();
     await platform.restartDaemon();

package/dist/commands/run.d.ts

@@ -1,21 +1,8 @@
 import type { TaskRunningState, RequiredPermission } from "../types.js";
-/**
- * Strip [PALMIER_*] marker lines from agent output.
- */
 export declare function stripPalmierMarkers(output: string): string;
-/**
- * Execute a task by ID.
- */
 export declare function runCommand(taskId: string): Promise<void>;
 export declare function parseReportFiles(output: string): string[];
-/**
- * Extract required permissions from agent output.
- * Looks for lines matching: [PALMIER_PERMISSION] <tool> | <description>
- */
 export declare function parsePermissions(output: string): RequiredPermission[];
-/**
- * Parse the agent's output for success/failure markers.
- * Falls back to "finished" if no marker is found.
- */
+/** Falls back to "finished" if no success/failure marker is found. */
 export declare function parseTaskOutcome(output: string): TaskRunningState;
 //# sourceMappingURL=run.d.ts.map