effing-use 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Obubelebra Amachree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# effing-use — stop paying 19.5 KB every session for browser control
+
+Full Chromium automation in **3 tools, 3.9 KB**. Same pages, same clicks, same scrapes — without the 24-tool handshake eating your context window before you load a page.
+
+**Measured, not marketed:** `tools/list` is **3,913 bytes** here vs **19,517 bytes** for `@playwright/mcp@latest` (~5x smaller, ~15.6 KB saved every session). Local ops stay in milliseconds — snapshot ~15 ms, extract ~50 ms, batch ~65 ms, screenshot ~60–190 ms. Page loads still cost seconds (network, not us). Full numbers in [`docs/COMPARISON.md`](docs/COMPARISON.md).
+
+## Install (Bun-only)
+
+Requires [Bun](https://bun.sh) 1.4+. The `playwright` npm package ships the driver, **not** the browser — every user needs Playwright's version-pinned Chromium (~150 MB) once:
+
+```bash
+bunx effing-use --help        # after: bun publish (runs src/index.ts via bin)
+# or from source:
+bun install
+bunx playwright install chromium --only-shell   # one-time Chromium download
+bun src/index.ts              # STDIO (single editor)
+bun src/http.ts               # HTTP on :3000 (/mcp) — shared across editors
+```
+
+Re-run `bunx playwright install chromium --only-shell` whenever you bump the `playwright` dependency (each Playwright version pins its own browser build). Verify with `bunx playwright install --dry-run chromium` or check `~/.cache/ms-playwright/`.
+
+**Why Chromium is separate:** Playwright supports multiple browsers and updates its pinned builds every release, so the binary can't live inside the npm tarball (ours is 16 kB). Docker users skip this — Chromium is baked into the `mcr.microsoft.com/playwright` base image.
+
+## Run it in 60 seconds (recommended path)
+
+**Step 1/3 — Start the server.** One server, every local editor:
+
+```bash
+bun install
+bunx playwright install chromium --only-shell
+docker compose up --build -d
+curl http://localhost:3000/healthz
+```
+
+Point any VS Code instance at `http://localhost:3000/mcp` (see `.vscode/mcp.json` → `effing-use (http)`). Plain HTTP on loopback is intentional — add TLS at the edge for remote use.
+
+**Step 2/3 — Connect.** STDIO for one editor, HTTP for all of them:
+
+```json
+{
+  "mcpServers": {
+    "computer-use": {
+      "command": "bun",
+      "args": ["/path/to/litepilot/src/index.ts"]
+    }
+  }
+}
+```
+
+Or HTTP: `http://localhost:3000/mcp`.
+
+**Step 3/3 — Drive.** Search Wikipedia in one call instead of two round-trips:
+
+```jsonc
+// browser_act batch: fill + press in 65 ms measured
+{
+  "action": "batch",
+  "steps": [
+    { "action": "fill", "target": "input[name=search]", "value": "Playwright" },
+    { "action": "press", "target": "input[name=search]", "value": "Enter" },
+  ],
+}
+```
+
+No Docker? `bun src/index.ts` (STDIO) or `bun src/http.ts` (`:3000` `/mcp`) works directly.
+
+## Why agents prefer 3 tools
+
+- 🪶 **Tiny handshake, full surface** — `browser_act` (27 actions), `browser_observe` (8 kinds), `browser_extract` (7 kinds). No schema bloat, no guessing which of 24 tools to call.
+- 🧠 **Context-safe by default** — snapshots capped at `OUTPUT_MAX_CHARS` (default 4000); full YAML/text saved under `.browser-use/`, never dumped inline. HN snapshot: 4,034-char preview, full file on disk.
+- 🖼️ **File paths, not base64** — screenshots, PDFs, traces return paths like `.browser-use/shot-*.png`. Read the file only when needed.
+- ⚡ **One call, not five** — `batch` runs fill+press flows in one turn (max 20 steps, stops on first error). `goal` plans or returns `E_GOAL_UNCLEAR` + `suggestedSteps` instead of hallucinating.
+- 🐳 **Shared, not spawned** — one Docker server serves every local VS Code instance. No per-client `npx` spawn.
+
+## The loop (agents: follow this order)
+
+1. `browser_observe` kind=`snapshot` → get `[eN]` refs (never guess refs, re-snapshot after navigation)
+2. `browser_act` to interact — prefer `batch` with `steps[]`
+3. `browser_observe` kind=`screenshot` → verify visually (you get a path)
+4. `browser_extract` kind=`text`|`table`|`query` → scrape structured data
+
+## Tools
+
+- `browser_act` — open/goto, click, dblclick, fill, type, press, select, check/uncheck, hover, drag, upload, scroll, back/forward/reload, wait, dialog_accept/dismiss, tabs (new/select/close), resize, close, `goal`, `batch`
+- `browser_observe` — snapshot (e-refs), screenshot (path), url, title, console (last N), network (method/url/status ring), tabs, focused
+- `browser_extract` — text, html, table (≤100 rows JSON), query (text|href|json), pdf, trace_start/stop
+
+Errors are always `{ ok: false, code, message, hint }` with `E_NOT_FOUND | E_TIMEOUT | E_NO_PAGE | E_BAD_INPUT | E_GOAL_UNCLEAR` — never a stack trace.
+
+## effing-use vs Playwright MCP
+
+|                  | effing-use                      | Playwright MCP                                             |
+| ---------------- | ------------------------------- | ---------------------------------------------------------- |
+| `tools/list`     | **3,913 bytes / 3 tools**       | **19,517 bytes / 24 tools**                                |
+| Snapshot         | capped 4 KB preview + full file | full accessibility tree                                    |
+| Screenshots/PDFs | file paths                      | inline or output dir                                       |
+| Browsers         | Chromium (headless in Docker)   | Chromium, Firefox, WebKit, Edge + vision/pdf/devtools caps |
+
+Need Firefox/WebKit, device emulation, or persistent profiles? Use Playwright MCP. Need context budget for Chromium work? Stay here. Full breakdown in [`docs/COMPARISON.md`](docs/COMPARISON.md).
+
+## Config
+
+Env defaults in [`.env.example`](.env.example): `BROWSER_HEADLESS`, `BROWSER_VIEWPORT_W/H`, `BROWSER_TIMEOUT_MS`, `OUTPUT_DIR` (`.browser-use/`, gitignored), `OUTPUT_MAX_CHARS`, `ALLOW_EVAL`.
+
+Agent skill: `skills/effing-use/SKILL.md` (skills.sh-ready).
+
+## Verify
+
+```bash
+bunx tsc --noEmit   # 0 errors
+bun test            # 6 pass
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "effing-use",
+  "version": "0.1.0",
+  "description": "Token-efficient browser control: 3 tools (act, observe, extract) built with tmcp + Bun + Playwright",
+  "license": "MIT",
+  "author": "Michael Obubelebra Amachree",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michael-Obele/litepilot.git"
+  },
+  "homepage": "https://github.com/Michael-Obele/litepilot#readme",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "effing-use": "src/index.ts",
+    "effing-use-http": "src/http.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun src/index.ts",
+    "start:http": "bun src/http.ts",
+    "dev": "bun --watch src/index.ts",
+    "dev:http": "bun --watch src/http.ts",
+    "check": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "playwright",
+    "browser-automation",
+    "tmcp",
+    "chromium"
+  ],
+  "dependencies": {
+    "@tmcp/adapter-valibot": "^0.1.6",
+    "@tmcp/transport-http": "^0.9.0",
+    "@tmcp/transport-stdio": "^0.5.0",
+    "playwright": "^1.63.0",
+    "tmcp": "^1.20.0",
+    "valibot": "^1.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  }
+}

package/skills/effing-use/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: effing-use
+description: Drive a headless Chromium browser through 3 token-efficient MCP tools (browser_act, browser_observe, browser_extract). Use when automating web pages, scraping structured data, screenshotting UIs, filling forms, or testing web flows.
+license: MIT
+compatibility: Requires the effing-use MCP server (Bun + Playwright Chromium). Works over stdio or Streamable HTTP at /mcp.
+metadata:
+  repo: Michael-Obele/litepilot
+  tools: browser_act,browser_observe,browser_extract
+---
+
+# effing-use — token-efficient browser control
+
+Three tools cover 100% of the interaction surface at ~4–10x lower token
+cost than 21-tool browser servers. `tools/list` is ~3.9KB.
+
+## The loop (always follow this order)
+
+1. `browser_observe` with `kind: "snapshot"` → get `[eN]` refs.
+2. `browser_act` to interact (`open`, `click`, `fill`, `type`, `press`, `select`, `check`, `wait`, …).
+3. `browser_observe` with `kind: "screenshot"` → verify visually (returns a file path).
+4. `browser_extract` with `kind: "text" | "table" | "query"` → scrape.
+
+Rules:
+
+- Never guess refs. Re-snapshot after every navigation.
+- Prefer `batch`: one `browser_act` with `steps[]` for fill+press flows (max 20 steps, stops on first error).
+- Large outputs are files under `.browser-use/` (gitignored). Read the path, not the preview.
+- Snapshots are capped at `OUTPUT_MAX_CHARS` (default 4000) with `…[truncated N chars, see file]`.
+
+## Tool cheat sheet
+
+**browser_act** — `action` + optional `target` (e-ref, `role=` selector, or CSS) + `value`:
+`open`/`goto` (URL in `value`), `click`, `dblclick`, `fill`, `type`,
+`press` (key like `Enter`), `select`, `check`/`uncheck`, `hover`,
+`drag` (start in `target`, end in `value`), `upload` (comma-separated paths in `value`),
+`scroll` (`up`/`down`/`top`/`bottom` or a target), `back`/`forward`/`reload`,
+`wait` (`ms:500`, `text:Saved`, or a ref), `dialog_accept`/`dialog_dismiss` (arm before the triggering step),
+`resize` (`1280x800` in `value`), `tab_new`/`tab_select`/`tab_close`, `close`,
+`goal` (deterministic add-todo/search planner, else `E_GOAL_UNCLEAR` + `suggestedSteps`),
+`batch` (needs `steps[]`).
+
+**browser_observe** — read-only: `snapshot` (e-refs), `screenshot` (file path,
+`full` page by default), `url`, `title`, `console` (last N, `limit`),
+`network` (method/url/status ring), `tabs`, `focused` (activeElement HTML).
+
+**browser_extract** — `text`, `html`, `table` (≤100 rows as JSON),
+`query` (`selector` + `mode: text|href|json`), `pdf` (headless Chromium only),
+`trace_start`/`trace_stop` (Playwright trace zip).
+
+Errors always come back as `{ ok: false, code, message, hint }` with codes
+`E_NOT_FOUND | E_TIMEOUT | E_NO_PAGE | E_BAD_INPUT | E_GOAL_UNCLEAR` — never a stack trace.
+
+## Setup
+
+See [references/setup.md](references/setup.md) for install (local Bun,
+Docker, VS Code `mcp.json` entries), port config (`ECU_PORT`), and the
+`.browser-use/` gitignore contract. See [references/troubleshooting.md](references/troubleshooting.md)
+for port conflicts, Chromium sandbox notes, and the `doQuery` arity lesson.

package/skills/effing-use/references/setup.md

@@ -0,0 +1,89 @@
+# Setup — effing-use
+
+## Prerequisites
+
+- [Bun](https://bun.sh) 1.4+ (`bun --version`)
+- Docker 29+ with Compose v2 (only for the container route)
+- Chromium system deps — handled by `bunx playwright install chromium`
+  locally, or baked into the `mcr.microsoft.com/playwright:v1.63.0-noble`
+  base image in Docker.
+
+## Option A — local Bun (single VS Code instance)
+
+```bash
+bun install
+bunx playwright install chromium --only-shell
+bun src/index.ts          # STDIO transport
+bun src/http.ts           # Streamable HTTP on $PORT (default 3000), MCP at /mcp
+```
+
+VS Code `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "effing-use (stdio)": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["/path/to/effing-use/src/index.ts"],
+      "cwd": "/path/to/effing-use",
+      "env": {
+        "BROWSER_HEADLESS": "true",
+        "OUTPUT_DIR": "/path/to/effing-use/.browser-use"
+      }
+    },
+    "effing-use (http)": { "type": "http", "url": "http://localhost:3123/mcp" }
+  }
+}
+```
+
+## Option B — Docker (shared across VS Code instances)
+
+```bash
+ECU_PORT=3123 docker compose up --build -d
+curl http://localhost:3123/healthz   # {"ok":true,"name":"effing-use"}
+```
+
+Then point any local client at `http://localhost:<ECU_PORT>/mcp`.
+The container listens on 3000 internally; only the host-side port moves.
+
+- `restart: unless-stopped` — survives daemon restarts and host reboots
+  once started with `up -d`.
+- `init: true` + `ipc: host` — Playwright's recommended flags (no PID-1
+  zombies, no Chromium `/dev/shm` crashes).
+- `.browser-use/` is bind-mounted so snapshots/screenshots land on the host.
+- Plain HTTP on loopback is intentional. For remote use, terminate TLS at
+  the edge (reverse proxy, Cloudflare Tunnel, Tailscale) — never bake certs
+  into the image.
+
+## Environment
+
+All optional; defaults shown (see `.env.example`):
+
+| Var                    | Default        | Notes                                          |
+| ---------------------- | -------------- | ---------------------------------------------- |
+| `PORT`                 | `3000`         | `src/http.ts` listen port (container-internal) |
+| `ECU_PORT`             | `3000`         | compose host-side port override                |
+| `BROWSER_HEADLESS`     | `true`         | Docker supports headless Chromium only         |
+| `BROWSER_VIEWPORT_W/H` | `1280/800`     |                                                |
+| `BROWSER_TIMEOUT_MS`   | `15000`        | per-action Playwright timeout                  |
+| `OUTPUT_DIR`           | `.browser-use` | all file outputs land here                     |
+| `OUTPUT_MAX_CHARS`     | `4000`         | inline cap; full text goes to the file         |
+| `ALLOW_EVAL`           | `false`        | no raw JS eval path unless explicitly enabled  |
+
+## Gitignore contract
+
+`.browser-use/`, `*.png`, `*.pdf`, `node_modules/` stay out of git.
+Any local planning/scratch folder (e.g. `docs/plan/`) should also be gitignored —
+it holds the build spec, not shippable code.
+
+## Verify
+
+```bash
+bunx tsc --noEmit   # 0 errors
+bun test            # unit green
+curl -s -X POST http://localhost:3123/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | head -c 300
+```

