Palmier Agent

A Node.js CLI that runs on your machine as a persistent agent. It manages tasks, communicates with the Palmier platform via NATS, and executes Claude Code autonomously.

Prerequisites

• Node.js 20+
• Claude Code CLI installed and authenticated
• Linux with systemd (the agent installs as a systemd user service)

Installation

npm install -g palmier

CLI Commands

| Command | Description | |---|---| | palmier init --token <token> | Provision the agent with a token from the dashboard | | palmier serve | Run the persistent NATS RPC handler (default command) | | palmier run <task-id> | Execute a specific task |

Setup

1. Install the agent: npm install -g palmier
2. Register on the Palmier PWA and click Add Agent.
3. Copy the provisioning token.
4. Run palmier init --token <token> in your project directory.

The init command:

• Saves agent configuration to ~/.config/palmier/agent.json
• Installs a systemd user service for the agent

Verifying the Service

After palmier init, verify the agent is running:

# Check service status
systemctl --user status palmier-agent.service

# View recent logs
journalctl --user -u palmier-agent.service -n 50 --no-pager

# Follow logs in real time
journalctl --user -u palmier-agent.service -f

You should see Active: active (running) and log output showing a NATS connection. If the service failed:

# Restart manually
systemctl --user restart palmier-agent.service

# Check config is valid
cat ~/.config/palmier/agent.json

How It Works

• The agent runs as a systemd user service, staying alive in the background.
• The persistent process (palmier serve) is a NATS RPC handler. It derives the RPC method from the NATS subject (e.g., ...rpc.task.create → task.create) and treats the message body as request parameters.
• Task IDs are generated by the agent as UUIDs.
• All RPC responses (task.list, task.create, task.update) return flat task objects — frontmatter fields at the top level, not nested under a frontmatter key.
• Tasks have no separate name field — the user_prompt is the primary identifier and display label.
• Plan generation is optional — if no plan body is present, the agent uses only user_prompt as the prompt.
• Triggers can be enabled/disabled via the triggers_enabled frontmatter field (default true). When disabled, systemd timers are removed; when re-enabled, they are reinstalled. Tasks can still be run manually regardless.
• Incoming tasks are stored as TASK.md files in a local tasks/ directory.
• Task execution spawns Claude Code as a background process with -p --dangerously-skip-permissions, running non-interactively. Task lifecycle events (start, finish, abort, fail) are tracked via a NATS JetStream KV bucket (task-event), keyed by <agent_id>.<task_id>.
• Task confirmation — tasks with requires_confirmation: true write a pending entry to the pending-confirmation KV bucket before execution. The Web Server and PWA watch this bucket to show confirmation prompts. The task waits until the user confirms or aborts via the PWA or push notification.

Project Structure

src/
  index.ts            # CLI entrypoint (commander setup)
  config.ts           # Agent configuration (read/write ~/.config/palmier)
  nats-client.ts      # NATS connection and messaging
  systemd.ts          # systemd service installation
  task.ts             # Task file management
  types.ts            # Shared type definitions
  commands/
    init.ts           # Provisioning logic
    serve.ts          # Persistent NATS RPC handler
    run.ts            # Single task execution

Removing an Agent

To fully remove an agent from a machine:

1. Delete the agent from the PWA dashboard (this removes it from the server database).

2. Stop and remove the systemd service:

   systemctl --user stop palmier-agent.service
   systemctl --user disable palmier-agent.service
   rm ~/.config/systemd/user/palmier-agent.service

3. Remove any task timers and services:

   systemctl --user stop palmier-task-*.timer palmier-task-*.service 2>/dev/null
   systemctl --user disable palmier-task-*.timer 2>/dev/null
   rm -f ~/.config/systemd/user/palmier-task-*.timer ~/.config/systemd/user/palmier-task-*.service

4. Reload systemd:

   systemctl --user daemon-reload

5. Remove the agent configuration:

   rm -rf ~/.config/palmier

6. Remove the tasks directory from your project root:

   rm -rf tasks/

7. (Optional) Disable login lingering if no other user services need it:

   loginctl disable-linger

Related

See the palmier repo for the server, API, and PWA.