Overview

eve is a filesystem-first framework for durable backend AI agents. The central idea is that an agent is authored as ordinary files in a TypeScript project, rather than as one large in-memory configuration object. Human-readable behavior lives in Markdown, typed runtime behavior lives in TypeScript, and the directory layout tells eve how to discover the agent's capabilities. That makes an eve project inspectable by people, editable by coding agents, and easier to operate as it grows from a minimal local assistant into a deployed service with channels, tools, schedules, connections, and frontend clients.

Sources: README.md, packages/eve/README.md, docs/introduction.mdx

The public repository and the published package both use the same product name, eve. The package README states that the framework is called eve, the npm package is eve, and the CLI binary is also eve. The package metadata publishes the eve binary from ./bin/eve.js, exposes the main TypeScript API from eve, and includes package files such as dist, docs, the changelog, and the README. In practice, that means the repository is both the source for the framework and the source for the developer-facing package users install to create, run, and integrate agents.

Sources: packages/eve/README.md, packages/eve/package.json

Purpose and Scope

Use this page as the map for the repository and the framework's public surface. It introduces the mental model behind eve, the package and CLI names to look for, and the authored project layout that appears throughout the docs. It is not a deep reference for every API; instead, it explains how the major pieces relate so that the more focused pages make sense. After reading it, a new contributor should know why agent/instructions.md, agent/tools/, agent/channels/, and agent/agent.ts are important, and a new user should know where to start.

eve's first-party docs describe the framework as durable by default. A session can span more than a single request and response: it can stream progress, call tools and subagents, pause for approval or another human answer, resume later, and keep durable state across turns. The introduction says eve uses the open-source Workflow SDK under the hood for resumable, crash-safe sessions, while keeping that machinery out of the application code that defines tools and capabilities. This separation is a recurring design theme: authored files describe capabilities, runtime infrastructure executes durable work, and channels translate external messages into the same agent flow.

Sources: docs/introduction.mdx

Relevant Source Files

• README.md - Repository-level entry point that defines eve as filesystem-first, shows the canonical starter tree, documents npx eve@latest init, and gives a minimal weather-agent example.
• packages/eve/README.md - Package-level overview that names the framework, npm package, and CLI binary; describes preview safeguards; and lists the fuller authored directory contract.
• packages/eve/package.json - Published package metadata for eve, including npm identity, CLI binary, exports such as eve/client, framework integrations, public subpaths, keywords, license, and packaged docs.
• docs/introduction.mdx - First-party introduction that explains the file-as-interface model, the message flow, durable sessions, and how capabilities are added over time.

Core Primitives

The smallest useful eve project starts with the agent/ directory. The required always-on system prompt normally lives in agent/instructions.md; the optional agent/agent.ts file selects the model and configures runtime options. Tools live under agent/tools/ as typed functions the model can call, and skills live under agent/skills/ as longer procedures the model loads when relevant. Channels live under agent/channels/ and connect the same agent behavior to HTTP clients, Slack, Discord, and other places where users interact with the agent.

Sources: README.md, packages/eve/README.md, docs/introduction.mdx

The package README expands that layout into a production-oriented contract. It includes hooks/ for lifecycle and stream-event subscribers, connections/ for external MCP server connections, sandbox/ for the agent's isolated workspace, workspace/ for files seeded into the sandbox on each session, subagents/ for specialist child agents, schedules/ for recurring jobs, and lib/ for shared authored code. This is the practical meaning of filesystem-first: adding a capability usually means adding a file or folder in a predictable place, not editing a central registry.

Sources: packages/eve/README.md

Connections deserve a separate mental slot from local tools and channels. A local tool is authored code in agent/tools/ that the model can call. A channel is message ingress and delivery, such as HTTP or Slack. A connection represents an external system integration, with the docs specifically calling out MCP and OpenAPI services as places where tools can come from. That distinction helps keep application architecture legible: the channel answers where the conversation came from, the tool or connection answers what the agent can do, and the session runtime manages the durable turn.

