> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

# How to Migrate Using AI

HyperIndex includes built-in Claude skills that show AI programming assistants how to write HyperIndex config, schema, handlers, and tests. Give your assistant the prompt below and it scaffolds a HyperIndex indexer from your existing indexer, matches the config, and ports your logic. This is the recommended way to migrate complex indexers.

## Step 1: Create an Envio API Token

Create an API token at [envio.dev/app/api-tokens](https://envio.dev/app/api-tokens) and set it in the shell you start your AI programming assistant from (or in your shell profile):

```bash
export ENVIO_API_TOKEN=<your-token>
```

`envio init` reads the token from this environment variable and saves it in your new indexer's `.env`, so you never need to paste it into the prompt. If you skip this step, your assistant asks you to add the token to the new indexer's `.env` after scaffolding it. See [About Envio API Token](https://docs.envio.dev/docs/HyperIndex/quickstart-with-ai.md#about-envio-api-token) for details.

## Step 2: Run Your AI Programming Assistant

Open your AI programming assistant (for example Claude Code or Cursor) in a new, empty directory. **Put your assistant in plan mode first**, then paste the following prompt. Replace `<EXISTING_INDEXER>` with the local path or git URL of the indexer you want to migrate:

```xml
<context>
Migrate my existing indexer at <EXISTING_INDEXER> (a local path or git URL)
to Envio HyperIndex. The existing indexer is the source of truth. Create the
HyperIndex indexer in `hyperindex-indexer/` (migration target).
</context>

<task>
Follow these phases in order:

Phase 0: Scaffold the boilerplate
- If <EXISTING_INDEXER> is a git URL, clone it into `existing-indexer/`.
- Pick one contract on one chain from the existing indexer's config (for
  example `subgraph.yaml` or `ponder.config.ts`) and scaffold it
  non-interactively:

    npx envio init -d hyperindex-indexer --package-manager npm \
      contract-import -c <CONTRACT_ADDRESS> \
      local -a <path/to/Contract.json> --contract-name <ContractName> \
      -b <CHAIN_ID> --single-contract --all-events

  If the ABI is not in a JSON file, save it as one first. If HyperSync
  doesn't support the chain, also pass `-r <RPC_URL> -s <START_BLOCK>`.
  `envio init` reads `ENVIO_API_TOKEN` from the environment, so don't pass
  my token in `--api-token`. If it fails because no token is set, rerun it
  with `--api-token ""`, and once the boilerplate is set up, ask me to add my
  token to `ENVIO_API_TOKEN` in `hyperindex-indexer/.env`.
- Update `hyperindex-indexer/config.yaml` to match the existing indexer: every
  contract, chain, address, start block, and event. Contracts created at
  runtime (subgraph `templates`, Ponder factories) become contracts without
  an `address`.
- Run `npx envio codegen` in `hyperindex-indexer/` and fix any errors.

Phase 1: Plan
- Read every `SKILL.md` under `hyperindex-indexer/.claude/skills/`. They
  describe HyperIndex config, schema, handlers and tests.
- Produce a migration plan mapping each component of the existing indexer to
  its HyperIndex equivalent.
- Flag anything that has no direct equivalent and propose a workaround.
- Do NOT write handler code yet.

Phase 2: Implement
- Migrate the entire indexer following the plan and skill guides.
- Process one handler file at a time.
- After each file, run `npx envio codegen` and `npx tsc --noEmit` in
  `hyperindex-indexer/` to validate, and verify it against the migration plan
  before moving on.

Phase 3: Verify
- Walk through every item in the migration plan and confirm it is
  implemented.
- Run `npx tsc --noEmit` and `npm test` in `hyperindex-indexer/` and fix any
  errors.
- List any items you could not complete and why.
</task>

<rules>
- Only create or modify files in `hyperindex-indexer/`. Do not change the
  existing indexer.
- Preserve all contracts, chains, entity fields, and event mappings from the
  existing indexer.
- Do not skip or summarize plan items. Execute every one.
- If you are uncertain about a migration decision, pause and ask me.
</rules>
```

:::tip
- After migration, run `npm run dev` in `hyperindex-indexer/` to verify the indexer runs correctly
- If you migrated a subgraph, use the [Indexer Migration Validator](https://github.com/enviodev/indexer-migration-validator) to compare outputs between your subgraph and the new HyperIndex indexer
:::

## Manual Migration

For step by step manual guides, see [Migrate from The Graph](https://docs.envio.dev/docs/HyperIndex/migration-guide.md) and [Migrate from Ponder](https://docs.envio.dev/docs/HyperIndex/migrate-from-ponder.md).