Skip to content

AGENTS.md

Latest commit

 

History

History
406 lines (340 loc) · 20.9 KB

AGENTS.md

File metadata and controls

406 lines (340 loc) · 20.9 KB
Raw

elizaOS repository guide

This monorepo contains the elizaOS agent framework and the product stack built on it: the core runtime, standalone agent host, Eliza application, CLI, cloud services, native bridges, documentation, tests, and first-party plugins. Bootable Linux and AOSP distributions are maintained separately in elizaOS/os.

How repository instructions work

  • Read this guide before changing the repository.
  • Before working in a package or plugin, read the nearest CLAUDE.md and its README.md. A local guide adds package-specific architecture, commands, and validation requirements; repository-wide rules in this guide remain binding.
  • CLAUDE.md and AGENTS.md in the same directory must be byte-for-byte identical. Author CLAUDE.md, copy the finished content to AGENTS.md, and run bun run check:agents-claude.
  • The AGENTS.md files under packages/elizaos/src/migrate/__tests__/fixtures/ are migration inputs, not repository instructions. They are intentionally unpaired and must change only when the corresponding migration fixture changes.
  • Treat package manifests, exports, executable scripts, tests, and current source as the factual authority. Documentation is a map, not evidence that a feature still exists.

Naming

Write elizaOS, never ElizaOS. The npm scope is @elizaos/*. Use Eliza agents for agents built with the framework. The Eliza Classic plugin is the deliberate exception because it reimplements the 1966 chatbot.

Before editing

  1. Run git status --short --branch. This is a shared working tree and existing changes belong to their authors; do not discard, rewrite, or stage unrelated work.
  2. Identify the owning workspace and read its local guide, README, manifest, exports, and relevant tests.
  3. Search for callers and contract tests before changing a public type, route, event, environment variable, script, or package export.
  4. Use the narrowest relevant command while iterating, then run the required package and repository gates before declaring the work complete.

Toolchain

  • Runtime: Bun 1.3.14 and Node 24.15.0 are pinned in package.json. Use the pinned versions; do not silently substitute npm, pnpm, Yarn, or an older Node runtime.
  • Modules: ESM only ("type": "module"). Do not introduce CommonJS.
  • Workspace orchestration: Turbo drives package build, typecheck, lint, and test tasks. Workspace globs are defined in package.json.
  • TypeScript: the repository uses project references through root and package tsconfig files.
  • Formatting and linting: Biome is pinned by the repository. Configuration lives in biome.json and exclusions in .biomeignore.
  • Tests: Vitest is the primary runner; repository lanes are orchestrated by packages/scripts/run-all-tests.mjs.

Root commands

bun install            # install workspaces, prepare submodules, apply patches, sync artifacts
bun run install:light  # install without the large artifact sync
bun run dev            # start the API and Eliza app development UI
bun run start          # start the standalone agent host
bun run build          # build the workspace through Turbo
bun run verify         # parity, dependency, type, lint, and repository audit gates
bun run lint           # workspace lint tasks
bun run format         # workspace formatting tasks
bun run typecheck      # workspace TypeScript checks
bun run test           # repository unit and integration lane
bun run test:server    # server package lane
bun run test:client    # client package lane
bun run test:e2e       # end-to-end lane
bun run cloud:mock     # start the local cloud stack with mocks
bun run clean          # remove generated build, cache, install, and local-state output
bun run reset          # clean, reinstall, and rebuild

Run bun run with no arguments for the live script inventory. Scope a package command with bun run --cwd <workspace> <script>, for example:

bun run --cwd packages/core test
bun run --cwd plugins/plugin-browser typecheck

Shared app development server

Use the normal bun run dev flow for a single checkout. Concurrent worktrees must not all bind the default app port. From packages/app use:

bun run dev:shared   # start or reuse this worktree's deterministic Vite port
bun run dev:status   # list registered shared servers
bun run dev:rebuild  # request a full Vite reload for this worktree

Reservations live in ~/.eliza/dev-server-registry.json and may be redirected with ELIZA_DEV_SERVER_REGISTRY. See packages/docs/development/shared-dev-server.md.

Removed root command migrations

Removed command Use instead
bun run test:ci bun run test
bun run test:cloud:playwright bun run --cwd packages/app test:e2e
bun run test:ui:playwright bun run --cwd packages/app test:e2e
bun run test:lifeops bun run test:plugin 'plugin-personal-assistant'
bun run trajectory:inspect:test bun test packages/scripts/__tests__/trajectory-validate.test.ts
bun run audit:e2e-coverage:test bun test packages/scripts/e2e-coverage/check-e2e-coverage.test.ts
bun run test:browser-bridge bun run --cwd packages/browser-extension test
bun run test:browser-bridge:safari bun run --cwd packages/browser-extension test:smoke:safari
bun run voice:latency-report bun run --cwd packages/app-core voice:latency-report
bun run voice:interactive bun run --cwd packages/app-core voice:interactive
bun run voice:duet bun run --cwd packages/app-core voice:duet
bun run voice:create-profile bun run --cwd packages/app-core voice:create-profile
bun run smartglasses:hardware:doctor bun run --cwd packages/examples/smartglasses hardware:doctor
bun run smartglasses:hardware:status bun run --cwd packages/examples/smartglasses hardware:status-latest
bun run smartglasses:hardware:validate bun run --cwd packages/examples/smartglasses hardware:validate-latest
bun run smartglasses:hardware:prove bun run --cwd packages/examples/smartglasses hardware:prove:bleak
bun run smartglasses:hardware:prove:watch bun run --cwd packages/examples/smartglasses hardware:prove:bleak:watch
bun run smartglasses:hardware:prove:noble bun run --cwd packages/examples/smartglasses hardware:prove:noble
bun run smartglasses:hardware:prove:noble:watch bun run --cwd packages/examples/smartglasses hardware:prove:noble:watch
bun run smartglasses:dev:hardware bun run --cwd packages/examples/smartglasses dev:hardware
bun run smartglasses:dev:simulator bun run --cwd packages/examples/smartglasses dev:simulator
bun run smartglasses:simulator bun run --cwd packages/examples/smartglasses simulator
bun run smartglasses:smoke:simulator bun run --cwd packages/examples/smartglasses smoke:simulator
bun run test:ci:live bun run test:live
bun run test:lint retired with its aggregate tooling; no direct replacement
bun run test:lint:no-vi-mocks bun run audit:test-integrity:no-vi-mocks
bun run test:lint:lane-coverage retired with its tooling; no replacement
bun run test:lint:test-integrity retired with its tooling; no replacement
bun run test:lint:test-integrity:self-test retired with its tooling; no replacement
bun run verify:smartglasses-software bun run audit:smartglasses-software
bun run personality:judge bun run bench:personality
bun run personality:bench:calibrate bun run bench:personality:calibrate
bun run lint:all bun run verify
bun run build:typescript node packages/scripts/run-turbo.mjs run build
bun run audit:mvp-board bun run mvp:closeout-audit
bun run mvp:board-readiness bun run mvp:closeout-audit
bun run mvp:evidence-matrix bun run mvp:closeout-audit

Repository map

packages/
  core/             @elizaos/core: AgentRuntime, contracts, message loop, memory, models
  agent/            @elizaos/agent: standalone runtime assembly and HTTP backend
  app-core/         shared application host, APIs, startup, build, and platform tooling
  app/              Eliza web, desktop, and mobile UI application
  auth/             shared account credentials, OAuth, subscription, and refresh logic
  ui/               shared React primitives and product surfaces
  elizaos/          the elizaos CLI and packaged project/plugin templates
  prompts/          shared prompt templates across supported languages
  shared/           cross-package utilities, contracts, and brand assets
  logger/           structured logging package
  vault/            secrets and configuration storage adapters
  skills/           bundled runtime skills and loading utilities
  registry/         first-party and community plugin registry data and validation
  scenario-runner/  real-runtime scenario execution and report generation
  test/             repository-wide scenarios and test corpus
  evidence/         evidence manifest, bundle, verification, and ingestion foundation
  docs/             documentation site source
  homepage/         public Eliza product and download site
  training/         Eliza-1 training, evaluation, conversion, and release tooling
  cloud/            API, shared libraries, routing, SDK, infrastructure, tests, services
  native/           native runtimes, third-party dependencies, and C/C++ plugins

plugins/
  plugin-<provider>/ model and inference providers
  plugin-<channel>/  messaging and workspace connectors
  plugin-native-*/   platform and device bridges
  plugin-*/          domain capabilities, app views, storage, tools, and orchestration

