@lisa.ai/agent

The Lisa.ai Agent is an autonomous CI/CD CLI that heals failing tests, generates missing test coverage (unit, E2E, integration), and remediates npm vulnerabilities — all powered by LLMs. Drop it into any JavaScript/TypeScript project and let it fix your build.

Installation

npm install -g @lisa.ai/agent
# or as a dev dependency
npm install --save-dev @lisa.ai/agent

You need at least one LLM API key set as an environment variable:

| Provider | Env var | Default model | |---|---|---| | Google Gemini | GOOGLE_GENERATIVE_AI_API_KEY | gemini-2.0-flash | | Anthropic Claude | ANTHROPIC_API_KEY | claude-haiku-4-5 | | OpenAI | OPENAI_API_KEY | gpt-4o-mini |

Override the default model per provider with LISA_GOOGLE_MODEL, LISA_CLAUDE_MODEL, or LISA_OPENAI_MODEL.

Commands

heal — Auto-Heal Failing Tests

Runs your test command, identifies every failing spec, and autonomously fixes them using LLM-generated patches. Each fix is verified in isolation before moving on.

lisa-agent heal --command "npm test" --model gemini

# Heal specific files only (skip discovery)
lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts

# Heal E2E tests
lisa-agent heal --type e2e

# Heal specific E2E files
lisa-agent heal --type e2e --files e2e/login.spec.ts

How it works:

1. Runs a single global test pass to discover all failures (skipped with --files)
2. Extracts every failing spec file (Karma suite-name matching, Jest FAIL header parsing, Playwright/Cypress)
3. For each file: queries the Memory Engine for proven fix patterns, sends context + error log to the LLM, writes the fix, verifies in isolation
4. Runs a single final global test pass to confirm all fixes together
5. Files that regress are quarantined after 3 strikes

Supported frameworks: Jest, Vitest, Mocha, Karma/Jasmine (Angular), Cypress, Playwright

unit — Generate Unit Tests

Runs your test suite with coverage enabled, identifies files below 100% coverage, and generates new test specs to close the gaps. Auto-detects your test framework and builds the correct coverage command.

lisa-agent unit --model gemini
lisa-agent unit --command "npx jest --coverage --coverageReporters=json-summary" --model claude

# Generate tests for specific source files only
lisa-agent unit --files src/services/auth.service.ts,src/services/user.service.ts

How it works:

1. Auto-detects test framework (Jest, Vitest, Karma, Mocha) and builds coverage command
2. Runs tests with coverage, parses coverage-summary.json
3. Identifies uncovered source files
4. Generates unit test specs targeting uncovered code via LLM
5. If generated tests fail, delegates to the heal loop
6. Re-runs coverage and reports delta

Auto-detected coverage commands:

| Framework | Command | |---|---| | Karma (Angular) | npx ng test --no-watch --code-coverage --browsers=ChromeHeadless | | Jest | npx jest --coverage --coverageReporters=json-summary | | Vitest | npx vitest run --coverage | | Mocha | npx nyc --reporter=json-summary mocha |

e2e — Generate E2E Tests

Generates Playwright end-to-end tests by discovering your app's routes and creating specs for each page/flow. Auto-installs Playwright if no E2E framework is detected.

lisa-agent e2e --model gemini

# Generate E2E test for a specific spec path
lisa-agent e2e --files e2e/login.spec.ts

How it works:

1. Detects existing E2E framework (Playwright or Cypress config files)
2. If none found, auto-installs Playwright + generates playwright.config.ts
3. Discovers routes from Angular/React router config files
4. Generates E2E specs for uncovered routes via LLM
5. Runs specs and heals failures

integration — Generate Integration Tests

Generates integration tests that exercise module seams — testing 2+ modules together without full E2E overhead.

lisa-agent integration --model gemini

# Generate integration test for specific files
lisa-agent integration --files src/services/auth.service.ts

How it works:

1. Detects app type (Angular, React, Express, NestJS, Node)
2. Discovers integration targets: component+service pairs, controller files, multi-import modules
3. Generates integration specs with real services (not mocked) via LLM
4. Runs specs and heals failures

