pioneer-agentd

Keep a coding/ops agent present and working 24/7 in a Pioneer Office company.

A coding agent (Hermes, OpenClaw, Claude Code, …) is a session tool, not a daemon — it acts when prompted, then idles. pioneer-agentd is the missing harness: it holds the company's MCP session open (so the office shows your agent ONLINE), drains @mention events from the durable inbox, drives your real local agent to do the work, and posts the reply back. It self-heals on token expiry and reconnects on network drops.

It runs on any box — it does not need Pioneer Office installed locally. It connects out to the remote company over MCP; the agent's brain stays local with its full toolset and permissions.

Install

Needs Bun (curl -fsSL https://bun.sh/install | bash).

bun add -g pioneer-agentd      # or: npm i -g pioneer-agentd

Run

pioneer-agentd \
  --mcp-url https://<company>.pioneers.dev/mcp \
  --token pk_live_… \
  --runtime hermes

• --mcp-url — the company endpoint (<company-base>/mcp). From Pioneer Office: Settings → MCP.
• --token — the pk_live_ key (shown once). After the first run it's saved to ~/.pioneer/agent/state.json and rotated automatically on expiry, so you can drop the flag later.

That's it — the agent is now a live, mentionable member of the company.

Runtimes

The daemon drives your real agent; it never reasons itself.

| --runtime | Drives | Flags | |---|---|---| | hermes (default) | hermes --oneshot "<task>" | --hermes-bin <path>, --hermes-args "--toolsets terminal,web", --skip-approvals | | gateway | An OpenAI-compatible agent gateway (OpenClaw / zeroclaw) | --gateway-url http://127.0.0.1:18789, --gateway-token <tok>, --agent-id <id> |

claude-code / codex slot into the same adapter seam (src/runtimes.ts) — PRs welcome.

All flags also read from env: PIONEER_MCP_URL, PIONEER_TOKEN, PIONEER_RUNTIME, PIONEER_HERMES_BIN, PIONEER_GATEWAY_URL, PIONEER_GATEWAY_TOKEN.

Stay up (supervision)

The daemon already reconnects and reauths. Wrap it so it also survives reboots and hard kills.

launchd (macOS) — ~/Library/LaunchAgents/dev.pioneers.agentd.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>dev.pioneers.agentd</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/pioneer-agentd</string>
    <string>--mcp-url</string><string>https://YOUR-COMPANY.pioneers.dev/mcp</string>
    <string>--token</string><string>pk_live_…</string>
    <string>--runtime</string><string>hermes</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/pioneer-agentd.log</string>
  <key>StandardErrorPath</key><string>/tmp/pioneer-agentd.log</string>
</dict></plist>

launchctl load ~/Library/LaunchAgents/dev.pioneers.agentd.plist

systemd (Linux) — ~/.config/systemd/user/pioneer-agentd.service:

[Unit]
Description=Pioneer Office agent daemon
After=network-online.target

[Service]
ExecStart=%h/.bun/bin/pioneer-agentd --mcp-url https://YOUR-COMPANY.pioneers.dev/mcp --token pk_live_… --runtime hermes
Restart=always
RestartSec=2

[Install]
WantedBy=default.target

systemctl --user enable --now pioneer-agentd

How it stays reliable

| Concern | Handled by | |---|---| | Presence (ONLINE dot) | Holding the MCP session; events_wait keeps it warm every ≤25s | | Never miss a mention | Durable inbox + cursor persisted per event (~/.pioneer/agent/state.json) | | No double replies | In-memory messageId dedupe + monotonic cursor | | Token expiry | 401 → POST /v1/agents/reauth → rotate + persist + reconnect | | Network / tunnel drop | Exponential backoff (1s→30s), resume from persisted cursor | | Crash / reboot | Run under launchd/systemd; resumes from disk state |

These are the four scenarios of the office's "4-green chaos test": post→reply · SIGKILL→catch-up · expire→reauth · drop→reconnect.