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.

The GitHub twin aims for high fidelity on the surfaces agents actually use — but it is a curated subset, not a universal clone. This page documents what is faithful, what is approximate, and what returns a loud error instead of silently misbehaving.

​
Fidelity tiers

Every MCP tool and REST route is classified into one of three tiers.
The stateful behavior is fully implemented locally and covered by tests. Optimistic locking, label invariants, branch ancestry, and other side effects behave exactly as they do on real GitHub. Agents written against real GitHub run unchanged against a semantic-tier surface.
The response shape is checked against captured real-GitHub fixtures, but the underlying side effects may differ. Safe for agents that read and inspect responses; not safe for agents that depend on specific side effects being executed.
Not implemented. The twin returns a loud 501 envelope rather than a silent 404, so an agent never silently succeeds against a missing route. If your agent hits a 501, that is the gap to file.
The bar Pome aims for: agents written against real GitHub run unchanged against the local twin for the surfaces listed in the MCP tools reference and the REST surface reference, and fail loudly for anything outside them.

​
What the twin enforces

The following invariants are enforced at the semantic tier — the twin returns a GitHub-shaped 422 or conflict error, not a permissive 200.
  • Labels must exist before you can apply them. Attempting to add a label to an issue when that label has not been seeded returns a 422 with code: "missing". This mirrors how GitHub enforces label existence.
  • Assignees must be seeded collaborators. Attempting to assign a user who is not in the collaborators table returns a 422 with code: "invalid". You cannot assign arbitrary usernames.
  • File updates require the current SHA. create_or_update_file requires the sha of the file you are updating. Sending a stale or missing SHA when the file exists returns a conflict error — the same optimistic locking GitHub enforces.
  • Create-or-update on an existing file without SHA returns a conflict error. If the file already exists and you do not supply sha, the call fails. This prevents accidental overwrites.

​
Known limitations

These are documented deviations from real GitHub behavior. They appear in the source FIDELITY.md and are kept up to date with each release.
AreaLimitation
IssuesIssue timeline and events are not modeled
IssuesMilestones and projects are not implemented
BranchesBranch protection rules are not modeled
FilesSymlinks, submodules, and media/raw file modes are not supported
SearchSearch is substring-based, not full GitHub search syntax
Pull requestsInline review comments are not created by create_pull_request_review
Pull requestsupdate_pull_request_branch is shape tier only — it updates the local branch pointer but does not create GitHub’s merge commit or run an async update job
Pull requestsDrafts, mergeability background jobs, and review decisions are simplified
CommentsComment edit and delete APIs are not implemented
CollaboratorsPermission filtering on list_collaborators is not implemented
UsersOrganization/user scoring in search_users is simplified

​
Filing a fidelity gap

If you find a case where your agent behaves differently against the twin than against real GitHub in a way the tables above do not predict, open a GitHub issue with:
  1. The MCP tool or REST route involved.
  2. A minimal repro: the request you sent, the local response you got, and the real GitHub response.
  3. Whether the divergence is shape (keys or types differ) or semantic (state transition behaves differently).
If you hit the 501 envelope on a route your agent needs, that is the gap to file. The 501 is intentional — it tells you exactly which surface is missing rather than letting the agent succeed silently against a wrong response.

​
Comparing against real GitHub

The twin’s MCP surface is URL-portable. You can point the same agent harness at real GitHub to verify that behavior matches:
  1. Run your agent against the twin and capture the trace.
  2. Point the same agent at a real GitHub repo you control using the same scenario.
  3. Compare tool call outcomes and state transitions.
Because the twin uses the same REST paths and MCP tool names as real GitHub, no changes to your agent code are needed when switching between the twin and production.