scripts/            repository-wide checks, CI helpers, evidence, security, and release tools
patches/            dependency patches applied during installation

Some directories are organizational roots rather than npm workspaces. Use the nearest manifest and local guide instead of inferring ownership from directory depth.

Runtime architecture

  • @elizaos/core owns AgentRuntime, the canonical public types, the plugin contract, the message loop, model abstraction, memory/state primitives, and framework services.
  • @elizaos/agent assembles a runnable backend around core. It owns the standalone process, plugin loading policy, HTTP/WebSocket surfaces, and host-level services.
  • @elizaos/app-core hosts Eliza application targets and their compatibility APIs, startup flow, platform integration, and build orchestration.
  • @elizaos/app and @elizaos/ui render product state. Business values belong in use-cases and DTOs, not recomputed in view or proxy layers.
  • A plugin normally exports a Plugin from src/index.ts. Plugins may contribute actions, providers, evaluators, services, model handlers, routes, events, tests, and app views.
  • The elizaos CLI is package-first. Its templates under packages/elizaos/templates/ are governed by their SCAFFOLD.md contracts.

When code needs only the framework, depend on @elizaos/core. Do not depend on an application host to reach a core abstraction.

Engineering conventions

  • Use the structured logger in server/runtime code; never use console there. Prefix human-readable messages with the owning class or subsystem and attach structured context to errors.
  • Keep boundary types explicit. Validate untrusted input once, then use the validated type. Avoid any, broad unknown, unchecked casts, and optional chaining that hides a required collaborator.
  • DTO fields are required by default. If the producer failed to load a value, represent that as an error or explicit unavailable state rather than a healthy-looking zero, empty string, or empty collection.
  • Route, proxy, and compatibility layers translate protocols. Business computation belongs in domain services or use-cases, and clients render the resulting DTO.
  • Preserve public compatibility deliberately. Search exports, consumers, templates, generated registry data, and contract tests before changing a public surface.

