> ## 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.

# How Pome works

> Digital twins, tasks, runs, scoring, and where artifacts land.

Pome tests agents by running them against deterministic digital twins, recording every
action they take, and scoring the outcome. The loop is identical whether you drive
it from the CLI, a coding-agent skill, or the dashboard.

## The loop

```text theme={null}
Task (seed + prompt + criteria)
        ↓
   pome run
        ↓
  Digital twin boots with seed state
        ↓
  Agent runs (tool calls hit the digital twin)
        ↓
  Pome records events + exports digital twin state
        ↓
  Judge scores [code] and [model] criteria
        ↓
  Artifacts + dashboard URL
```

## Digital Twins

A digital twin is an in-process (or hosted) simulation of a real SaaS API. It reproduces the
exact response shapes and error semantics of the live service without ever calling it.

| Digital Twin | Config              | What agents exercise                         |
| ------------ | ------------------- | -------------------------------------------- |
| GitHub       | `twins: ["github"]` | Issues, PRs, labels, comments, commit status |
| Stripe       | `twins: ["stripe"]` | PaymentIntents, refunds, x402 paywalls       |
| Slack        | `twins: ["slack"]`  | Channels, messages, threads, reactions       |
| Gmail        | `twins: ["gmail"]`  | Messages, threads, labels, drafts            |
| Linear       | `twins: ["linear"]` | GraphQL issues, comments, labels, projects   |

Each run starts from the task's **seed state** — a JSON block that describes
the digital twin's initial world (repos, charges, channels, etc.). The digital twin resets between
runs so the same task produces the same baseline every time.

See the [Digital Twins reference](/docs/twins/github) for per-service coverage, env vars, and bundled
tasks.

## Tasks

A task is a markdown file with three parts:

1. **`## Seed State`** — JSON the digital twin loads before the agent starts.
2. **`## Prompt`** — passed to the agent as `POME_TASK`.
3. **Acceptance criteria** — `[code]` deterministic checks on digital twin state or events;
   `[model]` probabilistic checks judged by an LLM.

```yaml theme={null}
# ## Config
twins: ["github"]
timeout: 60
passThreshold: 100
```

Browse and copy bundled tasks:

```bash theme={null}
pome tasks github --copy
```

## Runs

`pome run <task.md>` boots the matching digital twin, spawns your agent with injected
environment variables (`POME_<TWIN>_REST_URL`, `POME_AUTH_TOKEN`, etc.), waits for
the agent to exit, then scores the result.

Hosted is the default — runs record to [app.pome.sh](https://app.pome.sh). Set
`POME_LOCAL=1` for engineer-only in-process local digital twins.

## Artifacts

Every run writes a directory at `runs/<task>/<run-id>/`:

| File                                      | Contents                                                                          |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| `events.jsonl`                            | Canonical event stream — `TwinHttpEvent`, `LlmCallEvent`, `RunStartedEvent`, etc. |
| `score.json`                              | Per-criterion verdicts and aggregate satisfaction (0–100).                        |
| `state_initial.json` / `state_final.json` | Digital twin state before and after the agent.                                    |

<Note>
  `tool_calls.jsonl` is also written for older clients. New integrations should read
  `events.jsonl`.
</Note>

Hosted runs also get a dashboard URL with the full trace, score breakdown, and judge
handoff for failures.

## Scoring

* **`[code]` deterministic** — Pome checks digital twin state or recorded events directly.
  Example: "issue #42 has label `bug`" or "no message containing the secret appears
  in a public channel."
* **`[model]` probabilistic** — An LLM judge reads the trace and evaluates judgment
  criteria. Example: "the agent recognized the label was contextually wrong."

A run passes when satisfaction ≥ `passThreshold` (default 100).

## When to run pome

Run pome before merging changes that affect agent behavior:

* Prompt or system-instruction edits
* New or modified tools
* Model swaps
* Digital twin integration changes (new API surface your agent calls)

Compare scores across runs. The trace shows exactly which tool calls changed and
which criteria flipped.

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart/claude-code">
    Install and complete your first run.
  </Card>

  <Card title="Dashboard" icon="gauge" href="/docs/dashboard">
    Where runs, sessions, and judge feedback live.
  </Card>

  <Card title="pome run" icon="terminal" href="/docs/cli/run">
    CLI reference for running tasks.
  </Card>

  <Card title="/test-with-pome" icon="flask-conical" href="/docs/skills/test-with-pome">
    Run tasks from your coding agent with `/pome-test`.
  </Card>
</CardGroup>