Skip to content

AGENTS.md

Latest commit

 

History

History
46 lines (36 loc) · 2.66 KB

AGENTS.md

File metadata and controls

46 lines (36 loc) · 2.66 KB

Repository Guidelines

Project Structure & Module Organization

This repo is a single package with a browser demo:

  • src/: agent loop, model adapter, and browser tools.
  • test/: Node test suites.
  • examples/: demo UI (left chat, right canvas).
  • README.md: public API and usage examples.

Build, Test, and Development Commands

  • npm install: installs dependencies.
  • npm run build: builds the library to dist/.
  • npm run dev: runs the demo with hot reload (opens the browser).
  • npm test: builds and runs tests. The --experimental-loader warning during tests is expected and can be ignored.
  • npm run lint: runs ESLint.

Coding Style & Naming Conventions

ESLint is configured; use tabs for indentation. Match existing examples in README.md and use clear, descriptive names. Tool descriptions live near the tool definition in src/tools.ts. Use explicit types on function signatures (args and return types). Type definitions belong in src/types.ts to keep logic files focused. Helper functions should remain private inside their modules; do not create separate helper files. Prefer flat argument lists for function definitions; avoid deeply nested or overly abstracted type taxonomies. Keep type shapes shallow and avoid nested types when possible. Avoid "Runner/Doer" objects or classes (e.g., AgentRunner-style interfaces). Expose actions as functions and keep data separate. Do not bundle execution context into a single object (e.g., loopCtx); pass required data as explicit, flat parameters. Prefer functional style: pure(ish) functions, explicit inputs/outputs, minimal mutable state, and no action-bearing objects.

Testing Guidelines

Tests live in test/ and use Node’s built‑in test runner (node --test). If you add tests, keep them focused on public API behavior.

Commit & Pull Request Guidelines

Git history is minimal (e.g., “Initial commit” and a short “ic”), so there is no established convention. Use concise, imperative commit messages (e.g., “Add JS interpreter helpers”).

Pull requests should include:

  • A short description of the change and its motivation.
  • Links to related issues (if any).
  • README updates for API or workflow changes.

Security & Configuration Tips

Do not commit real API keys. The README example explicitly warns against passing personal keys; prefer a backend proxy or environment-based configuration.

ExecPlans

When writing complex features or significant refactors, use an ExecPlan (as described in PLANS.md) from design to implementation.

Codding guidance

  • run tests after feature has completed
  • run the linter before committing changes
  • update README.md whenever API, usage, or workflow changes