Error policy: fail fast inside, handle at boundaries

Inner data paths throw typed errors. A designated process, transport, or UI boundary may translate the failure into a structured response or a visibly distinct error/unavailable state. Do not catch and continue with fabricated success.

New or rewritten domain failures use ElizaError from packages/core/src/errors.ts with an actionable code, relevant context, a cause when wrapping, and severity when appropriate. Diagnostic failures in providers, services, background jobs, and event handlers call runtime.reportError(scope, error, context?); the runtime logs them, emits EventType.ERROR_REPORTED, exposes them through RECENT_ERRORS, and supports owner escalation. Action/tool failures already return to the planner path.

Every retained catch must document one of these grep-able categories on the handler with // error-policy:J<N> <reason>:

  • J1 — boundary translation: the outer process or transport boundary returns a structured failure.
  • J2 — context-adding rethrow: wrap with a typed error and preserve cause.
  • J3 — untrusted-input sanitizing: parsing produces an explicit invalid result, never a fake-valid default.
  • J4 — user-facing degrade: only an expected error shape becomes a visibly distinct unavailable/error state.
  • J5 — unhandled-rejection suppression: the comment names where the same rejection is observed.
  • J6 — best-effort teardown: teardown-only failure is logged at debug/warn.
  • J7 — diagnostics must not kill the loop: telemetry/trajectory failure is warned and reported through runtime.reportError.

Empty catches, .catch(() => {}), log-and-continue data paths, default returns from catches, and ?? <literal> used to disguise missing required data are not valid recovery. In UI code, loading, designed-empty, and error are three different states. The established examples are packages/ui/src/components/pages/StreamView.tsx and packages/ui/src/state/usePluginsSkillsState.ts.

File headers and comments

Every maintained source file begins with one prose /** ... */ header after a shebang or third-party license block and before imports. The first sentence states the file's system responsibility without repeating its filename. Add only the context a reader cannot infer from the code: consumers, inputs, invariants, protocol constraints, ownership boundaries, and non-obvious consequences.

  • Tiny barrels and type files usually need one line; ordinary modules need two to six; load-bearing modules may use two or three short paragraphs. Keep the header under roughly 25 lines.
  • Test headers state the surface under test and whether the harness is real, integration-backed, deterministic, or mocked.
  • Exported-symbol JSDoc serves callers. In-body // comments explain why a design or ordering constraint exists.
  • Delete code narration, change history, migration stories, status notes, commented-out code, and comments that merely restate the next statement.
  • Never edit generated files or third-party license text as part of comment cleanup.

Use these tone references:

  • packages/agent/src/api/media-store.ts
  • packages/ui/src/components/RoleGate.tsx
  • packages/scripts/run-all-tests.mjs
  • .gitmodules

Comment-only work must pass bun run check:comment-only, which verifies that the code token stream is unchanged.

Cross-package invariants

Scheduling and personal-assistant domains

