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.

​
Pome User Guide

This guide will walk you from a fresh clone to a local agent run against the Pome GitHub twin. The default flow uses a scripted agent, so you do not need an LLM API key for the first green run.

​
Prerequisites

node --version   # Node 20+
bun --version

​
Install

From this research workspace: 
cd ~/GitHub/cli
bun install
bun run build
bun run test

​
Initialize

bun run pome -- init
This creates local folders and pome.config.json if they do not exist.

​
Run The Scripted Agent

Use this first. It makes no network calls and needs no API key. 
bun run pome -- run scenarios/01-bug-happy-path.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
bun run pome -- inspect latest
Run every starter scenario: 
bun run pome -- run scenarios/01-bug-happy-path.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
bun run pome -- run scenarios/02-missing-label.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
bun run pome -- run scenarios/03-already-triaged.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
You should see three PASS lines at 100/100.

​
What Just Happened

Pome started a local GitHub-shaped HTTP server on your MacBook, seeded it from the scenario, then launched the agent as a child process. The agent received:
  • POME_TASK
  • POME_GITHUB_REST_URL
  • POME_GITHUB_MCP_URL
  • POME_TWIN_NAMES
  • POME_RUN_ID
  • POME_ARTIFACTS_DIR
The agent called the local twin, not GitHub. Pome recorded every request, evaluated the final twin state, and wrote a run folder under runs/.

​
Manually Poke The Twin

In one terminal: 
bun run pome -- twin start github --port 3333
In another: 
export POME_GITHUB_REST_URL=http://127.0.0.1:3333/s/standalone
export POME_AUTH_TOKEN=<token printed by pome twin start>

curl -H "Authorization: Bearer $POME_AUTH_TOKEN" "$POME_GITHUB_REST_URL/repos/acme/api/issues/1"
curl -H "Authorization: Bearer $POME_AUTH_TOKEN" "$POME_GITHUB_REST_URL/repos/acme/api/labels"
curl -H "Authorization: Bearer $POME_AUTH_TOKEN" "$POME_GITHUB_REST_URL/mcp/tools"
curl -s "$POME_GITHUB_REST_URL/mcp/call" \
  -H "Authorization: Bearer $POME_AUTH_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"tool":"search_repositories","arguments":{"query":"acme"}}'
pome twin start github launches the standalone GitHub twin and prints the session-scoped URLs plus a local bearer token: 
POME_GITHUB_REST_URL=http://127.0.0.1:3333/s/standalone
POME_GITHUB_MCP_URL=http://127.0.0.1:3333/s/standalone/mcp
POME_AUTH_TOKEN=...
The GitHub twin is the standalone ../github_clone package. Its default seed contains acme/api, branch main, README.md, src/index.ts, labels, and issue #1. Reset standalone twin state: 
bun run pome -- twin reset

​
Use The GitHub Clone For A New Agent

For a new project, define the state the agent should see before it runs. The seed should include:
  • users and organizations the agent can mention
  • repositories, default branches, and collaborators
  • files the agent should read or modify
  • labels, issues, and pull requests needed by the scenario
Post a seed directly to the clone when you need project-specific state: 
curl -s -X POST http://127.0.0.1:3333/admin/seed \
  -H 'content-type: application/json' \
  -d '{
    "users": [{ "login": "my-org", "type": "Organization", "name": "My Org" }],
    "repositories": [{
      "owner": "my-org",
      "name": "my-app",
      "default_branch": "main",
      "files": [{ "path": "README.md", "content": "# My App\n" }],
      "issues": [{ "number": 1, "title": "Fix checkout error", "labels": ["bug"] }]
    }]
  }'
Then give the agent:
  • POME_GITHUB_REST_URL
  • POME_GITHUB_MCP_URL
  • the exact owner/repo, branch, issue number, or file path it should work on
  • instructions to compare outcomes, not generated IDs or SHAs
If you want to compare with Archal, run the same task against Archal’s GitHub MCP URL after starting and seeding an Archal session. Expect protocol and metadata differences: Archal uses JSON-RPC MCP sessions, dynamic PR numbers, and different generated IDs, timestamps, and SHAs. The behavior should match for the tested flows.

​
Optional LLM Agent

The LLM example calls Anthropic directly. It is optional, and it is not part of the first green run. 
export ANTHROPIC_API_KEY=sk-ant-...
bun run pome -- run scenarios/01-bug-happy-path.md --agent "npx tsx examples/agents/llm-triage-agent.ts"

​
Debug A Failure

bun run pome -- inspect latest
open runs/<scenario>/<run-id>/tool_calls.jsonl
open runs/<scenario>/<run-id>/score.json
open runs/<scenario>/<run-id>/state_final.json
tool_calls.jsonl is the product. It tells you exactly what the agent tried, what the twin returned, and whether the call mutated state.