# Add hashspan with a coding agent

> Let Claude Code, Cursor or GitHub Copilot add hashspan to your project: install the agent skill, paste one prompt, and keep a short rules snippet.

Source: https://hashspan.dev/docs/build-with-ai

Your coding agent can add hashspan in one pass. Install the hashspan skill, paste the prompt below, and the agent wires up the send and confirm spans for you.

- **Skill:** `npx skills add https://hashspan.dev` puts the step-by-step instructions in your project.
- **Prompt:** one copy-paste prompt points the agent at the skill and the span names.
- **Rules:** a short snippet in your agent's rules file stops it from inventing attributes later.

## How do I install the hashspan skill?

Run this in your project root:

```sh
npx skills add https://hashspan.dev
```

It offers three skills: `hashspan`, the setup steps this page is about, and two that only read, `explain-evm-error` and `otel-attribute-names`. Add `--skill hashspan` to take only the setup. The same skill also installs from its repository with `npx skills add selimaytac/hashspan`. [Agent skills](https://hashspan.dev/agents) has every skill with a ready prompt.

The installer asks which agents to set up. For Cursor and GitHub Copilot it writes the skill to `.agents/skills/hashspan/SKILL.md`. For Claude Code it goes in `.claude/skills/hashspan`, as a link to that folder when you pick several agents. Commit the folder, so everyone on the project gets the same steps.

The [skill file](https://github.com/selimaytac/hashspan/blob/main/skills/hashspan/SKILL.md) is plain Markdown. It walks the agent through six steps: find how the project sends, install, start the OpenTelemetry SDK first, extend every client, flush before exit, and check the traces. The hashspan repository's CI applies it to minimal versions of two of its examples, the AI SDK agent and the payout worker, and checks their spans on a local chain.

Your agent doesn't read skills? Point it at the file's URL instead. The prompt below works either way.

## What prompt should I give the agent?

Paste this into Claude Code, Cursor, Copilot or any agent that can edit files and run commands:

```text wrap
Add hashspan to this project so every on-chain transaction it sends shows up as OpenTelemetry spans.

1. Follow the hashspan skill (in .agents/skills/hashspan/ or .claude/skills/hashspan/, or https://github.com/selimaytac/hashspan/blob/main/skills/hashspan/SKILL.md) step by step.
2. Use the hashspan adapter for each send path: @hashspan/viem for viem clients, @hashspan/cdp for the Coinbase CDP SDK, @hashspan/x402 for x402 payments, @hashspan/mpp for MPP payments made with mppx.
3. Take span and attribute names only from https://hashspan.dev/docs/reference/semantic-conventions.md. Don't hand-create send, confirm or payment spans or blockchain.* attributes: hashspan records them.
4. If the project sends through another library, such as ethers, or on a chain that is not EVM, stop and tell me.
5. Run it only against a local chain with Anvil's test accounts, or a testnet I name. Ask me before anything signs. Don't read .env files, key files or secrets. Then run the typecheck and tests.
```

When it's done, each transaction shows `send {chainId}` and `confirm {chainId}` spans under the span that was active when it was sent. An x402 payment shows `payment {chainId}` and, with a reader, `confirm {chainId}`. An MPP payment shows `payment {chainId}` and, with a reader, a linked `confirm {chainId}`.

## What should go in my agent's rules file?

A one-off prompt is forgotten in the next session. A rules file isn't. Add this to the file your agent reads on every task:

```md wrap title="AGENTS.md"
## Tracing on-chain transactions (hashspan)
- Transactions are traced with hashspan. Before you add or rename a span attribute, read https://hashspan.dev/docs/reference/semantic-conventions.md.
- hashspan records the `send`, `confirm` and `payment` spans, and `traceTransport()` adds one span per JSON-RPC request. Don't hand-create spans with these names or `blockchain.*` attributes.
- New viem clients get `.extend(hashspan)`, after other extensions. Smart account SDKs are the exception: build the client with `withHashspan()` before the SDK's actions (step 4 of https://github.com/selimaytac/hashspan/blob/main/skills/hashspan/SKILL.md). A user operation that an SDK or a hosted wallet sent and returned only a hash for is confirmed with `watchUserOperation()`, not `watch()`. CDP and x402 clients are wrapped with @hashspan/cdp and @hashspan/x402 right after they are created, and an mppx client with @hashspan/mpp's `withHashspan(mppx, { reader })` right after `Mppx.create()`.
- Run only against a local chain with Anvil's test accounts, or a testnet the user names. Ask before anything signs. Never read `.env` files, key files or secrets.
```

Where that file lives depends on the agent:

| Agent | Rules file |
|---|---|
| Claude Code | `CLAUDE.md`, or `AGENTS.md` when there is no `CLAUDE.md` (v2.1.277 or later) |
| Cursor | `AGENTS.md`, or a `.mdc` file in `.cursor/rules` |
| Copilot coding agent, CLI, VS Code chat | `AGENTS.md` or `.github/copilot-instructions.md` |
| Other Copilot chats (GitHub.com, Visual Studio, JetBrains, Eclipse, Xcode) | `.github/copilot-instructions.md` only |

One `AGENTS.md` covers Claude Code, Cursor and the Copilot agents. For the other Copilot chats, put the snippet in `.github/copilot-instructions.md` too. If you also keep a `CLAUDE.md`, Claude Code reads only that, so import `AGENTS.md` from it.

## Where are the machine-readable docs?

Every page on this site has a Markdown twin for agents and LLM tools:

| What | URL |
|---|---|
| Index of every page | [`/llms.txt`](https://hashspan.dev/llms.txt) |
| All docs in one file | [`/llms-full.txt`](https://hashspan.dev/llms-full.txt) |
| One page as Markdown | page URL + `.md`, e.g. [`/docs/quickstart.md`](https://hashspan.dev/docs/quickstart.md) |
| Span and attribute names | [`/docs/reference/semantic-conventions.md`](https://hashspan.dev/docs/reference/semantic-conventions.md) |
| Docs over the Context7 MCP server | library ID [`/selimaytac/hashspan`](https://context7.com/selimaytac/hashspan) |

Each HTML page also points to its Markdown version with `<link rel="alternate" type="text/markdown">`. Give the agent the `.md` URL, not the HTML page: it's smaller and has no navigation.

## FAQ

### Do I need the skill, or is the prompt enough?

The prompt alone works if the agent can fetch URLs: it links the skill file. Installing the skill keeps the steps in your repository, next to your code. Agents that support skills also load it by themselves when a task matches its description.

### Which projects can the agent instrument?

TypeScript projects that send EVM transactions or agent payments through viem, the Coinbase CDP SDK, x402 or MPP (mppx), on Node.js 22.3 or later. That covers agents and plain services such as payout workers. Other libraries, such as ethers, have no adapter, and the skill tells the agent to stop there.

### Why tell the agent not to invent attribute names?

Backends, dashboards and queries match on exact names like blockchain.tx.status. An attribute an agent makes up looks fine in one trace and breaks every query that expects the real one. The semantic conventions reference lists every name hashspan records.

### Can I check the agent's work by hand?

Yes. Compare the setup with the Quickstart, or run the local lab to see what a correct trace looks like. For a viem project, the viem OpenTelemetry page shows the spans each action should produce. When a span is missing, troubleshooting lists the usual causes.

Links from the answers: [semantic conventions](https://hashspan.dev/docs/reference/semantic-conventions), [Quickstart](https://hashspan.dev/docs/quickstart), [x402 tutorial](https://hashspan.dev/docs/x402-tutorial) (the same setup by hand, step by step), [local lab](https://hashspan.dev/docs/local-lab), [viem OpenTelemetry instrumentation](https://hashspan.dev/docs/viem-opentelemetry), [troubleshooting](https://hashspan.dev/docs/troubleshooting).