Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: clarify getting started (#2361)

Chad Hietala5552b9074f5d
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index 90a3ab7cd..f3c79240f 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -24,13 +24,7 @@ Run `eve init` with a project name:
npx eve@latest init my-agent
```
-The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
-
-Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
-
-```bash
-npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
-```
+The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.
To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
@@ -40,15 +34,23 @@ npx eve@latest init .
eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
+### Customize initialization
+
+To initialize the agent with a different AI Gateway model or reasoning effort, pass `--model` or `--reasoning`:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
+```
+
## Run the agent
-If the development server is not already running, start it from the project root:
+Choose **Start eve dev** after scaffolding, or run this from the project root:
```bash
npm run dev
```
-The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.
+This starts an interactive session where you can send messages to your agent.
## Project layout
@@ -56,7 +58,7 @@ eve builds an agent by walking the filesystem under `agent/`. Each directory is
### Naming from paths
-Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+eve derives names from file paths, so you do not configure them separately.
| Path | Resolves to |
| ------------------------------------- | --------------------- |
@@ -65,7 +67,7 @@ Identity comes from the path. You never write a `name` or `id` field on a `defin
| `agent/skills/summarize.md` | skill `summarize` |
| `agent/subagents/researcher/agent.ts` | subagent `researcher` |
-The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
+The root agent uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name.
### Recommended layout
@@ -93,31 +95,29 @@ my-agent/
Evals live beside `agent/`, not inside it.
-### Authored slots
-
-The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.
-
-| Path | Description | Subagents | Notes |
-| ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config). |
-| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents. |
-| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. |
-| `channels/` | HTTP and messaging entry points | No | Root-only. |
-| `connections/` | External MCP and OpenAPI services | Yes | One connection per file; its name comes from the filename. |
-| `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories are supported. |
-| `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. |
-| `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. |
-| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
-| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. |
-| `tools/` | Typed executable integrations | Yes | Module-backed only. |
-| `schedules/` | Recurring jobs | No | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only. |
-| `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents/<id>/`. Nested subagents are supported. |
-
-### Runtime files and source files
-
-eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts.
-
-Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code.
+### Agent files and directories
+
+Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**.
+
+| Path | Use | Available to subagents | Notes |
+| ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config). |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents. |
+| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. |
+| `channels/` | HTTP and messaging entry points | No | Root-only. |
+| `connections/` | External MCP and OpenAPI services | Yes | One connection per file; its name comes from the filename. |
+| `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories are supported. |
+| `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. |
+| `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. |
+| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
+| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. |
+| `tools/` | Typed executable integrations | Yes | Module-backed only. |
+| `schedules/` | Recurring jobs | No | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only. |
+| `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents/<id>/`. Nested subagents are supported. |
+
+### Files available in the sandbox
+
+Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts.
### Local subagents