package/skills/effing-use/references/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting — effing-use
+
+## Port already in use
+
+Port 3000 is a popular squat (e.g. other MCP servers). Diagnose:
+
+```bash
+ss -tlnp | grep -E ':3000|:3123'
+docker ps --format "{{.Names}} {{.Ports}}"
+```
+
+Fix — move our host port, never the container's:
+
+```bash
+ECU_PORT=3123 docker compose up -d   # client → http://localhost:3123/mcp
+PORT=3123 bun src/http.ts            # local Bun route
+```
+
+## Chromium won't launch in Docker
+
+- Keep `ipc: host` (Chromium crashes on small `/dev/shm` without it).
+- Keep `init: true` (avoids PID-1 zombie processes).
+- Headless only in containers. If you see sandbox errors on untrusted
+  sites, run with a non-root user + seccomp profile per
+  <https://playwright.dev/docs/docker> (trusted E2E code is fine as root).
+
+## `bun: not found` during `docker build`
+
+The `curl | bash` Bun installer can break mid-download (`curl: (56)`) yet
+the layer still "succeeds", leaving no binary. The effing-use Dockerfile copies Bun from
+the pinned `oven/bun` image instead — deterministic, no network flakiness:
+
+```dockerfile
+COPY --from=oven/bun:1.4.0 /usr/local/bin/bun /usr/local/bin/bun
+```
+
+## Query extract returns `[]`
+
+`page.locator(sel).evaluateAll(fn)` does **not** forward outer-scope args —
+the second parameter must be passed explicitly:
+
+```ts
+.evaluateAll((els, m: string) => /* … */, mode)
+```
+
+Without it the callback receives `undefined` and (depending on arity
+handling) the call throws inside the page, surfacing as an empty result
+via `.catch(() => [])`. Lesson: always pass `evaluateAll`/`evaluate`
+arguments explicitly; never rely on closure capture across the
+browser boundary.
+
+## Stale snapshot refs (`E_NOT_FOUND`)
+
+Refs are nth-match positions in DOM order — any navigation or re-render
+invalidates them. Fix: re-run `browser_observe kind: "snapshot"` and use
+fresh `eN` values. Fuzzy matching (`fill` with a label) and `role=`
+selectors survive re-renders better than raw `eN` refs.
+
+## Slow external sites timing out
+
+Default action timeout is 15s (`BROWSER_TIMEOUT_MS`). For slow demos,
+either raise it or prefer `wait` with `text:` expectations over fixed
+`ms:` sleeps. For deterministic E2E, serve a local fixture
+(`file:///tmp/…`) instead of depending on the network.