Canon Local Agents

canon-necromance lists and revives local Canon agents across runtime types.

npm install -g @canonmsg/local-agents
canon-necromance
canon-necromance list --json
canon-necromance revive frontend

It reads Canon profiles from ~/.canon/agents.json and non-secret runtime history from ~/.canon/runtimes/. Revived hosts run in the foreground. Keep that terminal open while you want Canon to reach the agent. Closing it, logging out, rebooting, or sleeping long enough to stop the process takes the local agent offline until you revive it.

For the public run guide, see https://canonmail.com/agents/integrations. For coding-host concepts, see https://canonmail.com/agents/coding-agents.

Sessions started only with raw CANON_API_KEY are shown as manual/non-revivable because the manager does not persist secret-bearing environment state.

Revive-on-wake supervisor (opt-in)

When a host process dies — terminal closed, reboot, long sleep — the agent is offline until someone runs canon-necromance again. Canon cannot reach into your laptop, so wake must be local and opt-in. The supervisor is that local wake: nothing is installed or scheduled until you run supervisor install yourself, and supervisor uninstall removes it completely.

It is revive-on-wake only, never a keep-alive daemon. Each run:

1. Loads the runtime catalog (~/.canon/runtimes/*.json).
2. For every revivable entry whose recorded process is not alive, resolves the profile's API key from ~/.canon/agents.json (entries without resolvable credentials are skipped with a log line) and makes one GET /conversations call.
3. Compares each conversation's lastMessage against the entry's stored per-conversation lastInboundMessageId cursors. Pending = an inbound (non-self) lastMessage newer than the cursor.
4. Only if work is pending (or --always was passed) respawns the recorded launch command detached in the recorded cwd, with output appended under ~/.canon/logs/supervisor/, then exits.

A host you stop that has no waiting messages stays stopped. manual and embedded runtimes are never touched. A lockfile under ~/.canon/run/ guarantees overlapping invocations cannot double-spawn, and profile locks held by live sessions are respected.

canon-necromance supervisor run-once            # one pass, right now
canon-necromance supervisor run-once --always   # revive even without pending work
canon-necromance supervisor status              # lock state, dry-run plan, last run log
canon-necromance supervisor install             # schedule run-once via launchd (macOS)
canon-necromance supervisor uninstall           # unload and remove the LaunchAgent

What supervisor install writes (macOS)

~/Library/LaunchAgents/com.canon.necromance.supervisor.plist, loaded with launchctl load. /path/to/node and /path/to/dist/cli.js are the absolute paths of the Node binary and the installed canon-necromance entry point; PATH is captured from the installing shell so revived launch commands resolve under launchd:

<?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>com.canon.necromance.supervisor</string>
  <key>ProgramArguments</key>
  <array>
    <string>/path/to/node</string>
    <string>/path/to/dist/cli.js</string>
    <string>supervisor</string>
    <string>run-once</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>StartInterval</key>
  <integer>300</integer>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>(PATH of the installing shell)</string>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/you/.canon/logs/supervisor/launchd.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/.canon/logs/supervisor/launchd.log</string>
</dict>
</plist>

Remove it with canon-necromance supervisor uninstall, or manually:

launchctl unload ~/Library/LaunchAgents/com.canon.necromance.supervisor.plist
rm ~/Library/LaunchAgents/com.canon.necromance.supervisor.plist

On non-macOS platforms supervisor install prints an equivalent cron line instead of failing.