Kery

AI agents that test your web app and find bugs — no test scripts required.

Point Kery at your web app, pick an LLM provider, and let it loose. It crawls every route, runs intent-driven tests, and hands you a report of visual, functional, and UX bugs — with screenshots and bounding boxes. No selectors to write. No scripts to maintain.

👾 Join the Discord — get help, share what you find, follow development.

---

Quick Start

The fastest path: one command sets up everything.

npx keryai

The CLI wizard asks for your LLM provider and API key, generates a docker-compose.yml, and starts all services. Dashboard opens at http://localhost:11111.

Manual Docker setup:

cp .env.example .env
# Add at least one LLM key — see Configuration below
docker compose up -d

Local development (no Docker):

# Requires Node 20+, PostgreSQL 16+, Redis
npm install
DATABASE_URL=postgresql://kery:kery@localhost:11112/kery npm run migrate
npm run dev:api   # API + Dashboard → http://localhost:11111

---

How It Works

1. Scan — Kery BFS-crawls your app and builds a map of every route, form, modal, and interaction.

2. Plan — For each route or saved test intent, a path-planning agent generates a sequence of steps to exercise that flow.

3. Run — A Navigator agent drives a real Playwright browser, observing the page via accessibility tree and screenshots. A Review Agent and Filmstrip Reviewer run in parallel, watching for visual and UX regressions.

4. Report — A Triage Agent deduplicates findings, filters false positives using memory from past runs, and outputs bugs categorized by type (visual / functional / UX) and severity — each with a screenshot and bounding box.

---

Features

App Discovery

• BFS crawler maps all routes, links, forms, and modals
• Route health dashboard — clean / issues / stale / untested
• Depth and scope controls per project

Autonomous Testing

• Intent-driven tests: describe what to test in plain English
• Supports authenticated flows — form login, Clerk, Supabase, OAuth, API tokens
• Navigator agent uses accessibility tree + screenshots, not brittle CSS selectors
• Stagehand self-healing: when the DOM shifts, elements are found by intent

Bug Detection

• Visual bugs — layout breaks, rendering glitches, pixel regressions
• Functional bugs — broken flows, unexpected errors, failed assertions
• UX bugs — confusing copy, missing feedback, accessibility gaps
• Screenshot per bug with highlighted bounding box; URL, severity, and source agent

Agent Memory

• Learns successful navigation paths across runs
• Records known false positives, ignore regions, and bug patterns
• Confidence scoring with decay — memory stays fresh, not compounding

Integrations

• MCP server: run tests and triage bugs from Claude Code, Cursor, or any MCP-compatible IDE
• TypeScript client SDK for CI/CD and custom orchestration
• REST API + SSE streaming for real-time run progress

LLM Flexibility

• OpenRouter (recommended), OpenAI, Anthropic, Google Gemini
• Each agent role (Navigator, Review, Auxiliary, Stagehand) configurable independently
• Per-run token and cost tracking

---

MCP — Run Kery from Your IDE

Install the MCP server and run tests without leaving your editor.

npx keryai   # select "Install MCP" during setup

Or add it manually to your MCP config:

{
  "mcpServers": {
    "kery": {
      "command": "npx",
      "args": ["-y", "@keryai/mcp"],
      "env": { "KERY_BASE_URL": "http://localhost:11111" }
    }
  }
}

Once connected, your AI assistant can scan your app, run tests, and triage bugs inline — no context switching.

Available tools: kery_scan, kery_run_test, kery_get_bugs, kery_update_bug, kery_list_routes, kery_memory, kery_get_coverage, and 20+ more.

---

Configuration

Variable	Default	Description
DATABASE_URL	postgresql://kery:kery@localhost:11112/kery	PostgreSQL connection string
OPENROUTER_API_KEY	—	OpenRouter key (routes to all models — recommended)
OPENAI_API_KEY	—	Direct OpenAI key
ANTHROPIC_API_KEY	—	Direct Anthropic key
GEMINI_API_KEY	—	Direct Google Gemini key
AGENT_MODEL	claude-haiku-4-5	Model for browser navigation decisions
AUXILIARY_MODEL	gemini-2.5-pro	Crawl, path planning, memory curation, summarization
REVIEW_AGENT_MODEL	claude-sonnet-4-6	Post-run holistic and filmstrip screenshot analysis
STAGEHAND_ENABLED	true	Enable Stagehand for semantic element finding
RUN_TIMEOUT_MINUTES	15	Max wall-clock time per test run

All model settings are also configurable via the dashboard under Settings.

---

Architecture

packages/
  engine/     — Core agent loop, LLM client, crawler, memory, bug triage
  db/         — PostgreSQL storage adapter (StorageAdapter interface)
  kery/       — CLI setup wizard (npx keryai)
  mcp/        — Model Context Protocol server (@keryai/mcp)
  client/     — TypeScript HTTP client SDK (@keryai/client)

apps/
  api/        — Fastify HTTP server
  web/        — React dashboard
  worker/     — Test run executor (BullMQ)

The engine is storage-agnostic via the StorageAdapter interface — PostgreSQL is the default, but other backends can be plugged in.

---

Contributing

Issues and pull requests are welcome. Please open an issue to discuss large changes before starting work.

git clone https://github.com/keryai/kery
cd kery
npm install
cp .env.example .env
docker compose up postgres redis -d
npm run dev

---

License

Apache 2.0 — see LICENSE.