Migrate an Existing Eve Agent

Follow this guide to migrate an Eve agent project to flue-eve. The process is mostly automated when your project follows standard Eve conventions.

1. Scan the project

Run the migration scanner to understand what needs to change:

npx flue-eve scan

This produces a tiered report. Most Eve chat agents fall into Tier 0/1 (zero-touch or auto-scaffold). For CI enforcement, use --strict:

npx flue-eve scan --strict

See migration tiers for what each tier means.

npx flue-eve init

This creates or updates:

File	Purpose
`src/agents/{name}.ts`	Flue agent with instructions + tools
`src/flue-eve-shim.ts`	Eve compat sidecar — mounts `/eve/v1/*`
`src/app.ts`	Flue Hono app (auto-injected with `mountEveCompat`)
`src/tools/*.ts`	Tool adapters from `agent/tools/*.ts`
`src/connections/*.ts`	Connection adapters from `agent/connections/*.ts`
`eve.config.ts`	Plugin config (if needed)

Safe to re-run — existing files are not overwritten unless --force is passed.

npx flue-eve init --agent-name support --model openai/gpt-4o

The Vite plugin auto-aliases eve/client → flue-eve/client and eve/react → flue-eve/react. No import changes are needed for browser code.

For server code, replace Eve server imports:

- import { createEveServer } from 'eve/server';
+ import { eveCompat } from '@flue-eve/compat-server';

pnpm dev

With mock admission (default), the agent returns deterministic responses without needing an LLM key:

curl -X POST http://localhost:5173/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Hello"}'

To test with a real LLM, start flue dev and set FLUE_BASE_URL:

FLUE_BASE_URL=http://127.0.0.1:3583 pnpm dev

curl http://localhost:5173/eve/v1/health
# { "ok": true, "status": "ready" }

Run the test suite:

vp test

Tier	What it covers	Effort
0	`useEveAgent`, `eve/client` browser imports	Zero-touch
1	`instructions.md`, `tools/*.ts`, `eve.config.ts`	Auto-scaffold
2	Custom tool patterns, non-standard layout	Manual review
3	Workflow SDK, channels, schedules	Blocked — see alternatives

A skills.sh-compatible skill is bundled in the repo. Install it and ask your AI coding agent to handle the migration:

npx skills add doeixd/flue-eve

Then ask:

"Migrate this Eve project to flue-eve"

The agent will scan, scaffold, configure the Vite plugin, connect the frontend, and verify the setup.

See deployment for production configuration.