What it generates:

• Angular: TestBed with real services, multi-component interactions, HttpClientTestingModule
• Express/NestJS: Supertest-based endpoint tests with test DB, middleware chains
• General: Tests exercising 2+ modules together

audit — Vulnerability Scanning & Remediation

Scans your project for npm vulnerabilities, applies safe fixes automatically, and consults an LLM for breaking changes that need manual intervention.

lisa-agent audit --model gemini

How it works:

1. Scan — runs npm audit --json (auto-detects npm/yarn/pnpm via lockfile)
2. Safe auto-fix — runs npm audit fix (semver-compatible patches only)
3. Re-scan — checks if vulnerabilities remain
4. Targeted upgrades — applies non-breaking semver-minor fixes
5. LLM guidance — for remaining breaking/unfixable vulnerabilities, consults the LLM and saves a remediation report to lisa-audit-report.md

diagnose — Test LLM Connectivity

Sends a simple probe to your configured LLM provider to verify your API key works and the model is reachable.

lisa-agent diagnose --model claude

init — Create Project Config

Interactively generates a .lisai.json config file in your project root.

lisa-agent init          # interactive wizard
lisa-agent init --force  # overwrite existing config

init-ci — Generate GitHub Actions Workflow

Scaffolds a .github/workflows/lisa-heal.yml file so Lisa.ai runs automatically on every push.

lisa-agent init-ci                    # defaults to Gemini
lisa-agent init-ci --model claude     # use Claude as the LLM provider
lisa-agent init-ci --force            # overwrite existing workflow

The generated workflow:

1. Triggers on push to main/master/develop (+ manual dispatch)
2. Installs project dependencies and Lisa.ai Agent
3. Runs lisa-agent heal --ci
4. If tests fail and Lisa heals them, opens a PR automatically
5. Writes a step summary to the GitHub Actions UI

Required setup: Add your LLM API key as a repository secret in GitHub (Settings > Secrets > Actions). The secret name depends on the provider:

| Provider | Secret name | |---|---| | Gemini | GOOGLE_GENERATIVE_AI_API_KEY | | Claude | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY |

GITHUB_TOKEN is provided automatically by GitHub Actions — no PAT needed.

Common Options

All test commands (heal, unit, e2e, integration, audit) accept:

| Flag | Description | Default | |---|---|---| | -c, --command <cmd> | Test/coverage command to run | Auto-detected | | -m, --model <provider> | gemini, claude, or openai | gemini | | -p, --project-id <id> | Control Plane project for remote config + telemetry | local | | -f, --files <paths> | Target specific files (comma-separated, bypasses discovery) | All files | | -t, --type <scope> | (heal only) Test type to heal: unit, e2e, integration | unit | | --ci | (heal only) CI mode: commit healed files + open PR + write step summary | Off |

Configuration

.lisai.json

Place a .lisai.json in your project root to configure the agent without CLI flags:

{
  "provider": "gemini",
  "model": "gemini-2.0-flash",
  "testCommand": "npm test",
  "testingFramework": "jest",
  "e2eFramework": "playwright",
  "e2eCommand": "npx playwright test",
  "testTypes": ["unit", "integration", "e2e"],
  "maxRetries": 5,
  "skipFiles": ["server.js", "app.js"],
  "skipDirs": ["scripts", "migrations"],
  "skipPaths": ["src/generated", "src/fixtures"]
}

| Field | Type | Description | |---|---|---| | provider | gemini \| claude \| openai | LLM provider | | model | string | Pin a specific model ID (e.g. claude-sonnet-4-6) | | testCommand | string | Override unit test command (skips auto-detection) | | testingFramework | jest \| vitest \| mocha \| karma \| jasmine | Override unit test framework detection | | e2eFramework | playwright \| cypress | Override E2E framework detection | | e2eCommand | string | Override E2E test command | | testTypes | string[] | Types of tests to generate: unit, integration, e2e | | maxRetries | number | Max heal/generation retries per session (default 5) | | skipFiles | string[] | Filenames to exclude from analysis | | skipDirs | string[] | Directory names to exclude | | skipPaths | string[] | Path prefixes to exclude |

