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 passes twin connection details to your agent via environment variables — no SDK required. When you run pome run, Pome boots a fresh twin, seeds it with the scenario’s initial state, and then launches your agent command with a set of POME_* variables in its environment. Your agent reads those variables, calls the twin’s REST or MCP surface, and exits. Pome records every call and scores the result.

​
Environment variables Pome sets

VariablePurpose
POME_TASKThe agent’s task string, taken from the scenario’s ## Prompt section
POME_GITHUB_REST_URLBase URL for the GitHub-shaped REST surface (e.g., http://127.0.0.1:3333)
POME_AUTH_TOKENBearer token for authenticated twin requests (set in hosted mode)
POME_TWIN_NAMESComma-separated list of twin names active for this run (e.g., github)
POME_RUN_IDUnique identifier for this run, used to correlate trace artifacts
POME_ARTIFACTS_DIRDirectory where the agent can write its own output files
POME_PREFLIGHTSet to "1" during the preflight check before the real run starts

​
Minimum agent shape

Your agent only needs to read POME_TASK and POME_GITHUB_REST_URL and call the twin. Everything else is optional. Handle the preflight check first — Pome calls your agent with POME_PREFLIGHT=1 before starting a real run to verify that the agent binary is reachable. 
if (process.env.POME_PREFLIGHT === "1") {
  console.log("preflight ok");
  process.exit(0);
}

const task = process.env.POME_TASK;
const githubUrl = process.env.POME_GITHUB_REST_URL;

if (!task || !githubUrl) {
  throw new Error("Pome env vars are required");
}

const issue = await fetch(`${githubUrl}/repos/acme/api/issues/1`).then(r => r.json());

console.log(JSON.stringify({ summary: "Agent completed" }));

​
Using the MCP surface

The twin also exposes 35 GitHub-shaped MCP tools at its MCP endpoint. If POME_GITHUB_MCP_URL is set, use that directly; otherwise derive the MCP URL from POME_GITHUB_REST_URL: 
MCP endpoint: {POME_GITHUB_REST_URL}/s/{session-id}/mcp
Call a tool by posting to POST /s/:sid/mcp/call with a name and arguments body: 
curl -X POST "$POME_GITHUB_REST_URL/s/demo/mcp/call" \
  -H "Authorization: Bearer $POME_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_issue",
    "arguments": { "owner": "acme", "repo": "api", "issue_number": 1 }
  }'
The response is the tool’s return value as JSON, following the MCP call result shape.

​
Running your agent

Pass your agent command to pome run using the --agent flag: 
# Run a single scenario
pome run scenarios/01-bug-triage.md --agent "bun run start"

# Run every scenario in a directory
pome run scenarios/ --agent "npx tsx my-agent.ts"
Pome runs the agent command in a subprocess with all POME_* variables injected. Your agent’s stdout and stderr are captured and included in the run trace.

​
Agent examples

A minimal agent that reads the task from the environment, fetches an issue over the GitHub-shaped REST surface, applies a label, and exits.
if (process.env.POME_PREFLIGHT === "1") {
  console.log("preflight ok");
  process.exit(0);
}

const task = process.env.POME_TASK;
const githubUrl = process.env.POME_GITHUB_REST_URL;
const authToken = process.env.POME_AUTH_TOKEN;

if (!task || !githubUrl) {
  throw new Error("POME_TASK and POME_GITHUB_REST_URL are required");
}

const headers: Record<string, string> = { "Content-Type": "application/json" };
if (authToken) {
  headers["Authorization"] = `Bearer ${authToken}`;
}

// Read the issue
const issue = await fetch(`${githubUrl}/repos/acme/api/issues/1`, { headers })
  .then(r => r.json());

console.error("Read issue:", issue.title);

// Apply a label (label must already exist in the seed)
await fetch(`${githubUrl}/repos/acme/api/issues/1/labels`, {
  method: "POST",
  headers,
  body: JSON.stringify({ labels: ["bug"] }),
});

console.log(JSON.stringify({ summary: "Labeled issue #1 as bug" }));
Run it:
pome run scenarios/01-bug-triage.md --agent "npx tsx my-agent.ts"
For the full list of MCP tools the GitHub twin exposes, see the MCP tools reference.