# Project layout

> Authored slots under agent/, path-derived naming (no name fields), evals/ placement, subagent inheritance rules, and what compiles into .eve/ artifacts.

- Repository: vercel/eve
- GitHub: https://github.com/vercel/eve
- Human docs: https://www.grok-wiki.com/public/docs/vercel-eve-759e1d74a10f
- Complete Markdown: https://www.grok-wiki.com/public/docs/vercel-eve-759e1d74a10f/llms-full.txt

## Source Files

- `docs/reference/project-layout.md`
- `packages/eve/src/compiler/manifest.ts`
- `packages/eve/src/compiler/normalize-manifest.ts`
- `packages/eve/src/compiler/artifacts.ts`
- `packages/eve/src/cli/commands/info.ts`

---

---
title: "Project layout"
description: "Authored slots under agent/, path-derived naming (no name fields), evals/ placement, subagent inheritance rules, and what compiles into .eve/ artifacts."
---

Eve compiles an agent by walking the filesystem under `agent/`. Each top-level directory or file is an authored slot; the slot a file lands in determines how discovery loads it, and the compiler normalizes the result into versioned artifacts under `.eve/`. Run `eve info` or `eve build` to inspect what was discovered and where artifacts were written.

## App root and agent root

Discovery resolves two roots from your working directory:

| Root | Role |
| --- | --- |
| **App root** | The enclosing project directory (marked by `package.json` or `vercel.json`) |
| **Agent root** | The directory Eve walks for authored slots |

Eve supports two layouts:

| Layout | Agent root | App root | When to use |
| --- | --- | --- | --- |
| **Nested** (recommended) | `<app-root>/agent/` | Parent of `agent/` | Keeps app scaffolding separate from the authored surface |
| **Flat** | Same as app root | Same directory | Supported when the app root is also the agent root |

Nested layout is detected when the app root contains an `agent/` directory. Flat layout is detected when the current directory contains recognized agent-root entries (`agent.ts`, `instructions.md`, `tools/`, and similar) without a separate `agent/` folder.

<Note>
`eve info` reports `layout` as `nested` or `flat`, plus resolved `appRoot` and `agentRoot` paths.
</Note>

## Path-derived naming

Identity comes from the path. Authored `define*` exports do not carry `name` or `id` fields — the compiler derives identifiers from filenames and directory names.

| Authored path | Runtime identifier |
| --- | --- |
| `agent/tools/get_weather.ts` | tool `get_weather` |
| `agent/tools/billing/refund.ts` | tool `billing-refund` (nested segments flattened with `-`) |
| `agent/connections/linear.ts` | connection `linear` |
| `agent/skills/summarize.md` | skill `summarize` |
| `agent/subagents/researcher/agent.ts` | subagent tool `researcher` |
| `agent/subagents/linear.ts` (with `defineRemoteAgent`) | remote subagent tool `linear` |

**Root agent name** comes from `package.json` `name` (npm scope stripped), falling back to the app-root directory basename when `name` is absent.

**Local subagent name** comes from the directory name (`subagents/<id>/`) or the module basename for single-file subagents (`subagents/<id>.ts`).

Subagent tool names share the same runtime namespace as authored tools. A subagent named `researcher` collides with a tool named `researcher`; Eve rejects the build rather than picking a winner.

## Recommended layout

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

`evals/` lives at the app root as a sibling of `agent/`, not inside it. Eval files are discovered at `eve eval` time and are not written into `.eve/`.

## Authored slot table

The **Subagents** column states whether a local subagent package (`subagents/<id>/`) may author the slot. Unsupported directories under an agent root are ignored with a discovery warning.