All fields are optional. The agent auto-detects everything. This file is the escape hatch for unusual setups.

Config Priority

Settings are resolved in this order (highest wins):

Shell env var  >  Control Plane  >  CLI flag  >  .lisai.json  >  built-in default

Control Plane Integration

Connect the agent to the Lisa.ai Dashboard for remote configuration, telemetry, and the Memory Engine:

lisa-agent heal --command "npm test" --project-id "my-project-123"

With a project ID, the agent will:

• Fetch remote config (model provider, max retries, agent toggle) from the Dashboard
• Report telemetry (heal/unit/e2e/integration events, pass/fail counts) for the Dashboard charts
• Use the Memory Engine — successful fix patterns are stored and reused across runs, so the agent gets smarter over time

Without a project ID, the agent runs fully offline using local config and env vars.

Memory Engine

The Memory Engine stores proven fix patterns from previous heal runs. When the agent encounters an error it has fixed before, it injects the known-good solution into the LLM prompt — dramatically improving fix accuracy and speed.

• Patterns are keyed by normalized error shape + framework + project
• Only patterns with confidence >= 50% are injected
• Confidence = successCount / totalAttempts, updated after each heal attempt
• Memory is project-scoped and stored on the Control Plane (requires --project-id)

Auto-Detection

The agent adapts to your project — zero config required. If no --command is provided, it scans your project to detect:

• Test framework — from config files (jest.config.*, karma.conf.js, vitest.config.*, .mocharc.*) and package.json dependencies
• E2E framework — from playwright.config.ts or cypress.config.ts (defaults to Playwright if none found)
• Coverage command — built automatically per framework with correct reporter flags
• Package manager — npm/yarn/pnpm detected via lockfile
• Missing dependencies — auto-installs test frameworks that are referenced but not installed

Examples

Heal a broken Angular project

export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
lisa-agent heal --command "npx ng test --no-watch --browsers=ChromeHeadless" --model gemini

Generate unit tests for a Node.js API

export ANTHROPIC_API_KEY="your-key"
lisa-agent unit --model claude

Generate Playwright E2E tests

export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
lisa-agent e2e --model gemini

Generate integration tests

export OPENAI_API_KEY="your-key"
lisa-agent integration --model openai

Fix npm vulnerabilities with LLM guidance

lisa-agent audit --model gemini

Target specific files (skip discovery for large projects)

lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts --model gemini
lisa-agent unit --files src/services/auth.service.ts --model claude
lisa-agent e2e --files e2e/login.spec.ts --model gemini
lisa-agent integration --files src/services/user.service.ts --model openai

GitHub Actions CI — auto-heal on every push

# One-time setup: generate the workflow file
lisa-agent init-ci --model gemini

# Then add your API key as a GitHub secret:
#   Repo > Settings > Secrets > Actions > GOOGLE_GENERATIVE_AI_API_KEY

# That's it! On every push, Lisa.ai will:
#   1. Run your tests
#   2. Auto-heal any failures
#   3. Open a PR with the fixes for review

Run heal in CI mode locally (test without pushing)

lisa-agent heal --ci --model gemini
# Runs the full heal loop, then attempts to commit + open PR.
# Without GITHUB_TOKEN set, PR creation is gracefully skipped.

Full CI/CD pipeline with Control Plane

lisa-agent heal --command "npm test" --model gemini --project-id "prod-api"
lisa-agent unit --model gemini --project-id "prod-api"
lisa-agent e2e --model gemini --project-id "prod-api"
lisa-agent integration --model gemini --project-id "prod-api"
lisa-agent audit --model gemini --project-id "prod-api"

Requirements

• Node.js 18+
• At least one LLM API key (Gemini, Claude, or OpenAI)
• A JavaScript/TypeScript project with a test suite

Built by the Lisa.ai Platform team.