> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Register your harness for replays

> Have your coding agent describe your agents, prompt switching, tools, skills, and injected context with moda registry, so replays rebuild the agent that actually answered.

A replay re-runs the assistant side of a recorded production conversation. It's only as faithful as what Moda knows about how your agent runs: which agent answered the replayed turn, with which prompt version, model, sampling settings, tools, and skills, how control moves between agents, and what context your code injects into the prompt. `moda registry` lets your own coding agent (Claude Code, Codex, Cursor) describe all of that from your codebase. You don't need the GitHub App or a repo upload.

## Hand it to your coding agent

```bash theme={"dark"}
moda registry prompt | pbcopy        # or: claude "$(moda registry prompt)"
```

The brief walks your agent through these steps:

1. Inventory every LLM call site.
2. Work out how the harness switches prompts.
3. List the context it injects.
4. Write `.moda/registry.json`, then validate and push it.
5. Make your traces name the agent and prompt version on each call. It shows you the diff first.
6. Check the result with `moda registry coverage`.

## What gets registered

| Section | What it captures | How replay uses it |
| - | - | - |
| `prompts` | Prompt text, templates, few-shot `messages`, `modelConfig` | The live agent's prompt: the version attributed on the replayed turn, otherwise prod |
| `tools` | OpenAI function schemas, verbatim | Tool contracts for the replayed model and the tool simulator |
| `skills` | SKILL.md files | Loaded for the agents that list them |
| `agents` | Prompt, model and params, tools, skills, handoffs, subagents, trace names | The agent rebuilt for the replayed turn |
| `routing` | `single`, `handoff`, `router`, `rules`, or `trace_attribute`, plus a default agent | Fallback when the trace doesn't name an agent |
| `context` | Static values, the clock, and per-user, memory, retrieval, or tool context | Static and clock values are filled in (the clock uses the original conversation's time). The others are reported as unresolved and never invented |
| `runtime` | Framework, tool rounds per turn, history policy, skill loading | Tool-round budget and how skills are offered |
| `mcpServers` | Server names, transports, and tools (no credentials) | Recorded with the harness; their tools replay like any registered tool |

## Prompt switching

Replay picks the agent for a replayed turn in this order:

1. **The agent name on the trace**: `gen_ai.agent.name` or `moda.agent_name` on the LLM call that answered the turn, matched against each agent's `key`, `name`, and `match.agentNames`.
2. **The prompt on the trace**: `moda.prompt_key`, `moda.prompt_id`, or `moda.prompt_version_id`, matched against each agent's `prompt` and `match.promptKeys`.
3. `routing.default`, then the agent marked `"entry": true`.

When the replayed model calls a handoff tool (for example `transfer_to_billing`), replay switches to the target agent's prompt, tools, model, and sampling settings for the rest of the conversation. That's how the OpenAI Agents SDK, supervisor patterns, and similar harnesses move control between agents.

Attribution comes from your traces. Auto-instrumented OpenAI and Anthropic calls don't carry it, so add it where you build each agent or make each call:

| What | OTel span attribute | Vercel AI SDK `experimental_telemetry.metadata` | `/v1/ingest` event field |
| - | - | - | - |
| Agent | `gen_ai.agent.name` or `moda.agent_name` | `moda.agent_name` | `agent_name` |
| Prompt key | `moda.prompt_key` | `moda.prompt_key` | `prompt_name` |
| Prompt version | `moda.prompt_version_id` | `moda.prompt_version_id` | `prompt_version_id` |

See [Prompt attribution](/prompt-management/attribution) for full examples.

## History: every push is a commit

Each successful `moda registry push` records a commit. A commit is a snapshot of
everything registered, rendered as files:

* `agents/<key>.json`
* `prompts/<key>.md`
* `tools/<name>.json`
* `skills/<key>/SKILL.md`
* `harness/routing.json`, `harness/runtime.json`, `harness/context.json` and `harness/mcp-servers.json`

Each commit also records your repo's git SHA, branch, and whether the checkout had uncommitted changes. Label a push with `--message`.

```bash theme={"dark"}
moda registry push --message="Add billing agent"
moda registry log                  # one commit per push
moda registry show 3f9a2c1         # that commit's file diffs
moda registry show working         # changes since the last push
```

The dashboard **Registry** page shows the same history, git-style:

* the commit log;
* per-file diffs for any commit, or for a range (shift-click a second commit);
* a file browser for any commit;
* **uncommitted changes**: edits made outside a push, such as dashboard tool edits, MCP discovery, or `moda prompts sync`. Admins can commit them from the page.

## Check what replay will see

```bash theme={"dark"}
moda registry status               # registered harness and its version
moda registry coverage --days=7    # recent production vs the registry
```

`coverage` reports:

* the share of recent LLM calls that resolve to a registered agent;
* agent names and prompt keys seen in traces that no agent claims;
* tools used in production but not registered;
* registered agents never seen.

Every replay's fidelity report also includes a `harness` block. It names the agent that was chosen and why, the prompt version, any unresolved variables, and the handoff tools that were available.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.