@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 | |---|---|---| | Anthropic Claude | ANTHROPIC_API_KEY | claude-haiku-4-5 | | Google Gemini | GOOGLE_GENERATIVE_AI_API_KEY | gemini-2.0-flash | | OpenAI | OPENAI_API_KEY | gpt-4o-mini |

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

Quick Start

# 1. Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# 2. (Optional) Create project config
lisa-agent init

# 3. Heal broken tests
lisa-agent heal

# 4. Generate missing unit tests
lisa-agent unit

# 5. Generate E2E tests
lisa-agent e2e

Zero config required. The agent auto-detects your test framework, package manager, and builds the correct commands automatically.

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

# 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 in CI mode (commit + open PR)
lisa-agent heal --ci

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 threshold, discovers source files with no tests at all, and generates new test specs to close the gaps.

lisa-agent unit

# 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 files from coverage report and source files with no spec at all
4. Generates unit test specs targeting uncovered code via LLM
5. If generated tests fail, delegates to the heal loop automatically
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

# 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

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

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

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

chat — Interactive Mode

Multi-turn interactive REPL with streaming LLM responses. Ask questions about your project, analyze test failures, heal specific files, and generate tests — all in a conversational loop.

lisa-agent chat

# Use a specific LLM provider
lisa-agent chat -m claude

Slash commands:

| Command | Description | |---|---| | /read <file> | Load a file into conversation context | | /write <file> | Save last code block from Lisa's response to a file | | /test [cmd] | Run tests and show results | | /explain <file> | Analyze why a test is failing (no file changes) | | /heal <file> | Auto-heal a specific failing test file | | /generate <file> | Generate test spec for a source file | | /status | Show test pass/fail summary | | /help | Show available commands | | /exit | Exit chat |

Example session:

lisa> /read src/services/auth.service.ts
  ✓ Loaded auth.service.ts (142 lines) into context

lisa> write a unit test for this file
[streams a test based on the actual file content]

lisa> /write src/app/services/auth.service.spec.ts
  ✓ Saved to src/app/services/auth.service.spec.ts (48 lines)

lisa> /test
Running: npx ng test --no-watch --browsers=ChromeHeadless...
✗ 3 of 47 tests failed

lisa> /heal src/app/services/auth.service.spec.ts
Healing src/app/services/auth.service.spec.ts...
✅ Healed via Cloud.

lisa> /status
[████████████████████] 100%  ✅ 47 passed  47 total

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

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).

| Provider | Secret name | |---|---| | Claude | ANTHROPIC_API_KEY | | Gemini | GOOGLE_GENERATIVE_AI_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) 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:

{
  "projectId": "my-project-123",
  "provider": "claude",
  "model": "claude-haiku-4-5",
  "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"],
  "lisaLlm": {
    "enabled": true,
    "model": "qwen2.5-coder:7b"
  }
}

| Field | Type | Description | |---|---|---| | projectId | string | Control Plane project ID — saves you from passing --project-id every time | | 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 file (default 5) | | skipFiles | string[] | Filenames to exclude from analysis | | skipDirs | string[] | Directory names to exclude | | skipPaths | string[] | Path prefixes to exclude | | lisaLlm | object | Lisa LLM local tier config (see below) |

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

Lisa LLM — Local-First Tier (v2.10.0)

Lisa LLM adds a local LLM tier (Ollama or any OpenAI-compatible server) that attempts fixes before calling cloud APIs. When the Memory Engine has a high-confidence proven fix pattern, the agent tries the local model first — zero API cost. Falls back to cloud on failure.

Enable via .lisai.json:

{
  "lisaLlm": {
    "enabled": true,
    "provider": "ollama",
    "model": "qwen2.5-coder:7b",
    "baseUrl": "http://localhost:11434",
    "confidenceThreshold": 0.8
  }
}

Or via environment variables:

LISA_LLM_ENABLED=true
LISA_LLM_MODEL=qwen2.5-coder:7b
LISA_LLM_URL=http://localhost:11434

| Field | Default | Description | |---|---|---| | enabled | false | Opt-in. Set true or LISA_LLM_ENABLED=true | | provider | "ollama" | Any OpenAI-compatible server works (LM Studio, LocalAI, vLLM) | | model | "qwen2.5-coder:7b" | Swappable — deepseek-coder-v3, codestral, etc. | | baseUrl | "http://localhost:11434" | Ollama default. Override for other servers | | confidenceThreshold | 0.8 | Minimum pattern confidence to trigger local tier |

How it works:

1. Memory Engine returns proven patterns with confidence scores
2. If confidence >= threshold and Lisa LLM is enabled → Tier 1 (local) attempt
3. Local fix verified → done (zero API cost, logged as resolvedBy: 'lisa-llm')
4. Local fix fails → falls through to Tier 2 (cloud) — doesn't burn a retry
5. No high-confidence patterns → skip local, go directly to cloud

Requirements: Ollama running locally with a code model pulled:

ollama pull qwen2.5-coder:7b

Dashboard: The project page shows a "Lisa LLM vs Cloud" breakdown card with resolution counts and success rate when Lisa LLM data exists.

.env File

The agent loads .env from your project root (the directory where you run the command). You can put all config here:

ANTHROPIC_API_KEY=sk-ant-your-key-here
LISA_CLAUDE_MODEL=claude-sonnet-4-6
LISA_CONTROL_PLANE_URL=http://localhost:3088

Config Priority

Settings are resolved in this order (highest wins):

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

.lisai.json overrides Control Plane defaults for maxRetries and provider, so you can always fine-tune locally even when connected to the Dashboard.

Control Plane Integration

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

// .lisai.json
{
  "projectId": "my-project-123",
  "provider": "claude"
}

lisa-agent heal    # automatically uses projectId from .lisai.json

Or via CLI flag:

lisa-agent heal --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 projectId)
• Supports hybrid vector + exact search for semantically similar error matching

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 ANTHROPIC_API_KEY="sk-ant-..."
lisa-agent heal

Generate unit tests for uncovered files

lisa-agent unit

Generate Playwright E2E tests

lisa-agent e2e

Target specific files (skip discovery for large projects)

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

GitHub Actions CI — auto-heal on every push

# One-time setup
lisa-agent init-ci --model claude

# Add your API key as a GitHub secret:
#   Repo > Settings > Secrets > Actions > ANTHROPIC_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

Full pipeline with Control Plane

lisa-agent heal --project-id "prod-api"
lisa-agent unit --project-id "prod-api"
lisa-agent e2e --project-id "prod-api"
lisa-agent integration --project-id "prod-api"
lisa-agent audit --project-id "prod-api"

Requirements

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

License

ISC

Built by the Lisa.ai team.