Pome Digital Twins

Simulation testing infrastructure for AI agents. Stateful, local digital twins of the APIs your agent calls — GitHub, Stripe, Slack, Gmail, and Linear.

CI npm node License

Docs · Platform · CLI reference

What is Pome?

A digital twin is a local emulation of a production API. It answers the exact same REST, GraphQL, and MCP calls your AI agent makes in production, backed by a real SQLite database — so every run is stateful, deterministic, and resettable. Use it to test and evaluate agents against 137 MCP tools without touching live infrastructure, rate limits, or shared sandbox accounts.

Every route and tool is tiered — semantic (real, tested behavior), shape (faithful response shape), or a loud 501. A twin never silently fakes success.

The twins

Five twins, 137 MCP tools in total. Each documents its surface route-by-route in its FIDELITY.md.

Twin	MCP tools	API surface
twin-github	65 (63 semantic)	62 REST routes — repos, issues, PRs, reviews, merges (push-access gated)	FIDELITY
twin-stripe	26 (all semantic)	43 REST routes — card + x402 crypto PaymentIntents, refunds, charges, balance, events	FIDELITY
twin-slack	11 (all semantic)	50 REST routes — channels, messages, threads, reactions, search	FIDELITY
twin-gmail	13	Frozen Gmail v1 REST — messages, drafts, threads, labels, uploads	FIDELITY
twin-linear	22	GraphQL + OAuth (PKCE) + signed webhooks — the first GraphQL twin	FIDELITY

Quickstart

Prerequisites: Node.js ≥ 24. No install, no clone.

npx @pome-sh/cli init                                  # scaffold tasks + example agent
npx @pome-sh/cli run --local tasks/01-bug-happy-path.md   # boots a twin, runs it, records a trace
npx @pome-sh/cli inspect latest                        # read the trace back

Or start a standalone twin to point your own agent at it:

npx @pome-sh/cli twin start github    # http://127.0.0.1:3333 — prints MCP URL + POME_AUTH_TOKEN

For a persistent pome command: npm install -g @pome-sh/cli.

Running an agent

pome run --local records a run — the trace plus before/after state — for you to read back. The CLI is capture-only: it never scores locally. Evaluation against a task's pass/fail criteria is a hosted feature; pome eval uploads a captured trace for a cloud verdict.

pome run --local tasks/      # self-hosted: records a raw trace
pome eval runs/<task>/<run-id>   # uploads it for a cloud verdict
pome login && pome run tasks/  # hosted: records + evaluates in one go

The bundled task library includes GitHub, Stripe, Slack, Gmail, and Linear flows — several adversarial (identity spoofing, prompt injection, merging a backdoored PR, fabricating green CI). Browse with pome tasks. Eight worked example agents live under examples/.

How it works

Everything ships inside @pome-sh/cli — one install, one entry point. The five twins are thin domain plugins on an internal twin engine that supplies HTTP mounting, bearer auth, the trace recorder, MCP dispatch, SQLite state, and the admin reset/seed gate. Those internals (packages/sdk, packages/twin-*) are implementation detail of the CLI, not separately installable packages.

Every twin honors the frozen CONTRACT.md runtime contract — entry point, env surface, /healthz shape, auth, and MCP surfaces. See packages/README.md for the internal layout.

Authoring your own twin is not a supported product surface today. If that's what you need, tell us: [email protected].

⚠️ Pome is in Beta — the CLI and dependencies may change while the API stabilizes toward v1. Questions or suggestions: [email protected].

Full documentation lives at docs.pome.sh. Licensed Apache-2.0.