| Path | Description | Subagents | Notes |
| --- | --- | --- | --- |
| `agent.ts` | Runtime config (`defineAgent`) | Yes | Model, compaction, `build.externalDependencies`, `experimental`. Required `description` on subagents. |
| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | Flat file or directory of `.md`/`.ts` sources. Static sources compose at build time; `defineDynamic` + `defineInstructions` resolve at runtime. **Required on root**, optional on subagents. |
| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings. Auto-discovered at server startup before agent code. Root-only. |
| `channels/` | HTTP and messaging entrypoints | No | Module-backed only. Recursive directories supported. Root-only. |
| `connections/` | MCP and OpenAPI connections | Yes | One connection per file or folder (`connections/<name>/connection.ts`). Name derived from path segment. |
| `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories supported. |
| `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Seeded into `/workspace/skills/...`. |
| `lib/` | Shared authored helper code | Yes | Import-only; never mounted into the sandbox workspace. |
| `sandbox.ts` or `sandbox/sandbox.ts` | Single sandbox definition | Yes | Top-level `sandbox.ts` for definition-only override; `sandbox/sandbox.ts` + `sandbox/workspace/**` to also seed files. Framework default applies when neither is authored. |
| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/...` at session bootstrap. Cannot contain `skills/` (reserved). |
| `tools/` | Typed executable integrations | Yes | Module-backed only. Recursive directories supported; nested paths flatten into tool names. |
| `schedules/` | Recurring jobs | No | `<name>.ts` (`defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only. |
| `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents/<id>/`, a single-file module, or a `defineRemoteAgent` module. Nested subagents supported. |

<Tip>
Legacy `system.md` / `system.ts` still resolve with a deprecation warning. Prefer `instructions.*`.
</Tip>

## What reaches the sandbox workspace

Eve does not mount the entire `agent/` tree into the sandbox. Only two authored sources land in the live workspace:

| Authored source | Sandbox path |
| --- | --- |
| `agent/skills/**` | `/workspace/skills/...` |
| `agent/sandbox/workspace/**` | `/workspace/...` at session bootstrap |

Everything under `lib/` stays import-only source code and never reaches the workspace. The compiled manifest records a `workspaceResourceRoot` descriptor pointing at materialized trees under `.eve/compile/workspace-resources/`.

## Local subagent layout and inheritance

A declared local subagent lives under `agent/subagents/<id>/` and uses the same slot grammar as the root, minus root-only slots.

:::files
agent/subagents/researcher/
├── agent.ts              # required; must export description
├── instructions.md       # optional
├── connections/
├── hooks/
├── skills/
├── lib/
├── sandbox/
├── tools/
└── subagents/            # nested subagents supported
:::

**Inheritance rule:** A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root. An absent slot falls back to the framework default, not to the root's version.

