# Atom Eve — Quick Start Atom Eve is an open-source registry of installable AI agents for **eve.dev** and **Flue** projects — like shadcn, but for agents. Each agent is a folder holding a `README.md` (what it is, with its manifest in the frontmatter), a `SETUP.md` (what it needs and how to wire it), and the `agent/` source that installs into your project. Browse the full catalog at **https://atomeve.dev**. --- ## For AI coding assistants If a user pasted a prompt like _"Read www.atomeve.dev/start.md and add agents…"_, do this: 1. **Detect or scaffold the project.** Eve is the default target; use Flue only when the user asks for Flue or the project is already a Flue project. - An Eve project has an `agent/` directory. - A Flue project uses `@flue/runtime` and source under `src/`. - If no project exists and the user did not ask for Flue, scaffold an Eve project with `npx atom-eve create --agent `. 2. **Never overwrite an existing agent without asking.** A project holds one agent (`agent/`). Running `npx atom-eve add ` in a configured project **replaces that agent in place** — instructions, schedules, skills, and channels all get swapped. Only do this when the user explicitly wants to replace the agent living there. - To add another agent, keep them side by side in a monorepo: each agent is its own project directory (and its own Vercel project). Scaffold the root once with `npx atom-eve init --workspace `, then `cd ` and run `npx atom-eve create --agent ` for each agent — apps land under `agents/`. - If the current directory already has an `agent/`, **stop and ask**: replace it, or add the new one as a separate project? Default to a separate project. 3. **Find the right agents.** Match the user's goal to agents in the registry (see "Browse" below). Prefer agents whose `family`/`category` fit the job. 4. **Install each agent.** New project or second agent: `npx atom-eve create --agent ` in its own directory (default the name to the agent's name unless the user picked one). Replace an existing agent (after confirming, per step 2): `npx atom-eve add `. Flue: `npx atom-eve add --target flue`. The CLI only ever prompts to pick a target, and skips that without a TTY (or with `CI=1`); pass `--target` to be explicit. 5. **Wire up credentials and config.** Follow the "Setup playbook" below: do the setup work yourself instead of dumping instructions on the user. 6. **Prepare runtime config.** For eve.dev: link Vercel with `vercel link` (an account-level action: it creates or links a Vercel project, so confirm with the user first) and pull existing env with `vercel env pull`. --- ## Setup playbook Every agent declares what it needs in the registry: `env` (secrets) and `config` (non-secret project settings). You (the coding agent) do the setup; the user only handles decisions and the few steps that genuinely require their browser or account. 1. **Read what the agent needs.** Two sources, one authored story: - `https://www.atomeve.dev/index.json` (a top-level `items` array; match on `name`) lists each agent's `env` (secrets: `name`, `description`, `url`, `optional`) and `config` (non-secret project settings that go into the `` block in `agent/instructions.md`). - The agent's `SETUP.md` is the walkthrough: how to obtain, verify, and store every credential. It installs into the project root; run the install first and read it from there. - `connections` with auth `vercel-connect` (e.g. Slack) are wired in the Vercel dashboard via Connect. Connections with auth `env` wire themselves from env vars at runtime; there is nothing to register anywhere. 2. **Inspect before asking.** Check what already exists: `.env.local` / `.env`, `vercel env ls` if the project is linked, and which CLIs are installed and signed in (`vercel`, `gh`, `gcloud`, provider CLIs), including which accounts and projects they are signed into. Never ask the user for a value you can discover or mint yourself. 3. **Ask everything up front, in one message.** After inspecting, open with a single message that collects every decision at once: each `config` value (show its `example`), which account or cloud project to use wherever you found more than one, and whether the user already has an account for services that need a sign-up. Then work through setup with as few interruptions as possible. Don't drip questions one at a time. 4. **Two consent tiers.** - Inside the project directory (writing `.env.local`, editing `agent/instructions.md`, installing dependencies): just do it. - Against any user account (creating cloud resources or keys, enabling APIs, linking or adding env to a Vercel project, anything that could bill or leave residue): first show the exact commands and which account/project they run against, get one confirmation for the whole batch, then run them. 5. **Prefer the CLI path.** `gh auth token` mints a GitHub token if the GitHub CLI is signed in; `gcloud` can create service accounts and keys; use `npx vercel@latest` when the Vercel CLI is not installed. If a needed CLI is missing, offer to install it or fall back to the dashboard steps; never leave a dead end. 6. **Browser steps: be exact.** When a step only exists in a dashboard, give the user the exact URL and click path from the SETUP.md walkthrough and say exactly what to enter where, including which email or ID to paste (e.g. "add this service account email as a user in Search Console → Settings → Users and permissions"). Tell them what, if anything, to paste back. 7. **Store secrets safely.** Local runs: write `.env.local` (gitignored), but note that `vercel env pull` overwrites `.env.local`, so pull before writing, or pull to a separate file. Deployed or scheduled runs: `vercel env add NAME production` reads the value from stdin, so pipe it in (production is where schedules run; add other targets only if the user wants them). Multi-line values such as JSON key files must be stored as a single line, quoted so embedded quotes and backslashes survive dotenv parsing. If a key file was written to disk on the way, put it outside the project directory and delete it after inlining. Never invent a value, never echo a secret back to the user, never commit one. 8. **Validate with consent.** SETUP.md describes a read-only verification check per credential. Before using the user's credentials for the first time, ask once for the whole batch: name each call, note that it is read-only, and flag anything that could cost money on a metered API. On a yes, run the checks and report per credential. If one fails, show the actual API error, not a guess. 9. **Write the project config.** Agents ship a `` block at the top of `agent/instructions.md`: replace its `not set` values with the user's answers and leave the markers in place. If an agent has no block, state the values as facts where the instructions expect them. Optional entries the user skipped stay `not set` (their line says what that means). They are not blockers, but note what enabling them would add. 10. **Finish with a real run.** `npx eve dev` starts the local runtime with an interactive terminal; send the agent a first message (e.g. "run your weekly SEO review for example.com") and confirm it does real work. The terminal UI needs a TTY; if you cannot drive one, start it for the user and give them the exact first message to type. A real run spends model tokens and any metered API credits, so say that when you propose it; the validation consent does not cover it. Once the project is deployed (`vercel deploy` or a git push to the linked project), any schedules run automatically on Vercel Cron, and a Slack-connected agent can be @mentioned. If nothing can run yet, state the single exact step that remains and who has to do it. For Eve, model calls go through the Vercel AI Gateway. The user does not need a model API key, but their Vercel account/team must have any required AI Gateway billing or account verification complete. If the first run fails with an AI Gateway/provider error, report it as model setup friction and ask the user to verify billing/access. `AGENT_MODEL` only changes runtime behavior when the installed Eve agent has an `agent/agent.ts` that reads it. To force a non-default model, add or update `agent/agent.ts`: ```ts import { defineAgent } from "eve"; export default defineAgent({ model: process.env.AGENT_MODEL ?? "anthropic/claude-sonnet-4.6" }); ``` Then set `AGENT_MODEL` to a provider/model available through the linked Vercel project. Agents never auto-publish or take destructive actions on their own — they open PRs or post drafts for review. Keep that behavior intact when wiring them in. --- ## CLI ```bash # Scaffold a new Eve project and install an agent npx atom-eve create my-agent --agent website-qa # Add an agent to an existing project npx atom-eve add website-qa # Generate/install for Flue npx atom-eve add website-qa --target flue # List available agents npx atom-eve list ``` `create` delegates to the framework scaffolder, installs the selected agent, and writes `atom-eve.json`. `init` still exists for advanced/manual setups, but `create` is the first-time happy path. --- ## Browse The registry is grouped into families: - **engineering** — code review, QA, docs, observability, migrations - **growth** — SEO, ads, content, social, CRO - **revenue** — outreach, CRM, sales, finance - **support** — ticket triage, onboarding, community - **ops** — productivity, spend, HR, scheduling - **data** — analytics, research Open any agent's page at `https://www.atomeve.dev/agents//` to see its description, required keys, integrations, and install command. --- ## Publish your own Every agent is a folder: a `README.md` with its manifest in the frontmatter, a `SETUP.md`, and the `agent/` source. Fork the template, open a PR, and it's auto-listed on merge. See the repo: **https://github.com/elie222/atom-eve**.