Sources: docs/introduction.mdx, packages/eve/README.md, packages/eve/package.json

System-to-Code Mapping

The package exports show that eve is more than a runtime-only library. The root export provides the main authoring API, while subpath exports expose the client SDK, frontend bindings, framework integrations, tools, connections, hooks, sandbox helpers, and authorization helpers. This matches the docs spine: author an agent as files, run it through the CLI and runtime, connect it to channels and external systems, and call it from applications using a typed client or frontend integration. The exports are also a useful navigation aid when reading source or writing code against the package.

Sources: packages/eve/package.json

Authoring and Local Development Flow

The repository README presents the quick start as npx eve@latest init my-agent. That command creates a new project directory, installs dependencies, initializes Git, and starts the interactive terminal UI. To add eve to an existing project, the same command accepts a path such as npx eve@latest init .. This flow reflects the framework's bias toward convention: the generated project already contains the agent directory, and the developer can immediately edit files in place instead of assembling a runtime from scratch.

Sources: README.md

npx eve@latest init my-agent
cd my-agent
npm run dev

The minimal example in the repository README is intentionally small but shows the end-to-end shape. Replace agent/instructions.md with a concise system prompt, add agent/tools/get_weather.ts using defineTool from eve/tools and a Zod input schema, and choose a model in agent/agent.ts with defineAgent from eve. At that point the project is a working agent, because eve discovers the files and turns their locations into runtime identity. The example also points to human-in-the-loop prompts, subagents, and schedules as natural next additions rather than separate frameworks.

Sources: README.md

Execution Model at a Glance

When a message arrives, eve normalizes platform input into an agent message, provides the model with instructions, skills, tools, and conversation history, runs the work, saves the session, streams events, and delivers the result back through the platform-specific channel. The docs emphasize that this flow is the same whether the user speaks through a web app, terminal, or Slack. That portability is important for agent authors: a weather tool, warehouse query tool, or analysis skill should not need to know which channel produced the user's question.

Sources: docs/introduction.mdx

Durability changes how developers should think about agent code. A turn may include streaming output, tool calls, subagent delegation, approval pauses, continuations, and later follow-up turns. The package README lists durable message runs, follow-up turns, inspectable compiled artifacts under .eve/, a per-agent sandbox, an explicit HTTP protocol with continuationToken and sessionId, and separation between channels, harnesses, and workflow execution as priorities. Those details explain why eve is structured as a backend agent framework rather than only a prompt helper library.

Sources: packages/eve/README.md

Safety, Preview Status, and Operating Responsibilities

The package README is explicit that eve is in preview and that deployers are responsible for safeguards appropriate to their use case. It calls out approval policies, tool restrictions, connection scopes, route and session authorization, sandbox controls, telemetry exports, and other controls as deployer concerns. It also warns that agents may operate with permissive settings unless stricter controls are configured, including tool execution without human approval when approval is omitted and sandbox network egress that is not deny-all. That warning belongs in the overview because capability discovery and durable execution are powerful by design.

Sources: packages/eve/README.md

As a result, an eve project should be reviewed as both source code and operational policy. Before exposing sensitive data or side-effecting actions, inspect which default tools, custom tools, MCP tools, shell, file, and web tools, connected services, subagents, schedules, and external actions are available. For irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions, the package README recommends human approval or other safeguards. The filesystem layout makes that audit easier because capabilities have named homes.

Sources: packages/eve/README.md

Next Steps

Start with the introduction and getting-started flow if you are learning eve for the first time. Then read the project layout reference to understand naming conventions, and the tools, channels, connections, sandbox, and schedules pages as you add capabilities. If you are integrating an existing app, inspect the exported package subpaths for eve/client and the frontend bindings for React, Vue, Svelte, Next, Nuxt, and SvelteKit. If you are operating an agent in production, prioritize the security model, route protection, approvals, sandbox configuration, and deployment pages before connecting real data or side-effecting services.

Sources: README.md, packages/eve/README.md, packages/eve/package.json, docs/introduction.mdx