README
¶
Agent GM
MCP and CLI access to your own Google Messages. One Go binary, one owner, as many Google accounts as you have. It pairs directly with the phone, the way the Google Messages web client does; there is no bridge and no UI for humans.
It imports the Google Messages client library from
mautrix-gmessages (pkg/libgm, pinned
by commit), keeps its state in one SQLite file, and serves three surfaces over
the same core:
- MCP — streamable HTTP at
/mcp, OAuth 2.1, for claude.ai and ChatGPT connectors and for local agents.docs/mcp.md - REST — JSON under
/v1, for scripts and for the CLI.docs/api.md - CLI —
agm, from npm or from a GitHub release binary.docs/cli.md
The CLI is a client of the REST API and nothing else, so anything agm can do
an agent can do, and the reverse.
Quickstart
Three secrets, one container, one pairing.
# 1. Run the server. It needs a public HTTPS origin in front of it.
export AGENT_GM_PUBLIC_URL=https://gm.example.com
export AGENT_GM_ADMIN_SECRET=$(openssl rand -base64 48) # >= 43 characters
export AGENT_GM_DATA_KEY=$(openssl rand -hex 32) # 256 bits, NOT rotatable
docker compose -f compose.example.yml up -d --wait
curl -fsS http://localhost:8080/healthz # {"status":"ok"}
# 2. Get a credential for the machine you drive it from.
npm i -g @agent-gm/cli
printf %s "$AGENT_GM_ADMIN_SECRET" |
agm auth login --admin --server https://gm.example.com --secret-stdin
# 3. Pair a Google account. Chrome opens; you sign in and tap an emoji on the phone.
agm pair
agm conversations list
Back up AGENT_GM_DATA_KEY with the data directory. It cannot be rotated, and
without it a restored sessions/ directory is unreadable.
Then: docs/deploy.md for a real host,
docs/pairing.md for what happens on the phone, and
docs/oauth.md for giving a connector a token.
Documentation
docs/README.md |
index of the pages below |
docs/pairing.md |
adding, refreshing, signing out and removing a Google account |
docs/api.md |
every REST route, DTO and error code |
docs/cli.md |
every agm command, flag and exit code |
docs/mcp.md |
the MCP tool catalogue and transport |
docs/oauth.md |
the authorization server, enrollment codes and approval |
docs/deploy.md |
the image, Compose, /data, releases |
docs/operations.md |
configuration, backup and restore, the runbook |
CHANGELOG.md |
each release with its GHCR digest and both pins |
plans/AGENT_GM_SPEC.md |
the specification, which is the contract |
CONTRIBUTING.md |
whether to send a pull request — short answer: this is a personal project |
Development
Devbox only. Do not install tooling on the host; add it to devbox.json.
devbox run check # build, vet, lint, test -race, and the repository lints
devbox run test
devbox run lint
devbox run build
make check and friends are thin wrappers over the same scripts.
Licence
Licensed under AGPL-3.0-or-later. Agent GM is reachable over a network, so it
offers its own corresponding source: GET /v1/health reports commit and
source_url, and the MCP serverInfo reports the same two facts as semver
build metadata on version and as websiteUrl. If you deploy a modified
build, that offer must point at your source.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
agent-gm
command
Command agent-gm is Agent GM.
|
Command agent-gm is Agent GM. |
|
agm
command
Command agm is Agent GM's command-line client (spec section 11).
|
Command agm is Agent GM's command-line client (spec section 11). |
|
internal
|
|
|
acceptance
Package acceptance holds the Slice 2 acceptance tests that need a whole server rather than one package: the sentinel-secret scan of spec section 12.2, and the end-to-end walks of section 16 that cross every layer.
|
Package acceptance holds the Slice 2 acceptance tests that need a whole server rather than one package: the sentinel-secret scan of spec section 12.2, and the end-to-end walks of section 16 that cross every layer. |
|
accounts
Package accounts is the account registry and supervisor: which accounts exist, their state, one gm.Backend and one ingest goroutine each, and start/stop on pair, sign-out and remove (spec section 2.2).
|
Package accounts is the account registry and supervisor: which accounts exist, their state, one gm.Backend and one ingest goroutine each, and start/stop on pair, sign-out and remove (spec section 2.2). |
|
api
Package api serves the REST surface of spec section 7: handlers, DTOs, the error envelope, strict parameter rejection and pagination.
|
Package api serves the REST surface of spec section 7: handlers, DTOs, the error envelope, strict parameter rejection and pagination. |
|
apierr
Package apierr is the one place the Agent GM REST error taxonomy lives.
|
Package apierr is the one place the Agent GM REST error taxonomy lives. |
|
audit
Package audit is the append-only audit log of spec section 12.4.
|
Package audit is the append-only audit log of spec section 12.4. |
|
authz
Package authz is Agent GM's credential logic: what a scope is, how the admin bootstrap session of spec section 9.7 is minted and refreshed, how a presented token is authenticated, and every limiter that stands in front of those three (spec sections 9.6, 9.8, 12.1, 12.3).
|
Package authz is Agent GM's credential logic: what a scope is, how the admin bootstrap session of spec section 9.7 is minted and refreshed, how a presented token is authenticated, and every limiter that stands in front of those three (spec sections 9.6, 9.8, 12.1, 12.3). |
|
cli
Package cli holds the pieces `agm` needs that are not the REST client: the Chrome cookie capture, the paste fallback, and the messages the owner reads at a terminal (spec section 11.4).
|
Package cli holds the pieces `agm` needs that are not the REST client: the Chrome cookie capture, the paste fallback, and the messages the owner reads at a terminal (spec section 11.4). |
|
clock
Package clock is the injected time source every timeout in Agent GM is measured against (spec section 13.1).
|
Package clock is the injected time source every timeout in Agent GM is measured against (spec section 13.1). |
|
config
Package config reads Agent GM's environment.
|
Package config reads Agent GM's environment. |
|
core
Package core holds the operations the surfaces share: ingestion (backfill, the live stream and the reconciliation sweep), and the mutation pipeline.
|
Package core holds the operations the surfaces share: ingestion (backfill, the live stream and the reconciliation sweep), and the mutation pipeline. |
|
gm
Package gm is Agent GM's entire dependency on Google Messages.
|
Package gm is Agent GM's entire dependency on Google Messages. |
|
gm/fake
Package fake is a deterministic in-memory Google Messages.
|
Package fake is a deterministic in-memory Google Messages. |
|
lint
Package lint is the name lint of spec section 13.5.
|
Package lint is the name lint of spec section 13.5. |
|
logging
Package logging builds Agent GM's two loggers.
|
Package logging builds Agent GM's two loggers. |
|
media
Package media holds the upload and download tickets, the media cache on disk, content sniffing and the size limits of spec section 10.
|
Package media holds the upload and download tickets, the media cache on disk, content sniffing and the size limits of spec section 10. |
|
oauth
Package oauth is Agent GM's OAuth 2.1 authorization server (spec section 9).
|
Package oauth is Agent GM's OAuth 2.1 authorization server (spec section 9). |
|
settings
Package settings is the runtime settings table of spec section 15.1: the keys that are mutable through `PATCH /v1/admin/settings` without an environment change and without a redeploy.
|
Package settings is the runtime settings table of spec section 15.1: the keys that are mutable through `PATCH /v1/admin/settings` without an environment change and without a redeploy. |
|
wire
Package wire holds the renderings every JSON surface must agree on.
|
Package wire holds the renderings every JSON surface must agree on. |
Click to show internal directories.
Click to hide internal directories.