eve: A Filesystem-First Framework for Durable AI Agents

What eve Actually Solves

eve addresses a specific pain: the opacity of AI agent frameworks. Most agent tooling hides prompts, tool definitions, and scheduling logic inside code or a database, which makes inspection and modification awkward. eve flips that by making the filesystem the authoring interface. Every capability has a conventional location, so a new contributor can open a project and see the agent's system prompt in instructions.md, its tools in tools/, and its recurring jobs in schedules/. The README frames this as making projects easier to inspect, extend, and operate. That is a real answer to a real problem, not a marketing line. For teams that need to audit what an agent does or hand it to a new engineer, the layout is a genuine advantage.

The Filesystem Layout and Its Conventions

The core structure is an agent/ directory with six possible components. agent.ts is optional and holds model and runtime configuration. instructions.md is required and acts as the always-on system prompt. tools/ contains typed functions the model can call, each defined with defineTool. skills/ holds procedures loaded on demand, written as markdown. channels/ handles message channels like HTTP, Slack, or Discord. schedules/ defines recurring cron jobs. This is a strong convention: the framework decides where things go, so you do not have to invent a structure. But it also means you must follow the layout exactly. If you put a tool outside tools/, eve will not find it. That is a constraint, but a clear one. The README notes that the full documentation ships inside node_modules/eve/docs, so coding agents can read it locally. That detail matters for teams that want to let an LLM edit its own agent definition, since the reference material is right there in the dependency tree.

Getting Started: Commands and a Minimal Agent

The quick start is a single command: npx eve@latest init my-agent. This creates a new directory, installs dependencies, initializes Git, and starts an interactive terminal UI. You can pass a model ID directly, like npx eve@latest init my-agent --model openai/gpt-5.6-terra, or add eve to an existing project with npx eve@latest init . from inside that project. The minimal example shows three files. instructions.md contains a plain sentence telling the agent to be a concise weather demo assistant. tools/get_weather.ts imports defineTool from eve/tools and zod, then exports a tool with a description, an inputSchema, and an async execute function that returns mocked weather data. agent/agent.ts imports defineAgent from eve and sets the model. After that, npm run dev starts the agent. Nothing here is exotic; it is standard TypeScript with a thin wrapper. That is the point: the framework stays out of the way until you need its conventions.

How Tools and Model Configuration Work

The tool definition is explicit and typed. defineTool takes an object with a description, an inputSchema built with zod, and an execute function. The description is what the model sees when deciding whether to call the tool, so it has to be precise. The inputSchema validates arguments before execution, which catches malformed calls. The execute function returns a plain object that the model can reason about. Model selection happens in agent.ts via defineAgent, with a model string like openai/gpt-5.6-luna-fast. The README mentions an AI Gateway, which suggests that model IDs are resolved through a gateway rather than directly to a provider. That is useful for teams that want to switch models without rewriting agent code, but the README does not explain how the gateway is configured. You would have to read the full docs in node_modules/eve/docs to learn that, which is a gap in the public material.

Durability and Human-in-the-Loop Features

The description calls eve a framework for durable AI agents. Durability here means the agent can persist state and resume across sessions, though the README does not detail the persistence mechanism. It mentions human-in-the-loop prompts, subagents, and schedules as features you can add. Human-in-the-loop is a significant capability for production agents, because it lets a person approve or reject actions before the agent executes them. The README does not show how to define such a prompt, so the mechanism is unclear from this material. Schedules are clearer: they are cron jobs defined as files in schedules/, which means recurring tasks are versioned alongside the rest of the agent. That is a practical design. But durability is the weakest documented area. The README states the framework is filesystem-first, but it does not say where state is written, how it survives a restart, or what happens if the filesystem is read-only. Those are questions you must answer before trusting it with long-running tasks.

Limitations and Wrong Tool Cases

The most obvious limitation is the beta status. The README says eve is subject to Vercel beta terms, and the framework, APIs, documentation, and behavior may change before general availability. That means code you write today might break on the next minor release. For a production system, that is a serious risk. The filesystem-first model also assumes you have a writable filesystem. In serverless or containerized environments where the filesystem is ephemeral or read-only, the agent's conventional locations may not persist. The README does not address this scenario. Another limitation is the requirement for an AI Gateway. The quick start assumes you have access to a gateway that resolves model IDs like openai/gpt-5.6-terra. If you do not, the init command may fail or require extra configuration that is not documented in the README. Also, the framework is TypeScript-only. If your team works in Python or another language, eve is not an option.

Alternatives and How They Differ

The main alternative is LangChain, which takes a code-first approach. In LangChain, you compose agents by writing Python or JavaScript code that chains calls to models, tools, and memory. There is no required directory structure; you decide where prompts and tool definitions live. That gives more flexibility but less convention. eve's filesystem-first model is the opposite: it imposes a structure so that any eve project looks familiar. LangChain also has a larger ecosystem of integrations and a longer history, which may matter if you need connectors to specific vector stores or external APIs. Another alternative is a plain script that calls an LLM API directly, with no framework at all. That gives you total control but no built-in tool schema validation, scheduling, or channel support. eve sits in between: it provides structure and durability primitives, but you trade that for the beta risk and the need to follow its layout.

Maintenance and License Considerations

The license is Apache-2.0, which is permissive and allows commercial use, modification, and distribution, provided you preserve copyright notices. That is a low-friction license for most organizations. The maintenance picture is mixed. The repository shows active development, with release eve@0.47.3 pushed on the same day as the review material, and a separate package @eve/self-modification at version 0.0.3. The self-modification package is notable because it suggests the framework can edit its own code, which is a strong durability feature but also a risk if not sandboxed. The version number 0.0.3 indicates early stage. The project is not archived, and the last push is recent, so it is under active maintenance. But the beta terms mean you cannot assume backward compatibility. Upgrading eve will likely require checking the changelog and adjusting your agent files. That is an ongoing cost you should budget for.

Editorial conclusion

Adopt eve if you want an agent framework where the entire configuration and logic live in plain files that you can inspect, version, and extend without a proprietary control plane. Skip it if you need a stable API for production systems, because the beta terms allow breaking changes before general availability. Before committing, verify that the model IDs you rely on (such as openai/gpt-5.6-terra) are supported by your AI Gateway and that the filesystem layout fits your deployment pipeline, especially if you expect to run agents in containers where file writes are ephemeral.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes