Project Layout Reference

Purpose and Scope

eve treats the filesystem as the authoring interface for an agent project. Instead of registering every capability in a central manifest, you place files under conventional directories and let eve discover them. The practical result is that a reviewer can open an agent/ directory and understand the agent’s instructions, runtime configuration, tools, connections, channels, schedules, skills, hooks, sandbox-related code, and subagents from the tree itself. This reference is for developers deciding where a new file belongs, how a capability receives its identity, and how root agents differ from local subagents.

Sources: docs/reference/project-layout.md

The most important rule is that identity is path-derived. A tool file at agent/tools/get_weather.ts resolves to the tool named get_weather; a connection file at agent/connections/linear.ts resolves to the connection named linear; a skill at agent/skills/summarize.md resolves to the skill named summarize; and a local subagent directory such as agent/subagents/researcher/agent.ts resolves to the subagent named researcher. Because the path is the source of identity, authored definitions should not add a separate name or id field to define* calls.

The root agent name is also derived rather than manually repeated in agent code. eve uses the enclosing package.json name when it is available, and falls back to the app-root directory name when that package metadata does not provide a name. Local subagents use their directory name. This keeps project moves, reviews, and generated scaffolds predictable: naming lives at the package or path boundary, while implementation files focus on behavior, configuration, prompts, and integration details.

Relevant Source Files

• docs/reference/project-layout.md — Defines the first-party project layout reference, including the filesystem walking model, path-derived naming rule, recommended my-agent/ tree, eval placement, and the visible slot table entries for agent configuration, instructions, instrumentation, channels, connections, and hooks.

Canonical Root Layout

A conventional eve project has a package root containing ordinary JavaScript or TypeScript project files plus a dedicated agent/ directory. The reference layout shows package.json and tsconfig.json at the root, agent/ as the home for the agent’s authored runtime slots, and evals/ as a sibling directory. Keeping evals/ outside agent/ matters because evals validate behavior rather than becoming model-visible or runtime-loaded agent capabilities. Put test and measurement material in evals/; put the agent’s operational surface in agent/.

my-agent/
├── package.json
├── tsconfig.json
├── agent/
│   ├── agent.ts
│   ├── instructions.md
│   ├── instrumentation.ts
│   ├── channels/
│   ├── connections/
│   ├── hooks/
│   ├── skills/
│   ├── lib/
│   ├── sandbox/
│   ├── tools/
│   ├── schedules/
│   └── subagents/
└── evals/

Sources: docs/reference/project-layout.md

Inside agent/, top-level files and directories are “authored slots.” A slot is a conventional location with a specific meaning to eve’s loader. For example, agent.ts is the runtime configuration slot, instructions.md or instructions.ts is the base system prompt slot, and directories such as tools/, skills/, connections/, and channels/ group related capabilities. The layout also includes lib/ for local support code, sandbox/ for sandbox-related project files, schedules/ for recurring work, and subagents/ for delegated local agents.

Framework applications should preserve this same mental model even when the surrounding app has its own router, components, or build configuration. The canonical agent surface still lives under agent/, while the framework’s application files remain outside that directory. That separation helps keep frontend integration concerns from being confused with agent authoring concerns: the framework app serves or proxies user traffic, while eve discovers the backend agent’s slots from the filesystem conventions documented here.

Naming and Identity Rules

The path-derived naming rule is intentionally stricter than many plugin systems. When adding a tool, connection, skill, or subagent, choose the file or directory path as the public identity first, then write the implementation around that identity. This makes renames meaningful: moving agent/tools/get_weather.ts changes the tool identity to match the new filename. It also avoids drift between filenames, exported objects, and model-visible names, which is especially important in agent projects where prompts, approvals, logs, and evals often refer to capabilities by name.

Sources: docs/reference/project-layout.md

This rule also explains why local subagents are directory-oriented. A subagent is not identified by a field inside its agent.ts; it is identified by its directory under agent/subagents/. The subagent may then author its own local slots inside that directory. The project-layout reference states that a declared subagent inherits nothing from the root and discovers its own slots. Treat a subagent as a smaller agent with its own local filesystem boundary, not as a partial overlay on the root agent.

Slot Reference

The visible slot table establishes which conventional paths have special meaning and whether local subagents can author them. agent.ts is runtime configuration and can appear for subagents. It is where model, model options, compaction, build, and experimental runtime configuration belong. instructions.md, instructions.ts, or an instructions/ directory defines the base system prompt. Static instruction sources compose at build time, while dynamic sources using defineDynamic with defineInstructions resolve at runtime. Root instructions are required; subagent instructions are optional.

instrumentation.ts is the telemetry slot. The reference describes it as root-only, auto-discovered, and run before agent code. Use it for OpenTelemetry exporter configuration and AI SDK span settings, not for model behavior or tool implementation. channels/ is also root-only in the visible table and represents HTTP or messaging entrypoints. That distinction matters because channels are how external conversations enter the root deployment, while delegated subagent behavior is reached through subagent mechanics rather than by independently declaring root-level channels inside a local subagent.

connections/ is the slot for external service connections, including MCP and OpenAPI integrations. It can be authored by local subagents, and the reference states that each connection is one file with its name derived from the filename. This is different from local tools: a connection represents an external system integration that can expose capabilities from a service boundary or API definition, while a tool is project code placed under the tool slot. Keep connection files named after the external service or integration identity you want the agent to reference.

The recommended tree also includes tools/, skills/, schedules/, sandbox/, hooks/, and lib/. Use tools/ for typed functions the model can call, skills/ for reusable procedures or knowledge loaded as skills, and schedules/ for recurring agent work. Use lib/ for internal helper modules that support those authored slots without becoming first-class capabilities themselves. The visible evidence identifies hooks/ as a slot path, and the broader tree reserves sandbox/ for sandbox-related project structure; place files there when following sandbox-specific guidance.

Sources: docs/reference/project-layout.md

Practical Authoring Flow

When adding a capability, start by deciding whether it is root infrastructure, local behavior, or delegated behavior. Root infrastructure belongs directly under agent/: runtime settings in agent.ts, the always-on prompt in instructions.md or the instructions slot, telemetry in instrumentation.ts, and incoming message surfaces in channels/. Local behavior usually belongs in a capability directory such as tools/, skills/, connections/, or schedules/. Delegated behavior belongs under subagents/<id>/, where the directory name becomes the subagent identity and the subagent discovers its own local slots.

Next, choose a path that you are comfortable exposing as the identity. If the model, logs, approvals, or evals should refer to a weather tool as get_weather, put the implementation at agent/tools/get_weather.ts. If a Linear integration should be linear, put it at agent/connections/linear.ts. If a reusable summarization skill should be summarize, use agent/skills/summarize.md. Avoid duplicating those identities inside definitions; the reference explicitly says not to write a separate name or id field on define* calls.

Finally, keep validation assets and framework code outside the authored agent slots unless they are part of the agent itself. Evals belong in the root-level evals/ directory, next to agent/, so they can test the agent without being loaded as capabilities. Frontend or framework files can live elsewhere in the app root according to the framework’s conventions, while agent/ remains the stable backend agent boundary. For deeper implementation work, read the related pages for agent config, instructions, tools and approvals, skills, subagents, schedules, connections, channels, sandbox, hooks, and evals.