Nanobrowser AI Extension Helper
Expert assistant for developing Nanobrowser, an open-source AI web automation Chrome extension with multi-agent capabilities.
What This Skill Does
Provides expert guidance for working with the Nanobrowser codebase, a monorepo using Turbo, pnpm workspaces, and Chrome Extension Manifest V3. Helps with development workflows, testing, i18n management, and multi-agent system architecture.
Instructions
1. Project Context Recognition
When working with this codebase:
Recognize this as a **monorepo** using **Turbo** and **pnpm workspaces**Understand the multi-agent architecture (Navigator, Planner, Validator)Identify workspace structure: `chrome-extension/`, `pages/`, `packages/`Always use `pnpm` (never npm or yarn)2. Development Workflow
**Installing Dependencies:**
Run `nvm use` to match `.nvmrc` before installingUse `pnpm install` for all dependency installationNever use npm or yarn**Common Development Tasks:**
Development mode: `pnpm dev`Build production: `pnpm build`Type checking: `pnpm type-check`Linting: `pnpm lint`Formatting: `pnpm prettier`**Workspace-Scoped Commands (Preferred for Speed):**
Build specific workspace: `pnpm -F <workspace> build` - Example: `pnpm -F pages/side-panel build`
Type check workspace: `pnpm -F <workspace> type-check`Lint workspace: `pnpm -F <workspace> lint`Format file: `pnpm -F <workspace> prettier -- <file-path>`Test workspace: `pnpm -F chrome-extension test` - Targeted test: `pnpm -F chrome-extension test -- -t "Sanitizer"`
3. Testing
**Unit Tests:**
Framework: VitestLocation: `chrome-extension/src/**/__tests__/*.test.ts`Run all tests: `pnpm -F chrome-extension test`Run specific test: `pnpm -F chrome-extension test -- -t "TestName"`Write fast, deterministic tests; mock network/browser APIs**E2E Tests:**
Run: `pnpm e2e` (builds and zips first)**Manual Testing:**
1. Build: `pnpm build`
2. Open `chrome://extensions/`
3. Enable "Developer mode"
4. Click "Load unpacked"
5. Select `dist/` directory
4. Internationalization (i18n)
**Key Naming Convention:**
Follow pattern: `component_category_specificAction_state`
**Semantic Prefixes:**
`bg_` - Background service worker`exec_` - Executor/agent execution`act_` - Agent actions/automation`errors_` - Global errors`options_` - Settings page`chat_` - Chat interface`nav_` - Navigation`permissions_` - Permissions**State Suffixes:**
`_start` - Action beginning`_ok` - Success`_fail` - Failure`_cancel` - Cancelled`_pause` - Paused**Usage:**
```typescript
import { t } from '@extension/i18n';
t('bg_errors_noTabId')
t('act_click_ok', ['5', 'Submit Button'])
```
**DO NOT edit generated files** under `packages/i18n/lib/**`. Edit source JSON in `packages/i18n/locales/**` instead.
5. Code Quality Standards
**Type Imports:**
Enforce: `@typescript-eslint/consistent-type-imports`Use: `import type { Foo } from './bar'` for type-only imports**Formatting:**
2 spaces, semicolons, single quotes, trailing commas`printWidth: 120`Run `pnpm prettier` before committing**Modular Design:**
Keep functions small and focusedExtract reusable logic to utilities or shared packagesUse dependency injection for testabilityPrefer composition over inheritance**Naming Conventions:**
Components: `PascalCase`Variables/functions: `camelCase`Workspace directories: `kebab-case`6. Security Guidelines
**Always validate and sanitize** user inputs (URLs, file paths, form data)**Never log or commit** API keys, tokens, or credentialsUse `.env.local` (git-ignored) with `VITE_*` prefix for secretsRespect CSP restrictions; avoid `eval()` or dynamic code executionRequest minimal Chrome extension permissionsSanitize content before rendering (XSS prevention)Validate URLs to prevent malicious redirectsAvoid exposing sensitive information in error messages7. Architecture Understanding
**Workspace Structure:**
`chrome-extension/` - Main extension + background scripts - `src/background/agent/` - AI agents (Navigator, Planner, Validator)
- `src/background/browser/` - Browser automation
`pages/` - UI pages (side-panel, options, content)`packages/` - Shared libraries (storage, ui, schema-utils, i18n)**Tech Stack:**
Chrome Extension Manifest V3React 18 + TypeScriptTailwind CSSVite bundlingPuppeteer for automationLangChain.js for LLM integration**Vite Aliases:**
Pages: `@src` → page `src/`Extension: `@root`, `@src`, `@assets` (see `chrome-extension/vite.config.mts`)8. Change Policy
**Ask First For:**
Adding new dependenciesRenaming/moving/deleting filesModifying global configs (`turbo.json`, `pnpm-workspace.yaml`, `tsconfig*`)Mass refactoring or reformatting unrelated files**Allowed Without Asking:**
Reading/listing filesWorkspace-scoped lint/format/type-check/buildSmall focused patchesUsing existing `packages/ui` components and `packages/tailwind-config` tokens**DO NOT Modify:**
Generated artifacts: `dist/**`, `build/**`, `packages/i18n/lib/**`Use only scripts defined in `package.json`9. Build System
Turbo manages task dependencies and cachingEach workspace has own `vite.config.mts` and `tsconfig.json`Extension builds to `dist/` (loaded as unpacked extension)Distribution zips written to `dist-zip/`Hot reload works via Vite HMR in dev modeBuild flags: `__DEV__=true` for watch builds**Cleaning:**
`pnpm clean` - All build artifacts + node_modules`pnpm clean:bundle` - Build outputs only`pnpm clean:turbo` - Turbo cache`pnpm clean:node_modules` - Dependencies in current workspace`pnpm clean:install` - Clean + reinstall10. Before Committing
1. Run `pnpm type-check` to catch TypeScript errors
2. Run `pnpm lint` for code style consistency
3. Run `pnpm prettier` to format code
4. Run workspace-scoped tests if applicable
5. Build extension: `pnpm build`
6. Test manually in Chrome if UI/functionality changed
Workflow Example
When asked to add a new feature:
1. Identify affected workspaces
2. Read relevant files first
3. Make focused, minimal changes
4. Use workspace-scoped type-check/lint: `pnpm -F <workspace> type-check`
5. Write/update unit tests if business logic changed
6. Build and manually test extension
7. Format code: `pnpm prettier`
When working with i18n:
1. Add keys to `packages/i18n/locales/**/*.json` (never edit `lib/**`)
2. Follow naming convention: `component_category_action_state`
3. Use `t()` helper in code
4. Build will regenerate types automatically
When debugging:
1. Check console for errors
2. Use Chrome DevTools for extension pages
3. Inspect background service worker at `chrome://extensions/`
4. Review relevant agent code in `chrome-extension/src/background/agent/`
Constraints
Only supports Chrome/Edge browsersManifest V3 requirements applyMust use pnpm package managerNode.js version must match `.nvmrc` (`engine-strict=true`)Keep diffs minimal and scopedReuse existing building blocks from shared packages