There is one clock and one scheduled-item architecture. Core TaskService owns when work runs. @elizaos/plugin-scheduling owns the storage-agnostic ScheduledTask state machine and runner. Personal-assistant and health domains contribute structural records and registries; they do not create competing schedulers.

Behavior must branch on typed fields such as kind, trigger, shouldFire, completionCheck, and pipeline, never on prose in promptInstructions. Connector delivery returns typed DispatchResult, not a boolean. Identity and relationship changes go through the shared EntityStore, RelationshipStore, and merge engine. The authoritative implementation and contribution contracts are in:

  • plugins/plugin-scheduling/README.md
  • plugins/plugin-personal-assistant/README.md
  • plugins/plugin-health/README.md
  • plugins/plugin-relationships/README.md

Attachments and media

Attachment bytes use the single content-addressed store in packages/agent/src/api/media-store.ts: ${STATE_DIR}/media/<sha256>.<ext>, served from /api/media/<sha256>.<ext>. The SHA-256 URL is the canonical deduplicated capability handle; Media in packages/core/src/types/primitives.ts is the in-message reference and may only be widened additively.

Do not add a second file store, a storage selector, a files table, reference counting, a second garbage collector, or a fileId field on Media. The existing store uses gcUnreferencedMedia with a grace window. Server-side attachment fetches must pass through the SSRF guard in packages/core/src/network and packages/core/src/media/fetch.ts. The pre-authenticated read route must not rewrite or rehost bytes; authenticated writes may rehost. ContentType is frozen and append-only, so derive finer kinds from mimeType at read time.

Testing and verification

Run focused checks while iterating, then expand in proportion to the affected surface. At minimum, documentation changes must pass guide parity and link/path validation; code changes must pass the owning package's tests, typecheck, and lint plus the root bun run verify gate.

Tests must exercise the real contract being changed. Cover error, empty, invalid-input, concurrency, authorization, and adversarial paths where they are meaningful. A mock or stub standing in for the system under test is useful for unit coverage but is not end-to-end proof.

App visual review

Any change in packages/app, or a shared UI change that reaches it, must run:

bun run --cwd packages/app audit:app

Review every affected desktop and mobile capture, including rest and hover states. No touched view may retain a computed needs-work or broken verdict. Run at least five audit/inspection/iteration cycles for a meaningful redesign. Orange is the accent; do not introduce blue, and use darker orange—not black— for an orange resting control's hover state. The full visual contract lives in packages/app/CLAUDE.md.

GitHub workflow and definition of done

Read CONTRIBUTING.md before claiming coordinated work or opening a pull request. Issues define scoped acceptance criteria; GitHub Projects track live ownership and status; discussions coordinate across work; the pull request carries the implementation and proof. Do not move a card to Done unless the board explicitly grants that authority.

  • Open an issue before a non-trivial change.
  • Use a feat/, fix/, docs/, or chore/ branch and target develop.
  • Before opening or updating a PR, fetch and rebase on origin/develop, resolve every conflict, run bun install, and run bun run verify.
  • Never push feature or fix work directly to develop.

A reviewer must be able to verify the behavior without reading the code:

  1. Exercise the real path and inspect the result yourself. Green automation is not a substitute for reviewing the generated artifact, pixels, audio, logs, model trajectory, database row, scheduled item, or on-chain result.
  2. Use real integrations for end-to-end evidence. When agent behavior changes, record live-model inputs and outputs; when a native/device/connector path changes, run it on the real supported target.
  3. Leave no TODO, stub, fabricated success, or undocumented follow-up in the delivered scope.

For frontend-testable work, include before/after full-page desktop and mobile screenshots, an MP4 walkthrough, backend logs, frontend console/network logs, and any applicable live-model trajectories. Use bun run test:matrix:review for the full evidence matrix, bun run test:e2e:record:review for scoped UI recording, and the platform capture commands documented in CONTRIBUTING.md for native targets. Build, install, and verify the current revision before capture; capture tools do not prove that the installed application is current.

Evidence belongs inline in the issue and PR, not committed to the repository. Prefer JPG screenshots, MP4 video, and collapsible log blocks. Mark a genuinely inapplicable evidence row N/A with a reason rather than leaving it blank.

Security and contribution references

Report suspected vulnerabilities privately through GitHub Security Advisories. Do not place exploit details, secrets, or embargoed dependency information in a public issue, PR, log, or agent transcript. Product security documentation is in packages/docs/security.md.

The repository is MIT licensed. Contribution workflow and evidence policy live in CONTRIBUTING.md.