README
¶
Agent GM
MCP and CLI access to your own Google Messages, paired directly with your phone through the Google Messages web protocol. One Go binary, one owner, as many Google accounts as you have. No Matrix, no bridge, no UI for humans.
It imports the Google Messages client library from
mautrix-gmessages (pkg/libgm,
pinned by commit), keeps its state in SQLite, 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. - REST — JSON under
/v1, for scripts and for the CLI. - CLI —
agm, distributed as a GitHub release binary and, if the name is available, an npm wrapper (spec §14.3, open question OQ-4).
Status: design phase. No code yet.
Where things are
| The specification, and the contract | plans/AGENT_GM_SPEC.md |
| What each doc page will cover | docs/README.md |
| Whether to send a pull request | CONTRIBUTING.md — short answer: this is a personal project |
Start with spec §1 (goals and non-goals) and §3 (the Google layer contract). §16 is the build order, four slices, each with its acceptance tests.
Development
Devbox only. Do not install tooling on the host; add it to devbox.json.
devbox run check # build, vet, lint, test -race
devbox run test
devbox run lint
devbox run build
make check and friends are thin wrappers over the same scripts.
Licence
AGPL-3.0-or-later, because Agent GM links libgm, which is AGPL-3.0, and no
upstream exception covers this project. Agent GM is reachable over a network,
so AGPL §13 applies: it serves its own source URL and built commit from
GET /v1/health and from the MCP serverInfo. That is why this repository is
public. Spec §1.4.
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.