Eve Project Layout

README

# eve-project-layout > Eve framework filesystem-first project layout, define* API signatures, and structural conventions. Use when creating, editing, or debugging files inside an Eve agent directory (agent/tools/, agent/connections/, agent/subagents/, agent/channels/, agent/skills/, agent/schedules/, agent/sandbox/). Also activate when importing from eve, eve/tools, eve/connections, eve/channels, eve/sandbox, eve/hooks, eve/skills, or eve/schedules, even if the user doesn't mention layout or project structure.

SKILL.md

---
name: eve-project-layout
description: >
  Eve framework filesystem-first project layout, define* API signatures, and
  structural conventions. Use when creating, editing, or debugging files inside
  an Eve agent directory (agent/tools/, agent/connections/, agent/subagents/,
  agent/channels/, agent/skills/, agent/schedules/, agent/sandbox/). Also
  activate when importing from "eve", "eve/tools", "eve/connections",
  "eve/channels", "eve/sandbox", "eve/hooks", "eve/skills", or "eve/schedules",
  even if the user doesn't mention "layout" or "project structure".
license: MIT
compatibility: Requires an Eve project with the `eve` npm package installed
metadata:
  author: villain
  version: "1.0"
allowed-tools: Read Bash
---

# Eve Project Layout & API Reference

## Overview

Eve is a **filesystem-first** framework for durable backend AI agents. An agent
is a directory on disk — instructions, skills, tools, connections, channels,
subagents, and schedules are all files — and Eve compiles and runs it.

**The cardinal rule**: Identity comes from the path. You never write a `name` or
`id` field on a `define*` call.

| Path                                  | Resolves to           |
| ------------------------------------- | --------------------- |
| `agent/tools/get_weather.ts`          | tool `get_weather`    |
| `agent/connections/linear.ts`         | connection `linear`   |
| `agent/skills/summarize.md`           | skill `summarize`     |
| `agent/subagents/researcher/agent.ts` | subagent `researcher` |

## Canonical Project Layout

```text
my-agent/
├── package.json
├── tsconfig.json
├── agent/
│   ├── agent.ts              ← defineAgent (model, limits, reasoning)
│   ├── instructions.md       ← Base system prompt (REQUIRED at root)
│   ├── instrumentation.ts    ← OTel config (root-only)
│   ├── channels/             ← HTTP/messaging entrypoints (root-only)
│   ├── connections/           ← MCP / OpenAPI external services
│   ├── hooks/                 ← Lifecycle & stream-event subscribers
│   ├── skills/                ← On-demand procedures
│   ├── lib/                   ← Shared helper code (import-only, never in sandbox)
│   ├── sandbox/               ← Sandbox override + workspace seed files
│   │   ├── sandbox.ts
│   │   └── workspace/         ← Files mirrored into /workspace/...
│   ├── tools/                 ← Typed executable integrations
│   ├── schedules/             ← Recurring jobs (root-only)
│   └── subagents/             ← Specialist child agents
│       └── <id>/
│           ├── agent.ts       ← defineAgent (description REQUIRED)
│           ├── instructions.md (optional)
│           ├── tools/
│           ├── connections/
│           ├── skills/
│           ├── sandbox/
│           └── subagents/     ← Nested subagents supported
└── evals/                     ← Sibling of agent/, not inside it
```

## define* API Quick-Reference

Every file follows the same pattern: import a helper, default-export the result.

