GhostFlow CLI

Caution

Experimental Product: GhostFlow is currently in an experimental phase. Expect breaking changes and potentially unstable behavior. Use with caution in production environments.

👻 GhostFlow: A ghost user that runs real user flows to validate your website.

GhostFlow is an AI-powered CLI tool designed to simulate real user interactions on your website. By combining the power of Playwright for browser automation and Large Language Models (LLM) via LM Studio, GhostFlow can plan, execute, and validate complex user flows based on simple natural language prompts.

Features

• 🤖 AI-Driven Planning: Automatically generates test steps from a natural language prompt.
• 👁️ Vision-Capable: Uses vision models to observe the website state and make decisions.
• 🎭 Real Browser Interaction: Powered by Playwright for reliable web automation.
• 🛠️ Configurable: Easy-to-use CLI options for URLs, prompts, models, and headless mode.
• 📸 Automated Screenshots: Captures screenshots during the flow for debugging and reporting.

Prerequisites

• Node.js: Version 18 or higher.
• LM Studio: Running locally to provide the LLM backend.
• Vision Model: A vision-capable model (like qwen2-vl or llama-3.2-vision) loaded in LM Studio is recommended for best results.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd 018_ghostflow/cli

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

Getting Started

1. Start LM Studio:

   • Open LM Studio.
   • Load a vision-capable model (e.g., qwen2-vl-4b-instruct).
   • Start the Local Server (default: ws://localhost:1234).

2. Run a GhostFlow Test:

   pnpm start run --url "https://example.com" --prompt "Go to the login page and try to sign in with invalid credentials."

Usage

ghostflow run [options]

Options

Alternative	Description	Default
-u, --url <url>	(Required) The target URL to test	-
-p, --prompt <prompt>	(Required) The user flow requirement/prompt	-
-m, --model <model>	LLM model ID to use (from LM Studio)	qwen3-vl-2b-instruct
--headless	Run browser in headless mode	true
--no-headless	Run browser in headed mode (visible)	-
-v, --version	Output the version number	-
-h, --help	Display help for command	-

Configuration

Default settings can be found and modified in src/lib/config/index.ts. Key configurations include:

• LLM Settings: Base URL, temperature, max tokens, and vision capability.
• Browser Settings: Viewport size, timeouts, and screenshot directory.
• Behavior Settings: Delays for clicking and typing, and retry counts.

Project Structure

• src/index.ts: CLI entry point.
• src/orchestrator.ts: Manages the overall flow execution.
• src/planner.ts: AI-based step planning.
• src/runner.ts: Executes actions via Playwright.
• src/observer.ts: Analyzes the page state using vision/LLM.
• src/lib/config/: Configuration management.

License

MIT