| Slot | Declared subagent behavior |
| --- | --- |
| Instructions | Own `instructions.{md,ts}` or directory; optional |
| Tools, connections, skills, hooks | Own directories only |
| Sandbox | Own `sandbox.ts` or `sandbox/`; else framework default (not parent's sandbox) |
| Channels, schedules, instrumentation | Not supported — discovery emits an error for `schedules/` inside subagents |
| State (`defineState`) | Fresh per child session; never shared |

When two subagents need the same procedure, copy skill markdown into each `skills/` directory, or share typed helpers via `lib/`. The built-in `agent` tool is the exception: its children are copies of the parent and share sandbox, tools, and connections.

Remote subagents (`defineRemoteAgent`) also live under `agent/subagents/` as single-file modules. Identity is path-derived like local subagents; the compiler lowers them into the manifest's `remoteAgents` array.

## Evals placement

Evals are authored at the app root, outside `agent/`:

| File pattern | Purpose |
| --- | --- |
| `evals/**/*.eval.ts` | Eval definitions (`defineEval` default export) |
| `evals/evals.config.ts` | Required run-wide defaults (`defineEvalConfig`) |

Eval identity is path-derived: `evals/weather/brooklyn-forecast.eval.ts` becomes id `weather/brooklyn-forecast`. Array exports in one file receive zero-padded index suffixes (`weather/0000`). Eval discovery runs independently of `eve build` and does not produce `.eve/` artifacts.

## Compile pipeline and `.eve/` artifacts

`eve build` (and dev-server startup) runs discovery, then writes compiler-owned artifacts. The pipeline is: resolve project layout → walk `agent/` → emit discovery manifest → compile normalized manifest → materialize workspace resources.

```mermaid
flowchart LR
  subgraph authored [Authored surface]
    A["agent/**"]
  end
  subgraph discovery [".eve/discovery/"]
    D1["agent-discovery-manifest.json"]
    D2["diagnostics.json"]
  end
  subgraph compile [".eve/compile/"]
    C1["compiled-agent-manifest.json"]
    C2["module-map.mjs"]
    C3["compile-metadata.json"]
    C4["workspace-resources/"]
    C5["channel-instrumentation-types.d.ts"]
  end
  A --> D1
  A --> D2
  D1 --> C1
  C1 --> C2
  C1 --> C4
```

### Discovery artifacts (`.eve/discovery/`)

| File | Contents |
| --- | --- |
| `agent-discovery-manifest.json` | Raw discovery manifest: source refs, logical paths, subagent graph before module import |
| `diagnostics.json` | Structured discovery diagnostics with error and warning counts |

### Compile artifacts (`.eve/compile/`)

| File | Contents |
| --- | --- |
| `compiled-agent-manifest.json` | Versioned runtime manifest (`eve-agent-compiled-manifest`, schema version 29): normalized config, tools, connections, skills, channels, schedules, hooks, sandbox metadata, flattened subagent nodes and edges, `remoteAgents`, `workspaceResourceRoot` |
| `module-map.mjs` | Compiled module map for loading authored exports at runtime |
| `compile-metadata.json` | Generator version, artifact SHA-256 digests, `status` (`ready` or `failed`), discovery summary |
| `workspace-resources/` | Per-node materialized skill packages and sandbox workspace trees |
| `channel-instrumentation-types.d.ts` | Generated channel instrumentation types |

<Warning>
When discovery reports errors, `compile-metadata.json` sets `status` to `failed` and `eve build` throws. Warnings alone still produce artifacts with `status: ready`.
</Warning>

The compiled manifest flattens the subagent tree: each local subagent becomes a `CompiledSubagentNode` with its own `CompiledAgentNodeManifest`, connected to its parent via `subagentEdges`. Root agent node id is `__root__`; nested ids compose from parent and source id.

## Verify discovery

<Steps>
<Step title="Run eve info">

```sh
eve info
```

Inspect layout, compile status, diagnostics summary, and artifact paths.

</Step>
<Step title="Inspect diagnostics when counts are non-zero">

Open `.eve/discovery/diagnostics.json` for structured error and warning entries with source paths and diagnostic codes.

</Step>
<Step title="Confirm compile metadata">

Check `.eve/compile/compile-metadata.json` for `status: ready` before deploying or starting production.

</Step>
</Steps>

`eve info --json` emits the same artifact paths and discovered tool/skill lists that the runtime serves from the compiled manifest.

## Flat layout alternative

When the app root is also the agent root:

:::files
my-agent/
├── package.json
├── agent.ts
├── instructions.md
├── tools/
└── skills/
:::

Prefer the nested layout for new projects. It keeps package scaffolding, evals, and the authored agent surface in separate trees.

## Related pages

<CardGroup>
<Card title="Overview" href="/overview">
Filesystem-first agent model, channel/harness/runtime split, and the shortest path from init to a running session.
</Card>
<Card title="Quickstart" href="/quickstart">
Scaffold with `eve init`, verify with `eve info`, iterate with `eve dev`.
</Card>
<Card title="Subagents and schedules" href="/subagents-and-schedules">
Local subagents, remote agents, cron schedules, and delegation boundaries.
</Card>
<Card title="Instrumentation and evals" href="/instrumentation-and-evals">
`defineInstrumentation`, `defineEval`, `eve eval`, and reporters.
</Card>
<Card title="CLI reference" href="/cli-reference">
All `eve` commands, flags, `.eve/` artifact paths, and the edit-info-dev-build-start loop.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Discovery diagnostics, common failure modes, and runtime error codes.
</Card>
</CardGroup>