# free-web-ai-worker

**English** · [简体中文](README.zh-CN.md)

**Let your AI coding agent outsource simple text tasks to a free web AI.**

Summarising, translating, classifying, extracting, reformatting — instead of spending your main model's tokens on that, this tool sends the prompt to a free web AI chat through your own Edge/Chrome and returns only the plain-text answer.

```
main agent -> ask_web_ai(prompt) -> your Edge/Chrome -> web AI -> plain text back
```

No API keys. No per-token billing. It drives the browser you already have, in a dedicated, isolated profile.

## Installation

Requires **Node.js >= 20** and **Microsoft Edge or Google Chrome**.

```bash
# Run straight from GitHub
npx -y github:augustlies/free-web-ai-worker ask "Say OK" --json

# Or clone and run locally
git clone https://github.com/augustlies/free-web-ai-worker.git
cd free-web-ai-worker
npm install
node bin/ask-web-ai.js ask "Say OK" --json
```

The first run opens a dedicated browser window with its own profile (`~/.agent-web-ai/`); your everyday browser is never touched.

`duckai` and `qwen` need no account. Providers that need a login are a one-time setup:

```bash
node bin/ask-web-ai.js login --provider deepseek
```

## Usage

```bash
ask-web-ai ask "<prompt>" --json     # ask a web AI, JSON result
ask-web-ai route "<task>"            # is this task worth delegating? (local heuristic, no network)
ask-web-ai providers                 # list available web AIs
ask-web-ai limits                    # today's usage vs the caps
ask-web-ai cache                     # answer cache status
ask-web-ai status                    # browser + profile + defaults
```

Four ways to call it:

- **CLI** — any agent that can run a shell; logs go to stderr, stdout is pure JSON
- **MCP** — exposes one tool, `ask_web_ai({ prompt, provider?, timeout_ms? })` (server: `src/mcp-server.js`)
- **Agent skill** — copy `skills/free-web-ai-worker/` into your skills directory
- **Node module** — `import { askWebAI } from 'free-web-ai-worker'`

Results are structured: success returns `{ status, provider, answer, meta }`; failures return a stable error `code` (e.g. `login_required`, `captcha_required`, `timeout`) plus a screenshot and page snapshot saved under the profile's `artifacts/` folder for debugging.

## Supported web AIs

| Provider | Login | Status |
|---|---|---|
| `duckai` | not needed | Verified |
| `qwen` | not needed (guest mode) | Verified |
| `deepseek` | required | Verified |
| `chatgpt` | required | Selectors only, not verified |
| `grok` | required | Experimental, disabled by default |
| `gemini` | required | Experimental, disabled by default |

Adding a provider is one file in `src/providers/` plus an entry in `config/default.json`.

## Built-in limits

The tool talks to these sites through your own logged-in browser, so it deliberately stays slow and small:

- At least **20s** between calls to the same provider
- **3 min** cooldown after every 8 calls
- **40** calls per provider per day
- **30 min** circuit breaker if a site shows a captcha or a block
- Identical prompts are answered from a **1-hour cache**

It never solves CAPTCHAs, forges logins, or tries to defeat a rate limit — when a site asks for a human, it stops and hands the task back to you. For large batches, use the provider's official API instead.

## Configuration

Defaults live in `config/default.json`; per-machine overrides go in `config/local.json` (git-ignored). Environment variables (`AWA_PROVIDER`, `AWA_TIMEOUT_MS`, `AWA_BROWSER_PORT`, …) override both.

## License

MIT — see [LICENSE](LICENSE).