Awel

Awel

English | [中文](./README.zh-CN.md)

AI-powered development overlay for Next.js. Awel runs a proxy in front of your dev server, injects a floating chat button into your app, and lets you talk to an AI agent that can read, write, and edit files in your project — all from an embedded dashboard.


Quick Start

Create a new project

# Set up at least one AI provider (pick one):
export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic API
export OPENAI_API_KEY="sk-..."          # OpenAI
export GOOGLE_GENERATIVE_AI_API_KEY="..." # Google AI
# Or install the Claude CLI: https://docs.anthropic.com/en/docs/claude-code

npx awel create

This scaffolds a new Next.js project and marks it for creation mode. Follow the instructions to `cd` into the project and run `npx awel dev`. You'll see a full-page creation UI where you describe what you want to build — the AI agent generates the entire app for you, then transitions to the normal Awel overlay.

Use with an existing project

cd my-existing-next-app
npx awel dev

Awel needs at least one configured provider to function. See [Supported Models](#supported-models) for the full list.

This starts Awel on port 3001 and proxies your Next.js dev server on port 3000. Open `http://localhost:3001` to see your app with the Awel overlay.

Commands

awel create              Create a new Next.js project with Awel
awel dev [options]       Start the development server with Awel overlay

  -p, --port     Target app port (default: 3000)
  -v, --verbose        Print LLM stream events to stderr
  --no-open            Do not open browser automatically

How It Works

Awel sits between your browser and your dev server:

Browser → Awel (proxy on :3001) → Your app (dev server on :3000)

1. Awel intercepts HTML responses and injects a small script into the page
2. The script renders a floating button (bottom-right corner, isolated via Shadow DO