@katatan/agents

@katatan/agents

KATATAN's AI agent set.
A single command npx @katatan/agents init sets up a workflow where AI coding agents automatically plan, implement, run, and fix E2E tests.

Overview

What are KATATAN AI Agents?

KATATAN AI Agents are a set of agents for delegating Playwright-based E2E testing to AI.
Just tell the agent "create tests for the login feature" and it will generate, run, and fix test code while operating the browser.

Internally, 5 specialized agents work together:

Agent	Role
katatan-supervisor	The entry point that interacts directly with the user. Interprets instructions and calls other agents
katatan-e2e-planner	Explores the browser to investigate the UI. Registers Dictionary entries and TestCases in KATATAN
katatan-e2e-generator	Generates Playwright TypeScript test code from TestCases
katatan-e2e-runner	Runs tests and records results in KATATAN
katatan-e2e-healer	Analyzes failed tests, fixes the code, and re-runs

What is MCP (Model Context Protocol)?

MCP is a standard protocol for AI agents to connect to external tools and services.
This package configures the following 2 MCP servers:

Server	Role
katatan-test	Manages TestSpecs, TestCases, Dictionaries, and TestReports in KATATAN
playwright	Handles browser operations (page navigation, snapshot capture, clicking, etc.)

Supported AI Clients

Client	Config File
Claude Code	.claude/agents/ + .mcp.json
VS Code (GitHub Copilot)	.vscode/mcp.json
Cursor	.cursor/mcp.json
Kiro (Amazon)	.kiro/settings/mcp.json
Google Antigravity	~/.gemini/antigravity/mcp_config.json (global) + .agents/skills/

Setup

Option A: Claude Code Plugin Marketplace (Claude Code only)

The easiest way if you use Claude Code. No npx command required.

1. Set your KATATAN API token as an environment variable

Add the following to your ~/.bashrc, ~/.zshrc, or equivalent:

export KATATAN_API_KEY=kat_xxxxxxxxxxxxxxxx

Tokens are available from the KATATAN settings page.

2. Add the marketplace and install the plugin

Run the following inside Claude Code:

/plugin marketplace add katatan-org/katatan-TEST
/plugin install katatan-agents@katatan

3. Use it

/katatan-agents:katatan-supervisor Create E2E tests for the login page

Option B: npx init (all clients)

Supports Claude Code, VS Code (GitHub Copilot), Cursor, Kiro, and Google Antigravity.

1. Run the setup command

Run the following in the root directory of the project you want to test:

npx @katatan/agents init

Requires Node.js 18 or later.

2. Select an AI client

Step 1: Select an AI client
  1. Claude Code           .claude/agents/ + .mcp.json
  2. VS Code (GitHub Copilot)  .vscode/mcp.json
  3. Cursor                .cursor/mcp.json
  4. Kiro (Amazon)         .kiro/settings/mcp.json
  5. Google Antigravity    ~/.gemini/antigravity/mcp_config.json + .agents/skills/

Select client(s) (comma-separated, Enter for all) > 1,2

You can select multiple clients with comma separation. Pressing Enter alone selects all clients.

3. Enter your KATATAN access token

Step 2: Enter your KATATAN access token
  Available from the KATATAN settings page (https://app.katatan.com/)
  Token > kat_xxxxxxxxxxxxxxxx

Access tokens can be obtained from the KATATAN settings page.

4. Done

Config files for the selected clients are auto-generated.
If Playwright is not yet installed, you will be prompted to install it.

Generated Files

Claude Code

.claude/
└── agents/
    ├── katatan-supervisor.md
    ├── katatan-e2e-planner.md
    ├── katatan-e2e-generator.md
    ├── katatan-e2e-runner.md
    └── katatan-e2e-healer.md
.mcp.json

VS Code (GitHub Copilot)

.vscode/
└── mcp.json

Cursor

.cursor/
└── mcp.json

Kiro (Amazon)

.kiro/
└── settings/
    └── mcp.json

Google Antigravity

~/.gemini/antigravity/mcp_config.json  ← global config (merged with existing)

.agents/
└── skills/
    ├── katatan-supervisor/SKILL.md
    ├── katatan-e2e-planner/SKILL.md
    ├── katatan-e2e-generator/SKILL.md
    ├── katatan-e2e-runner/SKILL.md
    └── katatan-e2e-healer/SKILL.md

Usage

Claude Code

• Open the project in Claude Code
• Talk to @katatan-supervisor

@katatan-supervisor Create E2E tests for the login page

VS Code (GitHub Copilot)

• Open "MCP: List Servers" in the command palette and enable katatan-test and playwright
• Give instructions in Copilot Chat (agent mode)

Cursor

• Restart Cursor to apply settings
• Give instructions in Agent mode

Kiro (Amazon)

• Restart Kiro to apply settings
• Give instructions in Agent mode

Google Antigravity

• Restart Antigravity to apply settings
• Talk to the katatan-supervisor skill

How It Works

User
  │ "Create E2E tests for the login feature"
  ▼
katatan-supervisor (interprets instructions and calls sub-agents)
  │
  ├─▶ katatan-e2e-planner
  │     Explore browser → Register Dictionary → Register TestCases
  │
  ├─▶ katatan-e2e-generator
  │     TestCases → Generate Playwright TypeScript code → Create TestReport
  │
  ├─▶ katatan-e2e-runner
  │     Run tests → Record results in KATATAN
  │
  └─▶ katatan-e2e-healer (only on failure)
        Analyze failure → Fix code → Re-run

Requirements

• Node.js 18 or later
• KATATAN account and access token
• One of the supported AI clients