README

eve








eve is a filesystem-first framework for durable AI agents. Core agent capabilities live in
conventional locations, so projects are easier to inspect, extend, and operate.

 The filesystem is the authoring interface

A typical eve agent has this structure:

text
my-agent/
└── agent/
    ├── agent.ts             Optional: model and runtime config
    ├── instructions.md      Required: the always-on system prompt
    ├── tools/               Optional: typed functions the model can call
    │   └── get_weather.ts
    ├── skills/              Optional: procedures loaded on demand
    │   └── plan_a_trip.md
    ├── channels/            Optional: message channels (HTTP, Slack, Discord)
    │   └── slack.ts
    └── schedules/           Optional: recurring cron jobs
        └── weekly_recap.ts


Read the documentation for the full project layout and guides.

 Quick start

bash
npx eve@latest init my-agent


This creates a new my-agent directory, installs its dependencies, initializes Git, and starts
the interactive terminal UI. The generated agent uses openai/gpt-6-luna-fast with high reasoning.

To start with another AI Gateway model, pass its model ID:

bash
npx eve@latest init my-agent --model openai/gpt-5.6-terra


Passing --model without --reasoning uses the provider's default reasoning. Pass --reasoning to set it explicitly.

To add eve to an existing project, pass a path:

bash
cd myapp
npx eve@latest init .


 [!NOTE]
 The eve package includes its full documentation, so coding agents can read it locally from
 node_modules/eve/docs.

 A minimal example

The generated project includes an agent directory. Replace agent/instructions.md with:

md
You are a concise weather demo assistant. Tell users that the weather data is mocked.


Add a mock weather tool at agent/tools/get_weather.ts:

ts
import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Return mock weather data for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});


Choose the model in agent/agent.ts:

ts
import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-6-luna-fast",
  reasoning: "high",
});


For a new scaffold, start the agent again:

bash
npm run dev


That's a working agent. Add human-in-the-loop prompts, subagents, and schedules as needed.

 Add Web Chat

From your agent's directory, link a Vercel project and add Web Chat:

bash
npx eve link
npx eve add channel/web


Choose a hosting layout, then Sign in with Vercel to provision authentication for members of the project's team.
You can also select Web Chat from the terminal UI's /add channel picker.
Run npx eve deploy when ready to publish. Local development works without browser sign-in.
See the Web Chat setup guide for permissions and recovery.

 Community

The eve community lives on GitHub Discussions,
where you can ask questi