Zefiro

AI-powered application explorer. Maps web applications through browser automation, producing structured documentation with screenshots and interactive reports.

Installation

npm install -g zefiro
# or
bun add -g zefiro

Quick Start

# 1. Initialize
zefiro init

# 2. Explore a running application
zefiro scan          # static AST scan (optional)

Environment Variables

zefiro init writes the QAI_* variables to your .env. You can also set them manually.

| Variable | Description | |----------|-------------| | QAI_INPUT_SOURCE | Issue tracker: none | jira | linear | | QAI_OUTPUT_TARGET | QA format: markdown | zephyr | both | | QAI_BASE_URL | QA Intelligence API base URL | | OPENAI_API_KEY | OpenAI API key | | ANTHROPIC_API_KEY | Anthropic API key |

Commands

zefiro init

Initialize zefiro in your project. Copies agent templates to .qai/zefiro/agents/ and writes QAI_* variables to .env.

zefiro init
zefiro init --non-interactive   # skip prompts, use defaults

On re-run (.qai/zefiro/agents/ already exists), preserves your existing setup and only updates agents and workflow guide.

After init:

1. Generate .qai/zefiro/context.md using the init-agent prompt in your AI tool, or via MCP (zefiro_scan_codebase)
2. Review the generated context
3. Run zefiro scan

zefiro scan

Scan your codebase AST — extracts routes, components, hooks, imports, and dependencies.

zefiro scan
zefiro scan --scan-dir src/app
zefiro scan --output custom-scan.json
zefiro scan --no-cache

| Option | Description | |--------|-------------| | --output <file> | Output file (default: .qai/zefiro/ast-scan.json) | | --scan-dir <dir> | Directory to scan (overrides config) | | --no-cache | Disable file-level MD5 caching |

zefiro auth

Manage authentication with QA Intelligence.

zefiro auth login    # open browser for OAuth sign-in
zefiro auth logout   # revoke CLI token
zefiro auth status   # show current auth status
zefiro auth switch   # re-authenticate with a different org/project/app

zefiro mcp

Print MCP server setup instructions.

zefiro mcp

Claude Code:

claude mcp add zefiro -- npx -y zefiro-mcp              # project-scoped
claude mcp add zefiro -s user -- npx -y zefiro-mcp      # global

Claude Desktop / other clients:

{
  "mcpServers": {
    "zefiro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "zefiro-mcp"],
      "env": {}
    }
  }
}

Available MCP tools:

| Tool | Description | |------|-------------| | zefiro_explore | Explore a web application via BFS | | zefiro_read_docs | Read generated documentation | | zefiro_scan_codebase | Scan project test infrastructure |

Global Options

-k, --key <KEY>        Issue key context (e.g. PROJ-101, LIN-42)
--provider <provider>  LLM provider: openai | anthropic
--model <model>        LLM model override
--verbose              Verbose output
-v, --version          Show version
-h, --help             Show help

Configuration

For most projects, the .env variables written by zefiro init are sufficient. For advanced setups (custom paths, per-agent model overrides, integrations), create .qai/zefiro/config.ts:

import { defineConfig } from 'zefiro';

export default defineConfig({
  inputSource: 'jira',            // 'none' | 'jira' | 'linear'
  outputTarget: 'markdown',       // 'markdown' | 'zephyr' | 'both'
  baseUrl: 'https://qaligent.space',

  scanner: {
    scanDir: 'src',
    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    exclude: ['**/node_modules/**', '**/dist/**', '**/*.test.*'],
    cacheDir: '.qai/zefiro/scan-cache',
  },

  llm: {
    provider: 'openai',           // 'openai' | 'anthropic'
    model: 'gpt-4o',
    agentModels: {                 // per-agent model overrides
      'feature-analyzer-agent': 'claude-sonnet-4-20250514',
    },
  },

  paths: {
    tests: 'e2e/tests',
    scenarios: 'e2e/scenarios',
    qaOutput: 'qa',
  },

  integrations: {
    zephyr: { titlePrefix: 'UI Automation' },
  },
});

QAI_* env vars take precedence over config.ts values when both are set.

AI Agents

Zefiro ships with agents copied to .qai/zefiro/agents/ on init. Edit them to tune AI behavior for your project.

| Agent | Purpose | |-------|---------| | 1.feature-analyzer-agent | Identifies features, workflows, and components from AST | | 2.scenario-planner-agent | Generates test scenarios for each workflow | | input-agent | Enriches form component input definitions |

Add .qai/zefiro/context.md to inject project-specific context into every agent call.

Project Structure

your-project/
  .env                         # QAI_* variables (written by zefiro init)
  .qai/zefiro/
    config.ts                  # Advanced config (optional)
    context.md                 # Project context for AI agents
    agents/                    # Agent prompts (customizable)
    workflow.md                # Workflow guide
    ast-scan.json              # Latest AST scan output
    scan-cache/                # File-level MD5 cache

Interactive TUI

Running zefiro with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).

zefiro

License

MIT