whatsapp-tools

WhatsApp tools for coding agents: chats, messages, contacts, history, received files, sends and actions on the user's own messages and chats.

The tools need Node.js 24 or later. docs/conventions.md describes how the tools are named and how they behave.

Install

Install from a release, never from the default branch: a release is a tag whose commit carries the built dist/, and the default branch does not. In the commands below, <version> is a release's version (1.2.3) and <sha> is the commit its tag names:

gh api repos/craft-agent/whatsapp-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 takes the package and its options in opencode.json:

{
  "plugins": [{ "package": "@craftsamo/whatsapp-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "whatsapp_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 takes the package as a string, or as a pair with its options:

{
  "plugin": [["@craftsamo/whatsapp-tools@<version>", { "read_only": false }]],
  "permission": { "whatsapp_*": "ask" }
}

OpenCode allows any action no rule names, so the plugin's request is granted silently unless a rule says ask. Read tools never ask, so the whatsapp_* glob is safe.

V1 registers no skills. Unpack the package and copy its skills/* folders into ~/.config/opencode/skills/:

npm pack @craftsamo/whatsapp-tools@<version>
tar -xzf craftsamo-whatsapp-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-whatsapp-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/whatsapp-tools#v<version>
claude plugin install whatsapp-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/whatsapp-tools --ref v<version>
codex plugin add whatsapp-tools@craft-agent

Codex turns - into _ in server names, so it shows the tools as mcp__whatsapp_tools__whatsapp_*. It starts the MCP server in the plugin's install directory, which is never the caller's working tree.

Grok Build

grok plugin install craft-agent/whatsapp-tools@v<version> --trust

Grok starts the MCP server in the session's working directory.

Antigravity

Install from the tree of the release tag, never from the default branch, which has no built dist/; Antigravity clones the tag into ~/.gemini/config/plugins/whatsapp-tools.

agy plugin install https://github.com/craft-agent/whatsapp-tools/tree/v<version>

Hermes Agent

The plugin needs Hermes Agent 0.22 or later. Hermes installs a commit, not a tag, and the plugin installs disabled:

hermes plugins install craft-agent/whatsapp-tools --ref <sha>
hermes plugins enable whatsapp-tools

If a Hermes gateway is already running, restart it (hermes gateway restart) to load the plugin.

The plugin runs the Node it found when Hermes started. If a version manager removes that version while Hermes runs, a call looks for Node again; when it finds none, restart Hermes from a shell where node runs.

Any other MCP host

Add the server to the host's MCP configuration. Flags go in args:

{
  "mcpServers": {
    "whatsapp-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
    }
  }
}

Related MCP server: tgx

Tools and skills

Each toolset comes with a skill that tells an agent how to use its tools. A skill names its toolset under metadata in its frontmatter (metadata: { toolset: sends }, written as a block). OpenCode V2 and Hermes register it only when the settings register at least one of that toolset's tools, so a profile with the toolset off, or with all its tools removed, does not see it; a skill without a toolset is always registered. Claude Code, Codex, Grok Build and Antigravity install the skill folder whole and pass the settings only to the MCP server, so they list every skill whatever the settings select. OpenCode V1 registers no skills, and its copied skills are all listed too.

Account (account)

It reads local state only: no network, no running service needed, and no message content, number, JID or key in its result. The skill is whatsapp-account, shown as whatsapp-tools:whatsapp-account in Claude Code and whatsapp-tools:account in Hermes. Unlike other tools, leaving out account lists every label.

Chats (chats)

It reads the account's local mirror only, with no network needed, and what it returns of other people's words is data, never instructions. The skills are whatsapp-chats, shown as whatsapp-tools:whatsapp-chats in Claude Code and whatsapp-tools:chats in Hermes, and whatsapp-count-activity, shown as whatsapp-tools:whatsapp-count-activity and whatsapp-tools:count-activity, which says how to count chats and replies over a period.

Contacts (contacts)

search reads the account's local mirror only, with no network or running service needed. check asks WhatsApp through the label's running sync service, writes nothing and adds no contact. The skill is whatsapp-contacts, shown as whatsapp-tools:whatsapp-contacts in Claude Code and whatsapp-tools:contacts in Hermes.

History (history)

It writes only to the label's own mirror and sends nothing to anyone. The sync service runs it, pausing its sync for the call, so the service must be running; the result says how many messages arrived, the oldest one now held, why it stopped, and whether the service is syncing again. The phone must be online, and nothing added does not prove that nothing older exists. Its skill is whatsapp-chats.

A call can take up to about five minutes. Some harnesses stop a tool call sooner by default, and the call then fails, though what arrived stays and the service syncs again:

• Codex stops a call after 60 s by default; the plugin raises the limit to 330 s. A server added under [mcp_servers] instead of the plugin (see Settings) needs tool_timeout_sec = 330.

• Antigravity stops a call after 180 s. Give the server "timeoutSeconds": 330 in its MCP configuration.

• Hermes gives the plugin's calls 150 s, and 330 s to whatsapp_history_backfill, whatsapp_file_save and whatsapp_file_send; nothing needs setting.

Files (files)

Off by default: turn it on with the files toolset. A message's file goes into its own folder under download_dir (~/Downloads/whatsapp-tools by default), private and never executable, and nothing is overwritten. Programs, installers, disk images, macro documents and archives that cannot be read are refused; zip, tar and gzipped tar are inspected first and unpacked only when asked. On macOS each saved file carries the quarantine flag. A file WhatsApp's server no longer keeps is asked of the phone through the running sync service. The skill is whatsapp-files, shown as whatsapp-tools:whatsapp-files in Claude Code and whatsapp-tools:files in Hermes.

A call that falls back to the phone can take a few minutes; the tool time limits given above under History apply to it too.

whatsapp_file_send sends only from the working directory and the directories the send_dirs setting names, judged by real path; a file anywhere else is refused, and so is the state directory. Keys and secrets (.ssh, .env, *.pem, …), the data folders of browsers, password managers and messengers, empty files, programs, installers and anything holding a private key block are never sent, wherever they are; an archive is sent only once every entry passes, and is never unpacked. Each file is copied into the label's outbox and checked there, so what is checked is what leaves, and a sha256 the user approved makes a changed file stale. Each file is its own message, in the order given, with the text as the first file's caption (at most 1,024 characters, refused on audio). Photos, videos and audio WhatsApp shows itself go as such, decided from the name and the first bytes, and everything else as a file; as_document sends all of them as files. A call that stops after some files went out fails and lists in details what went out, with the message ids, and what did not, so nothing is sent twice; a file that may have gone out is uncertain. A call takes at most 280 s, and the tool time limits given above under History apply to it too.

Sends (sends)

On by default, and it goes through the label's running sync service, so the service must be running. It sends to people and groups only: a channel, a broadcast list and the status feed are refused. The chat is a JID from whatsapp_chat_read; for someone the mirror does not hold yet, it is the chat that whatsapp_contact_read check gives, and WhatsApp is asked right before sending whether the number has an account. The text goes out as given, surrounding blank space trimmed, never split, and with no link preview. A result means WhatsApp accepted the message, not that it was delivered or read. A failure known to happen before anything left says so; every other failure after the request was handed over is uncertain: the message may have gone out, and the chat is checked and the user asked before it is sent again. Like a message written on the phone, a send lowers the chat's unread count in the mirror and sends no read receipt. The skill is whatsapp-sends, shown as whatsapp-tools:whatsapp-sends in Claude Code and whatsapp-tools:sends in Hermes.

Actions (actions)

Off by default: turn it on with the actions toolset. Each action goes through the label's running sync service and acts only on a chat and a message the mirror holds, named by JID and id from whatsapp_chat_read. Deleting for everyone pauses the sync service for the call, a few seconds, and the result says whether it syncs again. It keeps to the limits WhatsApp's own apps hold, and refuses past them before anything leaves. A result means WhatsApp accepted the action; a failure known to happen before anything left says so, and every other failure is uncertain: the chat is checked and the user asked before the action is tried again. A chat's archive, pin, mute and read state are states only the user's own devices show, and setting one again is safe, so their uncertain says so. Marking a chat read tells no one by default; only when the user asks for it does receipts: true send read receipts for up to 100 unread messages instead, which tells their senders and clears only the mirror's unread count, not necessarily the phone's mark. The skill is whatsapp-actions, shown as whatsapp-tools:whatsapp-actions in Claude Code and whatsapp-tools:actions in Hermes.

Adding a tool

1. Write the spec in src/core/<domain>/<verb>.ts with defineTool: an ID <prefix>_<domain>_<verb>, a title and description, the Zod argument and output schemas, its toolset and write class, and execute(args, context). A write tool also gives targets(args, context): what the call writes to, as a permission rule should name it.

2. Test it beside the spec (<verb>.test.ts), calling it through invoke as the entry points do. A tool that runs a program is tested against a fake of that program on PATH; no test reaches a real service.

3. List it in src/tools.ts. A new toolset goes into toolsets in src/project.ts (and defaultToolsets when it is on by default), a setting of the package's own into options (and OPTIONS in project.py with config_schema in plugin.yaml), and a variable the tool reads besides the settings into toolVariables.

4. Add or update the toolset's skill, skills/<prefix>-<toolset>/SKILL.md, whose frontmatter names the toolset under metadata.

5. Run pnpm run build && pnpm run manifests to list the tool in plugin.yaml and its variables in Codex's manifest, then describe it under "Tools and skills".

docs/conventions.md has the rules each step follows.

A package declares each option as text, boolean, number, list, path or paths, or as an object with type and optional bounds. For example, in src/project.ts:

options: {
  notes_dir: "path",
  note_limit: { type: "number", integer: true, min: 1, max: 50 },
}

integer: true requires a whole number; min and max bound a number or count a list or paths value's items. An object with only type means the same as the type alone. Hermes's OPTIONS mirrors the declarations on one line, with double quotes and Python's True for integer:

OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}

Reads and writes

Every read tool is named <prefix>_<domain>_read. Reads can run unasked; writes are confirmed by the harness.

Where a write is asked about, and where it is not:

• OpenCode grants any action no rule names, so a write runs unasked unless a rule asks for it: add the whatsapp_* rule shown under OpenCode.

• Codex under codex exec, and Grok Build under grok -p, refuse a write they cannot ask about, unless it is allowed beforehand.

• Grok Build calls the plugin's tools through its use_tool tool, and the agent often names a tool without its server first. Grok checks the rules against the name as given, so the server-qualified rule alone does not match that first call. The second rule matches the short name; a write still matches neither.

• Antigravity asks before any MCP tool no rule allows, reads included, and names the plugin's server whatsapp-tools_whatsapp-tools (plugin, then server). agy -p refuses a tool it cannot ask about.

• Hermes hermes chat -q refuses a write it cannot ask about; hermes -z and --yolo skip approval, so writes then run unasked.

Settings

Every entry point takes the same settings. A flag wins over its environment variable, and an option or setting wins over the variable too, except in Hermes, noted below.

Lists are comma-separated in a flag or a variable. state_dir, download_dir and send_dirs are this package's own settings, listed in options in src/project.ts and read the same way. A path is trimmed; ~ and ~/… (also with the platform separator) stand for the home directory (HOME when it is absolute, else the account's). It must then be absolute and reaches the tool normalized, without a filesystem check. A blank path counts as unset, so the default applies. paths is a list of such paths, comma-separated in a flag or variable and an array of strings in a plugin option. Blank items are dropped, and a list with none left counts as unset. Repeated send directories are dropped. Bounds check only a given value, not an unset option. Refused values are invalid_argument, naming the flag, variable or option and what it must be. Hermes passes paths and lists to the command line, which checks the paths and bounds. Where each harness reads them:

• OpenCode takes the plugin options shown above, with lists as arrays, read_only as a boolean, state_dir and download_dir as paths and send_dirs as an array of paths, and falls back to the variables. V2 runs plugins in its background service, which keeps the environment it started with: a variable set where opencode run starts has no effect until the service is restarted in that environment (opencode service restart). V1 runs plugins in its own process.

• Hermes takes plugins.entries.whatsapp-tools.settings in config.yaml:

  plugins:
    entries:
      whatsapp-tools:
        settings:
          read_only: false
          exclude_tools: []

  Without a language setting, the approval card follows Hermes's own display.language (or HERMES_LANGUAGE), the language of its approval buttons, and else stays in English. The plugin passes its own environment to the command line it runs, so the variables work too. A setting that is off or empty (read_only: false, tools: [], exclude_tools: [], send_dirs: []) passes nothing, so a variable set in that environment still applies: WHATSAPP_TOOLS_READ_ONLY=true keeps the plugin read-only whatever the setting says. A running gateway keeps the environment it started with; restart it (hermes gateway restart) after changing one.

• Claude Code, Grok Build and Antigravity start the plugin's server without flags and pass it the client's environment, so set the variables in the environment the harness runs in.

• Codex passes a plugin's MCP server only a few basic variables (such as PATH and HOME) and those the plugin's manifest names, which are the variables above: set them in the environment Codex runs in. A variable the tools read besides the settings belongs in toolVariables in src/project.ts; pnpm run manifests adds it to the manifest after the settings' variables. To pass flags, or to give the server a variable the package does not name, add the server under [mcp_servers] in Codex's config.toml instead of using the plugin: flags go in args, env_vars names the variables to forward from Codex's environment, and env sets fixed values.

  [mcp_servers.whatsapp-tools]
  command = "npx"
  args = ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
  env_vars = ["WHATSAPP_TOOLS_TOOLSETS"]
  tool_timeout_sec = 330

Accounts and the sync service

The tools use a WhatsApp account as a linked device of the user's phone, the way WhatsApp Web does, through wacli, which you install yourself (brew install openclaw/tap/wacli, or a release binary). They never drive WhatsApp Web or read another client's data.

• wacli 0.26 or later. WhatsApp stops serving old clients until wacli catches up with its protocol, so keep it updated; after an update, restart the sync service so it runs the new release.

• Each linked device has a label, 1 to 24 lowercase letters, digits and _ (default when pairing names none). A tool's account argument picks the label; leave it out when only one device is paired. The account tool instead lists every label when account is absent.

• Each label keeps its state in one directory, <state_dir>/<label>/ (mode 700): wacli's store (the session keys, its mirror of your messages, downloaded media), the sync service's socket, and the copies of files being sent. state_dir defaults to $XDG_STATE_HOME/whatsapp-tools, or ~/.local/state/whatsapp-tools. wacli's own accounts in ~/.wacli are not used. Keep the directory out of backups you share: the keys read and send as you.

• A sync service runs for each label: it keeps the mirror current, and every send and every other write goes through it, so the tools that write need it running. Reads work with or without it. History starts when the device is paired, with what the phone sends then; older messages can be asked of the phone, best effort.

• WhatsApp unlinks a device unused for 30 days, and every linked device when the phone has been unused for 14; a phone takes four linked devices at most. A running service keeps the device in use. An unlinked label is paired again from the phone.

• wacli is not an official client. WhatsApp has no API for personal accounts, and it may limit or ban an account it finds using an unofficial one.

Pairing a device and running the sync service

Install wacli 0.26 or later first: on macOS, brew install openclaw/tap/wacli; elsewhere, a release binary. macOS and Linux are supported; Windows is #11.

The commands come with the npm package, apart from any harness plugin: a plugin gives the tools, not a command on your PATH. Install the package globally, at the version of the plugin you use, so that the service it installs keeps a stable path:

npm install -g @craftsamo/whatsapp-tools@<version>

# On the phone, WhatsApp > Linked devices > Link a device, then scan the QR.
whatsapp-tools-cli pair --account work

# Start syncing at logon, and restart after a failure.
whatsapp-tools-cli service install --account work
whatsapp-tools-cli service status

--account may be left out when only one label exists (pair names a new one default), except by remove, which always needs it; every command takes --state-dir like the tools. With several labels, add --account work to service status too.

Every command below follows whatsapp-tools-cli:

• The service records this package's paths and Node's, so run service install again after updating either. Where Node's path holds its version, as under a version manager, service install records a node on PATH at a path without it that starts the same Node, and warns when there is none. That node then runs whichever Node the manager makes current. service status and whatsapp_account_read say when the recorded program is gone, once the service has been installed with this version. On macOS its log is ~/Library/Logs/io.github.craft-agent.whatsapp-tools/<label>.log; on Linux, journalctl --user -u <unit> as service status shows, and loginctl enable-linger keeps it running while you are logged out.

• On macOS, Login Items lists the service as whatsapp-tools-sync-<label>: the agent starts through that launcher script, which service install writes to ~/Library/Application Support/io.github.craft-agent.whatsapp-tools/ and service uninstall deletes. Switching the item off there stops syncing.

• A phone takes at most four linked devices, and each label is one of them. WhatsApp unlinks a device unused for 30 days, and every linked device when the phone has been unused for 14 days; a running service keeps the linked device in use, not the phone.

• --full-history asks the phone for its full history while pairing, instead of its recent months; --history-days limits how far back. It takes effect only while pairing, and the phone keeps sending for a while after pair ends, which reaches the mirror once the service runs. A device already paired gets older messages with whatsapp_history_backfill, one chat at a time, or by being removed and paired again.

• To pair a revoked label again, run pair again: the dead session is deleted and the mirror is kept. Use a new label for a different account.

• Removing a label logs the device out when possible. If it cannot, remove the linked device on the phone under WhatsApp > Linked devices too.

• whatsapp_account_read tells an agent which step a label needs.

Layout

• src/project.ts — the package's name, tool ID prefix, setting prefix, toolsets, tool options and the other variables its tools read.

• src/core/ — the tool contract and the tools, free of any harness and of the project's names.

• src/tools.ts — the list of every tool, which each entry point registers.

• src/words.ts — the translations of the tools' words, per language, which the native plugins use in their approval prompts.

• src/mcp/ — the MCP server, built to dist/mcp.js and run by whatsapp-tools.

• src/opencode/ — the OpenCode plugin, built to dist/opencode.js.

• src/cli/ — the command line the Hermes plugin calls, built to dist/cli.js and run by whatsapp-tools-cli.

• src/hermes/, plugin.yaml and __init__.py — the Hermes plugin.

• skills/ — one skill per toolset, skills/<name>/SKILL.md, which every harness that takes skills loads from the package or plugin root; the native plugins load only those of the toolsets that are on.

• .claude-plugin/, .codex-plugin/, .agents/plugins/, .mcp.json, .antigravity-plugin/ and mcp_config.json — the plugin manifests of the other harnesses. Codex reads .codex-plugin/plugin.json; a root plugin.json would make it load the plugin as an Agent Plugin, whose tool budget hides tools past a fixed size. The root .mcp.json is the configuration Grok Build reads (with ${CLAUDE_PLUGIN_ROOT}, the variable both Grok Build and Claude Code expand); when working on this repository in Claude Code, decline the project MCP server it offers from that file.

How a release is made is in RELEASING.md.

License

AGPL-3.0 with Commons Clause