@owloops/browserbird 1.0.0

package/LICENSE

@@ -0,0 +1,106 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Copyright 2026 Owloops
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+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,329 @@
+<div align="center">
+
+<img src="web/public/logo-icon.svg" alt="BrowserBird" width="80"/>
+
+# BrowserBird
+
+Self-hosted AI agent for Slack with a real browser, a scheduler, and a web dashboard.
+
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue?style=flat-square)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@owloops/browserbird?style=flat-square)](https://www.npmjs.com/package/@owloops/browserbird)
+[![Install size](https://packagephobia.com/badge?p=@owloops/browserbird)](https://packagephobia.com/result?p=@owloops/browserbird)
+
+</div>
+
+<video src="https://github.com/user-attachments/assets/c71791c3-ba1c-4590-8931-f3adc2dcac2d" autoplay loop muted playsinline></video>
+
+Talk to an AI agent in Slack threads. It can browse the web with a real Chromium browser you can watch live through VNC, run scheduled tasks on a cron, and keep persistent sessions across conversations. BrowserBird is the orchestration layer; the agent CLI ([claude](https://docs.anthropic.com/en/docs/claude-code/overview), [opencode](https://github.com/anomalyco/opencode)) handles reasoning, memory, tools, and sub-agents.
+
+Built by [Owloops](https://github.com/Owloops), who have been building browser automation tools since 2020 ([flybird](https://github.com/Owloops/flybird), [chrome-recorder](https://github.com/Owloops/owloops-chrome-recorder), [extension](https://github.com/Owloops/owloops-extension)). BrowserBird is written from scratch with lessons learned from those projects.
+
+## Installation
+
+On first run, open the web UI and complete the onboarding wizard. It walks through Slack tokens, agent config, and API keys.
+
+### Docker (recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Owloops/browserbird/main/compose.yml -o compose.yml
+docker compose up -d
+```
+
+Everything is included: agent CLI, Chromium browser, VNC, and Playwright MCP. Open `http://<host>:18800` to begin onboarding.
+
+The browser runs in **persistent** mode by default: logins and cookies are saved across sessions, one agent at a time. Set `BROWSER_MODE=isolated` in `.env` for parallel sessions with fresh contexts (requires container restart). `shm_size: 2g` is required for Chromium stability.
+
+### npm
+
+```bash
+npm install -g @owloops/browserbird
+browserbird
+```
+
+Requires Node.js 22.21+ and at least one agent CLI installed ([claude](https://docs.anthropic.com/en/docs/claude-code/overview) or [opencode](https://github.com/anomalyco/opencode)). Open `http://localhost:18800` to begin onboarding.
+
+## Slack
+
+1. Create a new Slack app at [api.slack.com/apps](https://api.slack.com/apps) using the [manifest.json](https://raw.githubusercontent.com/Owloops/browserbird/main/manifest.json) from this repo
+2. Go to OAuth & Permissions, install the app to your workspace, copy the **Bot User OAuth Token** (`xoxb-...`)
+3. Go to Basic Information, create an app-level token with the `connections:write` scope, copy the token (`xapp-...`)
+
+### Slash Commands
+
+Once the app is installed, `/bird` is available in any channel:
+
+```
+/bird list              Show all configured birds
+/bird fly <name>        Trigger a bird immediately
+/bird logs <name>       Show recent flights
+/bird enable <name>     Enable a bird
+/bird disable <name>    Disable a bird
+/bird create            Create a new bird (opens modal form)
+/bird status            Show daemon status
+```
+
+## Configuration
+
+The onboarding wizard handles initial setup. For manual configuration, copy the example config:
+
+```bash
+cp browserbird.example.json browserbird.json
+```
+
+See [browserbird.example.json](browserbird.example.json) for the full config with defaults.
+
+Any string value can reference an environment variable with `"env:VAR_NAME"` syntax (e.g. `"env:SLACK_BOT_TOKEN"`).
+
+The top-level `timezone` field (IANA format, default `"UTC"`) is used for cron scheduling and quiet hours.
+
+<details>
+<summary><strong>slack</strong> - Slack connection and behavior</summary>
+
+```json
+"slack": {
+  "botToken": "env:SLACK_BOT_TOKEN",
+  "appToken": "env:SLACK_APP_TOKEN",
+  "requireMention": true,
+  "coalesce": { "debounceMs": 3000, "bypassDms": true },
+  "channels": ["*"],
+  "quietHours": { "enabled": false, "start": "23:00", "end": "08:00", "timezone": "UTC" }
+}
+```
+
+- `botToken`, `appToken`: Required. Bot user OAuth token and app-level token for Socket Mode
+- `requireMention`: Only respond in channels when `@mentioned`; DMs always respond
+- `coalesce.debounceMs`: Wait N ms after last message before dispatching (groups rapid messages)
+- `coalesce.bypassDms`: Skip debouncing for DMs
+- `channels`: Channel names or IDs to listen in, or `"*"` for all
+- `quietHours`: Silence the bot during specified hours. Start/end in HH:MM format, can wrap midnight
+
+</details>
+
+<details>
+<summary><strong>agents</strong> - Agent routing and model config</summary>
+
+```json
+"agents": [
+  {
+    "id": "default",
+    "name": "BrowserBird",
+    "provider": "claude",
+    "model": "sonnet",
+    "fallbackModel": "haiku",
+    "maxTurns": 50,
+    "systemPrompt": "You are responding in a Slack workspace. Be concise, helpful, and natural.",
+    "channels": ["*"]
+  }
+]
+```
+
+Each agent is scoped to specific channels. Multiple agents are matched in order, first match wins.
+
+- `id`, `name`: Required. Unique identifier and display name
+- `provider`: `"claude"` or `"opencode"`
+- `model`: Claude uses short names (`sonnet`, `haiku`). OpenCode uses `provider/model` format (`anthropic/claude-sonnet-4-20250514`)
+- `fallbackModel`: Fallback when primary is unavailable (claude only)
+- `maxTurns`: Max conversation turns per session
+- `systemPrompt`: Instructions prepended to every session
+- `channels`: Channel names or IDs this agent handles, or `"*"` for all
+- `processTimeoutMs`: Per-agent subprocess timeout override (inherits from `sessions` if not set)
+
+</details>
+
+<details>
+<summary><strong>sessions</strong> - Session lifecycle</summary>
+
+```json
+"sessions": {
+  "ttlHours": 24,
+  "maxConcurrent": 5,
+  "processTimeoutMs": 300000
+}
+```
+
+- `ttlHours`: Session lifetime in hours (resets on each message)
+- `maxConcurrent`: Max simultaneous agent processes
+- `processTimeoutMs`: Per-request timeout in milliseconds
+
+</details>
+
+<details>
+<summary><strong>browser</strong> - Playwright MCP and VNC</summary>
+
+```json
+"browser": {
+  "enabled": false,
+  "mcpConfigPath": null,
+  "vncPort": 5900,
+  "novncPort": 6080,
+  "novncHost": "localhost"
+}
+```
+
+- `enabled`: Enable Playwright MCP for the agent
+- `mcpConfigPath`: Path to your MCP config (relative or absolute)
+- `vncPort`: VNC server port
+- `novncPort`: Upstream noVNC WebSocket port
+- `novncHost`: Upstream noVNC host (e.g. `"vm"` in Docker)
+
+Browser mode (`persistent` or `isolated`) is controlled by the `BROWSER_MODE` environment variable, not the config file.
+
+</details>
+
+<details>
+<summary><strong>birds</strong> - Scheduled task settings</summary>
+
+```json
+"birds": {
+  "maxAttempts": 3
+}
+```
+
+- `maxAttempts`: Max job attempts before a bird stops retrying
+
+Each bird supports per-bird active hours set via CLI `--active-hours 09:00-17:00` or the API. Wrap-around windows (e.g. `22:00-06:00`) are supported.
+
+</details>
+
+<details>
+<summary><strong>database</strong> - Retention policy</summary>
+
+```json
+"database": {
+  "retentionDays": 30
+}
+```
+
+- `retentionDays`: How long to keep messages, flight logs, jobs, and logs
+
+</details>
+
+<details>
+<summary><strong>web</strong> - Dashboard and API server</summary>
+
+```json
+"web": {
+  "enabled": true,
+  "host": "127.0.0.1",
+  "port": 18800,
+  "corsOrigin": ""
+}
+```
+
+- `enabled`: Enable the web dashboard and API
+- `host`: Bind address (`0.0.0.0` for Docker/remote)
+- `port`: Web UI and REST API port
+- `corsOrigin`: Allowed origin for CORS headers (for cross-origin SPA hosting)
+
+Authentication is handled via the web UI. On first visit, you create an account. All subsequent visits require login.
+
+</details>
+
+### Environment Variables
+
+| Variable                  | Description                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `SLACK_BOT_TOKEN`         | Bot user OAuth token                                                                             |
+| `SLACK_APP_TOKEN`         | App-level token for Socket Mode                                                                  |
+| `ANTHROPIC_API_KEY`       | Anthropic API key (pay-per-token). Used by both claude and opencode providers                    |
+| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token for claude provider only (uses your Claude Pro/Max subscription)                     |
+| `BROWSER_MODE`            | `persistent` (default) or `isolated`. Requires container restart                                 |
+| `BROWSERBIRD_CONFIG`      | Path to `browserbird.json`. Overridden by `--config` flag                                        |
+| `BROWSERBIRD_DB`          | Path to SQLite database file. Overridden by `--db` flag                                          |
+| `NO_COLOR`                | Disable colored output                                                                           |
+
+The **opencode** provider inherits standard env vars per model provider: `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, etc. See the full list at [models.dev](https://models.dev).
+
+> [!NOTE]
+> **Agent authentication:** `ANTHROPIC_API_KEY` (pay-per-token) is required for shared or commercial deployments per Anthropic's Consumer ToS. `CLAUDE_CODE_OAUTH_TOKEN` is fine for personal self-hosted use (claude provider only). When both are set, the claude provider uses OAuth and the opencode provider uses the API key.
+
+## CLI
+
+```
+$ browserbird --help
+
+   .__.
+   ( ^>
+   / )\
+  <_/_/
+   " "
+usage: browserbird [command] [options]
+
+commands:
+
+  sessions    manage sessions
+  birds       manage scheduled birds
+  config      view configuration
+  logs        show recent log entries
+  jobs        inspect and manage the job queue
+  doctor      check system dependencies
+
+options:
+
+  -h, --help     show this help
+  -v, --version  show version
+  --verbose      enable debug logging
+  --config       config file path (env: BROWSERBIRD_CONFIG)
+  --db           database file path (env: BROWSERBIRD_DB)
+
+run 'browserbird <command> --help' for command-specific options.
+```
+
+## Web UI
+
+Runs at `http://localhost:18800` by default.
+
+<img src="assets/webui-demo.png" alt="BrowserBird web UI" />
+
+| Page         | Description                                                                        |
+| ------------ | ---------------------------------------------------------------------------------- |
+| **Status**   | System overview, failing birds, upcoming runs, active sessions                     |
+| **Sessions** | Session list with message history, token usage, and conversation detail            |
+| **Birds**    | Scheduled birds: create, edit, enable/disable, trigger, inline flight history      |
+| **Browser**  | Live noVNC viewer (Docker only)                                                    |
+| **Settings** | Config editor, agent management, secrets, system birds, job queue, and log viewer  |
+
+## Development
+
+```bash
+git clone https://github.com/Owloops/browserbird.git
+cd browserbird
+npm ci
+```
+
+### Run locally
+
+```bash
+cd web && npm ci && npm run build && cd ..
+./bin/browserbird
+```
+
+### Docker (build locally)
+
+```bash
+cp .env.example .env
+docker compose -f oci/compose.yml up -d --build
+```
+
+### Checks
+
+```bash
+npm run typecheck          # tsc --noEmit
+npm run lint               # eslint
+npm run format:check       # prettier
+npm test                   # node --test
+```
+
+Web UI (from `web/`):
+
+```bash
+npm run check              # svelte-check
+npm run format:check       # prettier
+```
+
+## License
+
+[FSL-1.1-MIT](LICENSE), source available, converts to MIT after two years.
+
+> [!NOTE]
+> This project was built with assistance from LLMs. Human review and guidance provided throughout.

package/bin/browserbird

@@ -0,0 +1,11 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+
+import { run } from '../src/cli/index.ts';
+
+try {
+  await run(process.argv.slice(2));
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@owloops/browserbird",
+  "version": "1.0.0",
+  "description": "Self-hosted AI agent for Slack with a real browser, a scheduler, and a web dashboard",
+  "type": "module",
+  "bin": {
+    "browserbird": "./bin/browserbird"
+  },
+  "engines": {
+    "node": ">=22.21.0"
+  },
+  "files": [
+    "src",
+    "bin",
+    "web/dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "node --test src/**/*.test.ts",
+    "start": "./bin/browserbird",
+    "prepublishOnly": "npm run lint && npm run format:check && npm run typecheck && cd web && npm ci && npm run build"
+  },
+  "keywords": [
+    "slack",
+    "claude",
+    "claude-code",
+    "orchestrator",
+    "cli",
+    "bot"
+  ],
+  "author": "Owloops",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://github.com/Owloops/browserbird#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Owloops/browserbird.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Owloops/browserbird/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.5.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@slack/socket-mode": "^2.0.5"
+  }
+}