noui-setup

name	noui-setup
description	Use this skill when the user wants to set up the NoUI project for the first time, install dependencies, configure the environment, load the Chrome extension, or prepare to run any NoUI skill. Triggers on "set up NoUI", "install NoUI", "configure noui", "load the Chrome extension", "first time setup", "get NoUI running", or "I want to start using NoUI".

NoUI Setup

One-time environment setup for the NoUI project. Run this before any other NoUI skill.

All commands run from the noui/ directory (the repo root).

---

Critical Rules (Never Violate)

• ALWAYS use .venv/bin/python cli/main.py for all CLI invocations — never the system python or python3
• NEVER run pip install individual packages — all deps are managed by poetry install --no-root
• NEVER run pip install -e . — the project uses package-mode = false in pyproject.toml and does not support editable installs
• ALWAYS copy .env.example to .env and set ANTHROPIC_API_KEY before running the backend
• ALWAYS load the extension from noui/extension/ in Developer mode — the packed install path does not work

---

Step 1 — Create the Virtual Environment

python3 -m venv .venv

Creates .venv/ in the repo root. All subsequent commands use .venv/bin/python.

If python3 --version returns something older than 3.11, use python3.11 -m venv .venv or python3.12 -m venv .venv explicitly (both are supported; the project requires >=3.11).

---

Step 2 — Install Dependencies

.venv/bin/python -m pip install poetry
.venv/bin/python -m poetry install --no-root

--no-root is required because pyproject.toml sets package-mode = false. All runtime deps (FastAPI, FastMCP, Anthropic SDK, SQLAlchemy, httpx, etc.) are installed into .venv.

Common errors:

Error	Fix
ModuleNotFoundError: No module named 'poetry'	Re-run the pip install poetry step above
python3: command not found or version < 3.11	Install Python 3.11 or 3.12 via your OS package manager, then re-create the venv with that interpreter
This build backend cannot be used in 'editable' mode	You ran pip install -e . — use poetry install --no-root instead

---

Step 3 — Configure Environment Variables

cp .env.example .env

Open .env and fill in:

Variable	Required	Purpose
ANTHROPIC_API_KEY	Yes	Powers the MCP compiler's LLM calls
TABBY_API_HOST	Auth flows only	Tabby endpoint (default: http://localhost:8080)
TABBY_ADMIN_TOKEN	Auth flows only	Admin token for provisioning Tabby profiles
NOUI_PORT	No	Backend port (default: 8002)

If you only need unauthenticated app support, ANTHROPIC_API_KEY is the only required field.

---

Step 4 — Load the Chrome Extension

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer mode (toggle, top-right corner)
3. Click Load unpacked
4. Select the noui/extension/ directory
5. The NoUI Workflow Recorder icon appears in the Chrome toolbar

If the icon does not appear, click the puzzle-piece Extensions menu and pin it.

Verify: Click the icon — you should see the NoUI popup with recording mode options.

---

Step 5 — Verify the Installation

.venv/bin/python cli/main.py status

Expected output when the backend has not yet been started:

NoUI backend:
  Not reachable at http://localhost:8002

This confirms Python, the venv, and all imports are working. The backend not running at this point is expected.

---

Decision Flow

Start
  │
  ├─ Does .venv/ exist?
  │     ├─ No  → Step 1: python3 -m venv .venv
  │     └─ Yes → skip
  │
  ├─ Are deps installed?
  │     ├─ No  → Step 2: pip install poetry + poetry install --no-root
  │     └─ Yes → skip
  │
  ├─ Does .env exist?
  │     ├─ No  → Step 3: cp .env.example .env + fill in ANTHROPIC_API_KEY
  │     └─ Yes → verify ANTHROPIC_API_KEY is set
  │
  ├─ Is Chrome extension loaded?
  │     ├─ No  → Step 4: Load unpacked from noui/extension/
  │     └─ Yes → skip
  │
  └─ Step 5: .venv/bin/python cli/main.py status
       └─ Ready → proceed to /record-login or /record-workflow

---

CLI Command Reference

Command	Purpose
.venv/bin/python cli/main.py status	Verify backend reachability and session counts
.venv/bin/python cli/main.py start	Start the FastAPI backend on port 8002
.venv/bin/python cli/main.py stop	Stop the backend
.venv/bin/python cli/main.py tabby status	Check Docker Compose services and Tabby API liveness
.venv/bin/python cli/main.py tabby start	Start Docker Compose infra and Tabby API
.venv/bin/python cli/main.py tabby stop [--infra]	Stop the Tabby API (and optionally Docker Compose)
.venv/bin/python cli/main.py tabby setup	Full Tabby provisioning: agent client + ServiceProfiles + write TABBY_* to .env
.venv/bin/python cli/main.py tabby session status	Show browser session state for configured profiles
.venv/bin/python cli/main.py tabby session ensure	Ensure a HEALTHY browser session exists
.venv/bin/python cli/main.py tabby session stop	Stop the locally-running worker

Tabby setup — for authenticated app workflows, run tabby start then tabby setup (interactive) to provision agent credentials and ServiceProfiles. This writes TABBY_CLIENT_ID, TABBY_CLIENT_SECRET, and TABBY_API_URL to .env. You still need TABBY_ADMIN_TOKEN (or ADMIN_BOOTSTRAP_EMAIL/ADMIN_BOOTSTRAP_PASSWORD in tabby/.env.local) for the provisioning step.

---

Troubleshooting

Symptom	Fix
ImportError or ModuleNotFoundError on cli/main.py	Deps not installed — re-run poetry install --no-root
.env not found error from backend	Run cp .env.example .env from the noui/ directory
Extension shows "Manifest file is missing"	Confirm you selected noui/extension/ (the dir containing manifest.json)
Extension loads but popup is blank	Check chrome://extensions/ for errors; remove and re-load unpacked
Port 8002 already in use on start	lsof -i :8002 to find conflicting process; set NOUI_PORT=8003 in .env to use another port
Generated tool raises "No Tabby page matching ..."	Open the target site in the Tabby browser, or tabby session ensure --profile <slug>
Generated tool raises Connection refused on port 9222	Tabby's CDP endpoint is down — tabby session ensure --profile <slug>