@agentcomms/core

The provider-neutral core of agent-communications: the config and inbox registry, the secret store (OS keychain or owner-only files), the approval engine for sends, posts and configuration changes, the audit log, path jails, and the untrusted-content envelope and HTML sanitiser that keep what a sender wrote — an email or a Slack message — from steering an agent.

Most people want a platform package instead: npx @agentcomms/gmail --help or npx @agentcomms/slack --help — or this package's MCP server, which installs those for an agent.

The agentcomms command

npx @agentcomms/core paths      # where config, state and downloads live
npx @agentcomms/core doctor     # Node version, directory permissions, secret store
npx @agentcomms/core audit tail # mailbox writes, Slack prepares and posts, and every step of a change, newest last (no bodies, no secrets)
npx @agentcomms/core approvals list
npx @agentcomms/core approve <id>  # approve a settings change an agent prepared: read it, type the code it shows
npx @agentcomms/core policy        # the change policy: how a loosening is approved — chat or confirm
npx @agentcomms/core attach        # which files may be attached: the folders, your deny entries, the built-in list
npx @agentcomms/core attach roots add ~/Documents/outgoing  # allow another folder (a change you approve)
npx @agentcomms/core channels      # which servers exist, which are installed, and where each is registered
npx @agentcomms/core mcp install --client claude-code   # register the core MCP server
npx @agentcomms/core update --check  # what is behind the latest release; `update` brings it there, as one change
npx @agentcomms/core update --later  # not now: nothing stops for the update until midnight (a change you approve)
npx @agentcomms/core update --auto off  # no daily update check on this machine (a change you approve); --auto on

Once a day this machine asks npm whether a newer release is out. When one is, every server and every command stops before doing anything — "Hang on a minute, there's an update. Let's update first." — until it is updated or put off until midnight. At a terminal you are asked "Update now, later today, or cancel?"; anything without a terminal exits 11 (UPDATE_REQUIRED), naming agentcomms update and agentcomms update --later. update, doctor, paths, approve, approvals and mcp on its own (the server, which stops each call itself — mcp install and mcp prune are stopped) are never stopped, and neither is a call or a command carrying the id of an approval already given on this machine. A registry that cannot be reached stops nothing. The check is skipped when CI is set, or AGENT_COMMS_UPDATE_CHECK=off; doctor shows it on one line.

Every command takes --json and prints { "ok": true, "schemaVersion": 1, "data": … } or { "ok": false, "schemaVersion": 1, "error": { "code", "message", "hint" } }.

A command that loosens something or cannot be undone — policy chat, attach roots add, attach deny remove, mcp install, mcp prune, update, secrets migrate, names migrate — shows the change first (policy confirm, attach roots remove and attach deny add tighten, so they apply at once). At a terminal you approve it there; anything else gets the preview and an approval id and exits 10, and runs the same command again with --approval <id> once the person has agreed. agent-gmail and agent-slack register and prune their own servers through the same change, so an approval comms_server_install or comms_server_prune prepared is claimed by their mcp install or mcp prune for the same request, and the other way round.

The core MCP server

agentcomms mcp runs it on stdio; agentcomms mcp install --client <client> registers it, from a terminal, since it is the one registration that cannot come from chat. After a restart of the client, an agent can do the rest:

| Tool | What it does | |---|---| | comms_channels_available | which servers exist — core, Gmail, Slack — which are installed and at which version, and which clients start each | | comms_server_install | register the Gmail, Slack or core server with a client; the server appears once the client restarts | | comms_server_prune | remove the managed runtimes old releases left behind; dryRun lists them | | comms_update | what is behind the latest release (check), and bringing every registration, runtime and global package there as one change; later puts the daily check's stop off until midnight, auto turns the check on or off | | comms_change_policy | report or set the change policy of the defaults, a mailbox or a workspace | | comms_attach | which files may be attached, as attach; rootsAdd allows another folder once the person approves, and rootsRemove, denyAdd and denyRemove change the rest | | comms_names_migrate | rename every account to organisation/platform; dryRun shows the mapping | | comms_secrets_migrate | move every credential between the keychain and files | | comms_paths, comms_doctor, comms_audit_tail | as paths, doctor and audit tail | | comms_approvals_list, comms_approval_revoke | as approvals list and approvals revoke |

Every change is shown to a person before it happens: the first call returns a preview and an approval id, and the same tool called again with that id applies it — after the person's yes in the conversation under the chat change policy, or after they run agentcomms approve <id> under confirm. No tool approves a change, and none applies a change it did not plan itself.

Licence

MIT