@whalent/agent

Unified CLI agent for Whalent Memory.

Protocol reference:

• Agent Communication Protocol v3

Install

npm install -g @whalent/agent

Requires Node.js 20 or newer:

npm install -g @whalent/agent --prefer-online --registry=https://registry.npmjs.org

Node.js 20 is still the safest choice on older Linux hosts. Newer Node.js releases can force native node-pty fallback builds that need newer C++ compilers when prebuilt binaries are unavailable.

Self-updates stay in the npm prefix that owns the running whalent command, verify that prefix before restarting, and explicitly allow only the reviewed node-pty and ssh2 lifecycle scripts required by the runtime. The Whalent packages themselves rely on the engines declaration and do not run install hooks.

The HTTP, HTTPS, and SOCKS proxy paths are regression-tested on Node.js 20 and Node.js 26. Whalent keeps its fetch implementation and custom dispatchers on the same bundled Undici version so Node runtime upgrades do not break proxies.

The official npm package @moonshot-ai/kimi-code requires Node.js 22.19.0 or newer, so the daemon checks that requirement before npm install/upgrade. An already-installed native Kimi executable can run under a daemon hosted by Node.js 20 and is not blocked by that package-install requirement. Kimi uses the official ACP transport, supports native kimi login, managed kimi-code/k3 and kimi-code/kimi-for-coding* aliases, direct API-key kimi-k3, resume, approvals/questions, thinking/tool/plan streaming, and local history import.

Codex SQLite history reads require the Whalent sqlite helper. The helper is a small Go binary cached under ~/.whalent-agent/helpers/sqlite; if it is missing, cannot run, or is older than the required protocol, Codex history import is treated as unavailable instead of falling back to native npm sqlite bindings or history.jsonl. Set WHALENT_SQLITE_HELPER_BASE_URL to a release/CDN directory containing sqlite-helper-0.1.5-manifest.json, or set WHALENT_SQLITE_HELPER_MANIFEST_URL directly.

By default the daemon checks Platform's release API at startup and every five minutes for newer sqlite-helper, terminal-helper, and enabled desktop tray-helper releases, then downloads and activates the returned manifests. Helper releases are independent from daemon/npm releases. A guacd installation that already uses Whalent's managed component is updated through the same flow; system-installed or missing guacd remains an explicit user choice.

Start Daemon

whalent --token <YOUR_TOKEN>

The daemon connects to the Whalent Memory platform, fetches agent configurations, and auto-starts workers marked with auto_restart. It also accepts remote commands (upgrade, restart) via the gateway.

On Windows, macOS, and graphical Linux sessions, daemon mode installs and starts the native tray-helper automatically. Its menu shows the current Whalent login, Gateway/worker status, opens Whalent Memory or today's daemon log, checks and installs the latest Platform-approved Agent release, and can restart or stop the daemon. Double-clicking the icon where the desktop supports it, or choosing Status & diagnostics, opens a loopback-only page where the user can collect, redact, gzip, and upload the three most recent rotating logs. The Platform keeps one compressed report per account/machine and never extracts it. Headless and SSH sessions skip the tray without affecting daemon work.

To specify a custom gateway:

whalent --token <YOUR_TOKEN> --gateway wss://your-server/gw/sdk/ws

MCP Gateway Routing

When starting the legacy whalent mcp subcommand directly, pass the gateway routing instance with --gateway-instance-id or WHALENT_GATEWAY_INSTANCE_ID. The older --app-id and WHALENT_APP_ID forms remain accepted as deprecated input aliases for existing integrations.

For Codex workers, every streamable HTTP MCP server rendered by Whalent Agent receives a dedicated versioned header:

User-Agent: whalent-agent-mcp/<agent-version>

This identity is separate from Codex's own HTTP client defaults so an MCP edge can apply an explicit allow rule and correlate startup failures to the installed Whalent Agent version. Stdio MCP servers are unchanged.

License

Copyright © 2025 Whalent. All rights reserved.