Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pome.sh/llms.txt

Use this file to discover all available pages before exploring further.

A Pome twin is a local HTTP server that mimics a real API closely enough that your agent cannot tell the difference. It speaks the same REST routes, returns the same response shapes, and enforces the same invariants — but its state lives in a SQLite file you can reset between runs. No rate limits, no shared sandbox accounts, no network flakiness.

​
How the GitHub twin works

The GitHub twin ships as a Docker container that boots in under 30 seconds and exposes port 3333 by default.
  • State in SQLite. Every repo, issue, label, comment, and collaborator lives in a local SQLite database. Between runs, Pome wipes and reseeds that database from your scenario’s ## Setup block — giving you a clean, deterministic starting point every time.
  • GitHub-shaped REST endpoints. The twin exposes 11 curated REST routes under the same paths GitHub uses (/repos/:owner/:repo/issues/:number, etc.). Your agent’s HTTP client code requires zero changes.
  • 35 MCP tools. The same GitHub operations are also available as MCP tools over a standard MCP transport, so agents built on MCP-based frameworks connect without any adapter.
  • Real error shapes. When something fails, the twin returns the same error envelope GitHub would — 422 Validation Failed with the errors array your agent already parses. It never returns a fake 200 for an operation that would fail on real GitHub.

​
Fidelity tiers

Each REST route and MCP tool carries a fidelity classification that tells you exactly how faithful it is to real GitHub behavior.
TierMeaning
semanticFull stateful behavior is implemented and test-covered. Agents written against real GitHub behave identically against the twin for these surfaces.
shapeResponse shape matches GitHub’s, but side effects may differ. Safe for agents that inspect response fields; not safe for agents that rely on state transitions.
unsupportedNot implemented. Returns a loud 501 — never silently succeeds.

​
What the twin enforces

The twin’s SQLite schema enforces real GitHub invariants via foreign keys. These aren’t artificial rules — they reflect how GitHub actually behaves:
  • Non-existent label on an issue. Calling POST /repos/:owner/:repo/issues/:number/labels with a label that was never created returns 422 Validation Failed. A dumb mock would return 200 and hide the bug.
  • Non-collaborator assignee. Assigning an issue to a user who isn’t a collaborator on the repo returns 422. Your agent has to either seed the right collaborators or handle the rejection.
  • Optimistic locking on file updates. create_or_update_file requires the current file sha when updating an existing file. A stale sha is rejected — exactly as GitHub would reject it.
Any route not in the twin’s supported surface returns 501 with a fidelity: "unsupported" field. Your agent always knows when it has hit a gap — there are no silent 404s or empty responses.

​
Next steps