digital-twins

# Pome

> Test mode for your integrations, built for the way agents build. Local, stateful twins of GitHub, Slack, Stripe, Gmail and Linear, over REST, GraphQL and MCP, backed by real SQLite state. No test account, no OAuth app, no API key. Every request lands on a tape: the twin's own record of every call and what it changed, so a step the agent only claimed shows up as a step that did not happen. 5 digital twins, 115 MCP tools, Apache-2.0.

## Getting started

- Start a twin: `npx @pome-sh/cli@latest twin start github`. It prints its address, a token it mints itself, and the connect block for Claude Code, Codex, `.mcp.json` and the vendor's own SDK. There is no account and no login.
- Watch it live: `twin start` also prints a `Dashboard:` link. Every call the agent makes lands there as it happens, with what it changed, and a write that did not land turns red.
- Read what the agent did from a terminal or CI: `npx @pome-sh/cli@latest twin tape --diff`. One line per request, REST or MCP, with the state each one changed. A write that did not land reads `no change`.
- Several twins at once: `npx @pome-sh/cli@latest twin start github slack linear`. Each takes its own port, and one connect block covers all of them.
- Your own starting state: `npx @pome-sh/cli@latest twin new-seed github --out seed.json`, edit it, then `twin start github --seed seed.json`. The twin is named on the command line, not in the file, and the seed REPLACES the twin's default state rather than merging into it.
- Requires Node.js 24 or newer. The twins run on Node's built-in SQLite.

## Twins

Every route carries one fidelity level: `semantic` (the route implements and tests provider behavior), `shape` (the response has the provider's shape), `unsupported` (the twin returns `501` rather than a guess). Pome replays the same requests against the real vendor API daily and publishes the result per route at [status.pome.sh](https://status.pome.sh).

- [twin-github](./packages/twin-github/FIDELITY.md): 36 MCP tools — repositories, issues, pull requests, reviews, merges (push-access gated)
- [twin-stripe](./packages/twin-stripe/FIDELITY.md): 26 MCP tools — PaymentIntents, refunds, charges, balances, events, and x402 crypto payments
- [twin-slack](./packages/twin-slack/FIDELITY.md): 18 MCP tools — channels, messages, threads, reactions, search
- [twin-gmail](./packages/twin-gmail/FIDELITY.md): 13 MCP tools — frozen Gmail v1: messages, drafts, threads, labels, uploads
- [twin-linear](./packages/twin-linear/FIDELITY.md): 22 MCP tools — GraphQL, OAuth with PKCE, and signed webhook registration

The twins answer requests. They do not call your app, and no twin delivers webhooks today.

## Docs

- [Documentation](https://docs.pome.sh): full guides, CLI reference, and per-package details
- [Connect guide](https://docs.pome.sh/docs/mcp/connect): the stanza for Cursor and the other clients
- [Runtime contract](./CONTRACT.md): the frozen v1.6.0 twin contract every twin honors
- [Endpoint-tier rubric](./packages/sdk/ENDPOINT-TIERS.md): what semantic, shape and unsupported mean per route
- [Contributor & agent conventions](./AGENTS.md): how to work in this repo
- [Internal package architecture](./packages/README.md): the twin registry, the shared `@pome-sh/wire` trace surface, and which packages are private vs. published

## Packages

- [@pome-sh/cli](https://www.npmjs.com/package/@pome-sh/cli): the `pome` CLI — start twins, read tapes, run tasks. The twin engine and all five twins ship inside it; there is nothing else to install.

## Going further

- Swap to the real API: the base URL and the credential change, plus whatever vendor-side setup the twin never asked for. Nothing else in your code should.
- Run it in CI: the same `twin start` command in a GitHub Actions job, with the token minted on the runner and dying with the twin. No secret in the repository.
- Graded tasks, locally: `npx @pome-sh/cli@latest init` scaffolds a project, `pome run --local tasks/01-bug-happy-path.md` records a run, and `pome inspect latest` reads it. A local run records evidence and does not score.
- Hosted twins, scoring and observability are optional, and live at [pome.sh](https://pome.sh).