Contributing to eve

June 22, 2026 · View on GitHub

Thanks for your interest in contributing! This guide covers everything you need to get the repo running locally and land a change.

Signed commits

This repository requires verified commit signatures on protected branches.

Before contributing, configure Git to sign your commits with a GitHub-verified GPG, SSH, or S/MIME key. Unsigned commits will be rejected by repository rules and need to be rewritten as signed commits before they can be merged.

If a pull request includes unsigned commits, re-sign the commits and force-push the branch. Make sure the signing key is added to your GitHub account and that your commits appear as Verified.

A Signed-off-by line in the commit message is not enough to satisfy this requirement. A verified commit signature alone does not satisfy the DCO either; commits need both.

Prerequisites

Node.js 24+ — see .nvmrc (nvm use or fnm use)
pnpm — the version pinned in package.json (corepack enable handles this automatically)

Getting started

git clone https://github.com/vercel/eve.git
cd eve
pnpm install
pnpm build

The repo is a pnpm workspace orchestrated with Turborepo:

packages/eve — the framework and eve CLI
packages/eve-scaffold / packages/eve-catalog — internal (unpublished) scaffolding libraries
apps/fixtures — shared agent fixtures used by e2e tests, TUI smoke tests, local dev, and bundle analysis
apps/frameworks — framework integration apps for Next.js, Nuxt, and SvelteKit
apps/templates — source apps for generated templates
docs — the published documentation content
e2e/ — fixture-owned eve eval end-to-end tests

Development

pnpm dev

This runs the eve package build in watch mode alongside the apps/fixtures/weather-agent fixture on an OS-assigned available localhost port. The fixture prints the selected URL at startup.

Testing

pnpm test               # unit + integration
pnpm test:unit          # unit tests
pnpm test:integration   # integration tests
pnpm test:scenario      # scenario tests (requires pnpm build first)
pnpm test:e2e           # fixture-owned eve eval suites
pnpm test:tui           # TUI smoke scripts (not e2e)

E2E tests are fixture-owned evals. Run them from the fixture directory:

cd e2e/fixtures/agent-basic-runtime
pnpm exec eve eval --strict

The fixture agents and judges run against real models (openai/gpt-5.5), so the environment must provide the corresponding model-provider credentials.

Vercel e2e builds that same fixture directory with VERCEL=1, deploys the fixture's prebuilt Vercel output, and runs evals against the immutable deployment URL. All fixture deployments link to the same Vercel project id; the shared project's Preview env must provide those same model-provider credentials.

Do not commit fixture trees under packages/eve/test/fixtures/ — scenario app content is defined inline as ScenarioAppDescriptor objects under packages/eve/src/internal/testing/scenario-apps/ (CI enforces this).

Linting and formatting

pnpm lint          # oxlint (auto-fixes)
pnpm fmt           # oxfmt (also runs on staged files via the pre-commit hook)
pnpm typecheck     # TypeScript across the workspace
pnpm check:deps    # syncpack — dependency versions must stay in sync
pnpm guard:invariants  # mechanical code-invariant lints (run in CI)
pnpm docs:check    # docs frontmatter and nav validation

All of these run in CI, so running them locally before pushing saves a round trip.

Documentation

User-facing docs live in docs/ and are published with the eve npm package and rendered by the docs site in apps/docs. If your change alters public behavior, update the relevant doc in the same PR and run pnpm docs:check.

Before opening a pull request

Every pull request must be tied to an issue. Before opening a PR, search the existing issues, discussions, and pull requests so you do not duplicate active work. If there is no existing issue, open one with the relevant template and describe the problem, use case, or bug reproduction.

For changes to public APIs, agent behavior, compiler/runtime internals, dependencies, generated artifacts, fixture contracts, or any non-trivial implementation detail, wait for discussion on the issue before investing in the implementation. The goal is to agree that the problem is real and that the proposed direction fits eve before review shifts to code. Bug fixes should link to an issue with a reproduction or failing test case so the problem remains tracked even if a specific fix is not accepted.

To avoid PRs that are unlikely to be reviewed or merged:

Do not send broad rewrites, style-only churn, formatting-only changes, or generated-output refreshes unless a maintainer asked for them.
Do not bundle unrelated fixes or refactors into one PR. Split them so each PR has one reviewable purpose.
Do not add runtime dependencies without prior agreement. Prefer eve-owned wrappers, vendored code, or generated artifacts, and remember that the eve package should keep runtime dependencies minimal.
Do not change public behavior based only on a hypothetical use case. Include a concrete user story, reproduction, fixture, or test that shows the need.
Do not claim an issue silently. Comment before starting work, and check the thread first in case someone else is already working on it.

Submitting a pull request

Fork the repo and create a branch from main.
Link the issue where the change was discussed and agreed on.
Make your change, including tests and docs where relevant.
Sign off every commit with git commit -s.
If the change affects the published eve package, add a changeset:
```
pnpm changeset
```
Make sure pnpm lint, pnpm typecheck, and pnpm test pass.
Open the PR with a clear description of the problem and solution.

Releases are managed with Changesets by the maintainers.

Developer Certificate of Origin (DCO)

We do not require a CLA. Instead, all contributions are made under the Developer Certificate of Origin (DCO), a lightweight, one-line attestation that you have the right to submit your contribution under the project's license. There is nothing to sign and no account to create.

Every commit must include a Signed-off-by line matching the commit author's name and email:

Signed-off-by: Jane Doe <jane.doe@example.com>

Add it automatically with:

git commit -s -m "your commit message"

If you forget, amend the last commit:

git commit --amend -s --no-edit

To sign off a series of commits, rebase with --signoff:

git rebase --signoff main

The sign-off requirement applies to all contributors, including Vercel employees. A required check blocks pull requests that contain commits without a valid sign-off.