| Helper                        | Import from              | Authored at                     |
| ----------------------------- | ------------------------ | ------------------------------- |
| `defineAgent`                 | `eve`                    | `agent/agent.ts`                |
| `defineTool`                  | `eve/tools`              | `agent/tools/<name>.ts`         |
| `defineMcpClientConnection`   | `eve/connections`        | `agent/connections/<name>.ts`   |
| `defineOpenAPIConnection`     | `eve/connections`        | `agent/connections/<name>.ts`   |
| `defineChannel`               | `eve/channels`           | `agent/channels/<name>.ts`     |
| platform channels (e.g. `githubChannel`) | `eve/channels/<platform>` | `agent/channels/<platform>.ts` |
| `defineSkill`                 | `eve/skills`             | `agent/skills/<name>.ts`        |
| `defineInstructions`          | `eve/instructions`       | `agent/instructions.ts`         |
| `defineHook`                  | `eve/hooks`              | `agent/hooks/<slug>.ts`         |
| `defineSchedule`              | `eve/schedules`          | `agent/schedules/<name>.ts`     |
| `defineState`                 | `eve/context`            | tools, hooks, lifecycle          |
| `defineSandbox`               | `eve/sandbox`            | `agent/sandbox.ts`               |
| `defineRemoteAgent`           | `eve`                    | `agent/subagents/<id>/agent.ts` |
| `useEveAgent`                 | `eve/react` (or vue/svelte) | frontend components           |

### Key Import Paths

```
eve                    → defineAgent, defineRemoteAgent
eve/tools              → defineTool, defineDynamic, disableTool
eve/tools/approval     → always, once, never
eve/tools/defaults     → bash, readFile, writeFile, glob, grep, webFetch
eve/connections        → defineMcpClientConnection, defineOpenAPIConnection
eve/channels           → defineChannel, route verbs (GET/POST/etc.)
eve/channels/<platform> → githubChannel, slackChannel, discordChannel, etc.
eve/channels/auth      → localDev, vercelOidc, placeholderAuth
eve/hooks              → defineHook
eve/schedules          → defineSchedule
eve/skills             → defineSkill, defineDynamic
eve/instructions       → defineInstructions, defineDynamic
eve/context            → defineState
eve/sandbox            → defineSandbox, defaultBackend
eve/sandbox/vercel     → vercel()
eve/react              → useEveAgent
eve/client             → Client, ClientSession
```

## Critical Rules

1. **Every file must `export default`** a `define*` call. No named exports.
2. **Names derive from filenames** — never set `name` or `id` in define options.
3. **Subagents inherit NOTHING from root** — they need their own tools, skills, connections, sandbox. Use the built-in `agent` tool if you want inherited tools.
4. **Subagent `agent.ts` MUST have `description`** — the compiler rejects it otherwise.
5. **`defineRemoteAgent`** is for calling *another deployed Eve instance* as a subagent. For local specialist subagents, use `defineAgent` with `description`.
6. **Channels and schedules are root-only** — never place them inside `subagents/`.
7. **`lib/` is import-only** — it never reaches the sandbox workspace.
8. **`evals/` is a sibling of `agent/`**, not inside it.

## Gotchas

- **Wrong**: Using `defineRemoteAgent` for local subagents → use `defineAgent` with `description`
- **Wrong**: Assuming `tool-invocation` / `tool-result` message part types in Eve React → Eve uses `step-start`, `authorization`, `dynamic-tool`
- **Wrong**: Expecting subagent to inherit parent's tools → declared subagents get nothing; use the built-in `agent` tool for inherited copies
- **Wrong**: Placing `channels/` inside a subagent directory → channels are root-only
- **Runtime context**: `ctx` is only live inside `execute` handlers — accessing it at module top level throws

## Available Scripts

No scripts bundled. This is a reference-only skill.

## References

- Read [`references/instructions.md`](references/instructions.md) when writing or updating the agent's system prompt.
- Read [`references/skills.md`](references/skills.md) when defining load-on-demand procedures.
- Read [`references/tools.md`](references/tools.md) when creating typed executable actions.
- Read [`references/workflows.md`](references/workflows.md) when configuring experimental agent workflows.
- Read [`references/subagent-isolation.md`](references/subagent-isolation.md) when creating or debugging subagents, or when a subagent can't find its tools.
- Read [`references/mcp-auth-patterns.md`](references/mcp-auth-patterns.md) when creating MCP connections or debugging auth failures.
- Read [`references/sandbox-backends.md`](references/sandbox-backends.md) when configuring sandbox backends, network policies, or credential brokering.