eve-doctor

Deterministic health checks for projects built with eve, the filesystem-first framework for durable AI agents.

[!NOTE] This is an independent, early-stage project and is not affiliated with Vercel or the eve maintainers.

Quick start

npx eve-doctor@latest

Or scan another directory:

npx eve-doctor@latest ../my-agent --verbose

The command discovers nested agent/ projects and eve's supported flat layout, runs deterministic checks, and returns a 0–100 health score. It makes no model calls and sends no source code anywhere.

Current checks

| Area | Checks | | --- | --- | | Structure | eve dependency, agent layout, root instructions, conflicting instruction sources, eval placement, subagent layout | | Security | placeholder authentication, likely hardcoded credentials | | Reliability | explicit approval for likely side-effecting tools | | Quality | useful root instructions, discoverable tool exports and descriptions, schedule shape |

Heuristic checks are warnings unless there is strong evidence of an unsafe configuration. Rules should optimize for low false-positive rates.

CLI

eve-doctor [directory] [options]

--json       machine-readable report
--score      numeric score only
--verbose    include suggested fixes
--help       usage
--version    version

The process exits with status 1 when an error-level finding exists and 2 for invalid CLI usage.

Node API

import { scanProject } from "eve-doctor";

const report = await scanProject("./my-agent");
console.log(report.score, report.findings);

Development

npm install
npm test
npm run typecheck
npm run build
node dist/cli.js test/fixtures/healthy --verbose

The initial rules follow eve's documented project layout and security guidance. Because eve is in beta, every rule should remain tied to a public framework contract and be updated as that contract changes.