An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
feat(panel): /android (or /phone) switches the panel to Chrome on the Android phone and back; the command and the header’s Android switch always show in Chromium browsers, greyed out with the Bridge’s reason until a phone is ready
Shahriar81f50765ff8e
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex 5001722..3c07d96 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -106,7 +106,7 @@ settings page shows but will not change.| Key | Default | Notes || --- | --- | --- |-| `android.enabled` | `true` | `false` stops the Bridge using adb at all: it never looks for phones, and the side panel shows no Android switch. See [Android phone](features/android.md) |+| `android.enabled` | `true` | `false` stops the Bridge using adb at all: it never looks for phones, and the side panel's Android switch stays greyed out. See [Android phone](features/android.md) || `android.adb` | found | Absolute path to the adb to use. Without it the Bridge looks on `PATH`, under `ANDROID_HOME` and `ANDROID_SDK_ROOT`, in Android Studio's SDK, where Homebrew puts it, and on Windows where winget, Scoop and Chocolatey put it and in `Downloads`. Name one when you have several, since two adb versions stop each other's server. On Windows write the path with forward slashes, `"C:/platform-tools/adb.exe"`: a single backslash is not valid JSON, and the Bridge then ignores the whole file |## Site mappingdiff --git a/docs/guide/features/android.md b/docs/guide/features/android.mdindex 2c74574..7bd4d25 100644--- a/docs/guide/features/android.md+++ b/docs/guide/features/android.md@@ -47,9 +47,14 @@ them. Android's [OEM USB drivers](https://developer.android.com/studio/run/oem-u## Using it-The **Android** switch (a phone icon) appears in the side panel's header once the Bridge sees a-phone. Switch it on and a **phone tab** opens beside the tab you were on. It shows the page in-front on the phone, kept up to date as it changes.+The **Android** switch (a phone icon) is in the side panel's header. Until a phone is ready it is+greyed out, and hovering it says why, such as no phone connected or adb not installed. Switch it on+and a **phone tab** opens beside the tab you were on. It shows the page in front on the phone, kept+up to date as it changes.++Typing **`/android`** (or `/phone`) in the composer does the same, and typed again it takes you+back to the computer's browser. The `/` menu always lists it, greyed out with the same reason while+no phone is ready.- **Talk to it** in the side panel while the phone tab is in front, exactly as you would for adesktop tab. The conversation belongs to the phone tab, and the agent's actions land on the phone.diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 63201b6..29e3242 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -112,7 +112,7 @@ names the one that fails. See [Android phone](features/android.md) for setting a| Symptom | Cause | Fix || --- | --- | --- |-| No Android switch in the side panel | The Bridge sees no phone, the Bridge predates Android, or the browser is Firefox | Run `browsentic android`. Update the Bridge if it does not know the command. Firefox has no Android switch |+| The Android switch is greyed out, or `/android` is | The Bridge sees no ready phone, or it predates Android. Hovering the switch says which | Run `browsentic android`. Update the Bridge if it does not know the command. Firefox has no Android switch || `ANDROID_OFF` | `"android": { "enabled": false }` is set in `config.json` | Set it to `true`, or remove it || `ADB_MISSING` | adb, from Android's platform-tools, is not installed, or not where the Bridge looks | Install platform-tools (the check prints the command for your system), or name your adb with `"android": { "adb": "/path/to/adb" }`. On Windows, unzip the download in `Downloads`, or name it with forward slashes: `"C:/path/to/adb.exe"` || `ADB_BROKEN` | The adb the Bridge found does not run | Reinstall platform-tools, or name a working adb in `config.json` |diff --git a/src/extension/components/composer.tsx b/src/extension/components/composer.tsxindex 499fe48..d4e6d6d 100644--- a/src/extension/components/composer.tsx+++ b/src/extension/components/composer.tsx@@ -16,7 +16,7 @@ import {X,} from 'lucide-react';-import { SkillMenu, skillMenuItems, type SkillMenuItem } from '@/extension/components/skill-menu';+import { SkillMenu, skillMenuItems, type AndroidOption, type SkillMenuItem } from '@/extension/components/skill-menu';import type { SavedToolMeta } from '@/lib/bridge/saved-tools';import { Button } from '@/extension/components/ui/button';import { Textarea } from '@/extension/components/ui/textarea';@@ -46,6 +46,7 @@ export function Composer({picking,liveTools,handsFree,+ android,onToggleLiveTools,onPhone = false,scheduling,@@ -79,6 +80,8 @@ export function Composer({liveTools: boolean;/** Whether `/hands-free` is offered — never where the browser cannot transcribe speech. */handsFree: boolean;+ /** `/android`, listed wherever a phone could be driven; absent where none ever can. */+ android?: AndroidOption;/** The panel is showing the phone conversation: what only works in a desktop tab is not offered. */onPhone?: boolean;onToggleLiveTools: () => void;@@ -106,8 +109,8 @@ export function Composer({const menuOpen = slash !== null && connected;const [highlight, setHighlight] = useState(0);const menuItems = useMemo(- () => (menuOpen ? skillMenuItems(catalog, tabUrl, slash ?? '', tools, { handsFree }) : []),- [menuOpen, catalog, tabUrl, slash, tools, handsFree],+ () => (menuOpen ? skillMenuItems(catalog, tabUrl, slash ?? '', tools, { handsFree, android }) : []),+ [menuOpen, catalog, tabUrl, slash, tools, handsFree, android],);useEffect(() => setHighlight(0), [slash]);@@ -118,6 +121,7 @@ export function Composer({}, [menuOpen, cancelPending]);function choose(item: SkillMenuItem) {+ if (item.unavailable) return;if (item.savedToolId) {voice.setInput('');onRunTool(item.savedToolId);diff --git a/src/extension/components/phone-toggle.tsx b/src/extension/components/phone-toggle.tsxindex 1e47be3..cd0174a 100644--- a/src/extension/components/phone-toggle.tsx+++ b/src/extension/components/phone-toggle.tsx@@ -1,9 +1,10 @@import { useEffect, useState } from 'react';import { Smartphone } from 'lucide-react';import { browser } from 'wxt/browser';-import { ANDROID_PROTOCOL } from '@/lib/actions/protocol';+import { ANDROID_PROTOCOL, failure, type ActionResult } from '@/lib/actions/protocol';import { isLive } from '@/lib/bridge/phone';import { askPhone, usePhoneSession } from '@/lib/bridge/phone-client';+import type { DaemonState } from '@/lib/bridge/socket';import { useDaemonState } from '@/lib/bridge/use-daemon-state';import type { AndroidState } from '@/lib/phone/types';import { cn } from '@/lib/utils';@@ -14,9 +15,42 @@ const ERROR_SHOWN_MS = 6_000;/** The first phone adb has a connection to; Chrome closed on it is handled once the session starts. */export const drivablePhone = (android: AndroidState | undefined) => android?.devices.find((device) => device.state === 'ready');-export function PhoneToggle() {+function whyNoPhone(daemon: DaemonState | null, android: AndroidState | undefined): string {+ if (import.meta.env.FIREFOX) return 'Android phones are driven from Chrome and other Chromium browsers, not Firefox.';+ if (!daemon?.connected) return 'Connect to Browsentic Bridge first, then switch to the phone.';+ if (!android) return 'This Browsentic Bridge is too old to drive a phone. Update it, then try again.';+ return android.devices[0]?.problem?.message ?? android.problem?.message ?? 'The phone is not ready.';+}++export interface PhoneSwitch {+ on: boolean;+ ready: boolean;+ /** What stands between the user and a ready phone; empty once there is none. */+ problem: string;+ toggle: () => Promise<ActionResult<unknown>>;+}++export function usePhoneSwitch(): PhoneSwitch {const daemon = useDaemonState();const session = usePhoneSession();+ const android =+ !import.meta.env.FIREFOX && daemon?.connected && (daemon.protocolVersion ?? 0) >= ANDROID_PROTOCOL ? daemon.android : undefined;+ const on = isLive(session);+ const phone = drivablePhone(android);+ const ready = on || phone !== undefined;+ const problem = ready ? '' : whyNoPhone(daemon, android);++ const toggle = async (): Promise<ActionResult<unknown>> => {+ if (on) return askPhone({ op: 'phoneEnd' });+ if (!phone) return failure('PHONE_NOT_READY', problem);+ return askPhone({ op: 'phoneStart', serial: phone.serial, windowId: (await browser.windows.getCurrent()).id });+ };++ return { on, ready, problem, toggle };+}++export function PhoneToggle() {+ const phone = usePhoneSwitch();const [busy, setBusy] = useState(false);const [error, setError] = useState<string>();@@ -27,20 +61,11 @@ export function PhoneToggle() {}, [error]);if (import.meta.env.FIREFOX) return null;- const android = daemon?.connected && (daemon.protocolVersion ?? 0) >= ANDROID_PROTOCOL ? daemon.android : undefined;- const on = isLive(session);- if (!on && !android?.devices.length) return null;-- const phone = drivablePhone(android);- const blocked = !on && !phone;- const title = blocked ? (android?.devices[0]?.problem?.message ?? 'The phone is not ready.') : 'Drive Chrome on your Android phone';const toggle = async () => {setBusy(true);setError(undefined);- const result = on- ? await askPhone({ op: 'phoneEnd' })- : await askPhone({ op: 'phoneStart', serial: phone!.serial, windowId: (await browser.windows.getCurrent()).id });+ const result = await phone.toggle();setBusy(false);if (!result.ok) setError(result.error.message);};@@ -48,12 +73,12 @@ export function PhoneToggle() {return (<span className="relative"><Button- variant={on ? 'subtle' : 'ghost'}+ variant={phone.on ? 'subtle' : 'ghost'}size="icon-sm"- title={title}+ title={phone.ready ? 'Drive Chrome on your Android phone' : phone.problem}aria-label="Android"- aria-pressed={on}- disabled={busy || blocked}+ aria-pressed={phone.on}+ disabled={busy || !phone.ready}onClick={() => void toggle()}><Smartphone className={cn('size-3.5', busy && 'animate-pulse')} />diff --git a/src/extension/components/skill-menu.tsx b/src/extension/components/skill-menu.tsxindex e82ffd0..edc3b45 100644--- a/src/extension/components/skill-menu.tsx+++ b/src/extension/components/skill-menu.tsx@@ -3,6 +3,10 @@ import { BookOpen, Globe, Sparkles, SquareSlash, Zap } from 'lucide-react';import type { SkillCatalog } from '@/lib/actions/protocol';import { AGENTS } from '@/lib/agents/catalog';import {+ ANDROID_ALIASES,+ ANDROID_COMMAND,+ ANDROID_DESCRIPTION,+ ANDROID_LEAVE_DESCRIPTION,CONTEXT_COMMAND,CONTEXT_COMMAND_DESCRIPTION,HANDS_FREE_ALIASES,@@ -33,6 +37,13 @@ export interface SkillMenuItem {savedToolId?: string;/** Other spellings the filter matches, so a near miss still finds the command. */aliases?: string[];+ /** Why the command cannot run right now. It stays listed, greyed out, with this in place of its description. */+ unavailable?: string;+}++export interface AndroidOption {+ on: boolean;+ problem: string;}// Saved tools sort first: they are the only entries that do something on their own, and@@ -51,7 +62,7 @@ export function skillMenuItems(tabUrl: string,query: string,tools: readonly SavedToolMeta[] = [],- { handsFree = false }: { handsFree?: boolean } = {},+ { handsFree = false, android }: { handsFree?: boolean; android?: AndroidOption } = {},): SkillMenuItem[] {const host = hostnameOf(tabUrl);const items: SkillMenuItem[] = [@@ -73,6 +84,17 @@ export function skillMenuItems(aliases: HANDS_FREE_ALIASES,});}+ if (android) {+ items.push({+ key: 'command:android',+ group: 'command',+ name: 'android',+ description: android.on ? ANDROID_LEAVE_DESCRIPTION : ANDROID_DESCRIPTION,+ command: ANDROID_COMMAND,+ aliases: ANDROID_ALIASES,+ unavailable: android.problem || undefined,+ });+ }if (tools.length) {items.push({key: 'command:remove-tools',@@ -160,6 +182,8 @@ export function SkillMenu({type="button"role="option"aria-selected={index === highlight}+ aria-disabled={item.unavailable ? true : undefined}+ title={item.unavailable}onMouseEnter={() => onHover(index)}onMouseDown={(event) => {event.preventDefault();@@ -168,6 +192,7 @@ export function SkillMenu({className={cn('flex w-full items-start gap-2 px-3 py-1.5 text-left transition-colors',index === highlight ? 'bg-brand/12' : 'hover:bg-ground/40',+ item.unavailable && 'cursor-not-allowed opacity-55',)}>{item.group === 'tool' ? (@@ -183,8 +208,10 @@ export function SkillMenu({)}<span className="min-w-0 flex-1"><span className="block truncate text-xs font-medium text-ink">{item.name}</span>- {item.description && (- <span className="block truncate text-[11px] text-ink-dim">{item.description}</span>+ {item.unavailable ? (+ <span className="line-clamp-2 block text-[11px] text-ink-dim">{item.unavailable}</span>+ ) : (+ item.description && <span className="block truncate text-[11px] text-ink-dim">{item.description}</span>)}</span></button>diff --git a/src/extension/entrypoints/sidepanel/App.tsx b/src/extension/entrypoints/sidepanel/App.tsxindex 681c695..840325e 100644--- a/src/extension/entrypoints/sidepanel/App.tsx+++ b/src/extension/entrypoints/sidepanel/App.tsx@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';import { ArrowDown, PanelRightClose, PictureInPicture2, SlidersHorizontal, SquarePen } from 'lucide-react';import { browser } from 'wxt/browser';-import { isHandsFreeCommand, isRemoveToolsCommand } from '@/lib/bridge/commands';+import { isAndroidCommand, isHandsFreeCommand, isRemoveToolsCommand } from '@/lib/bridge/commands';import { BRIDGE_CHANNEL, type FocusedElement } from '@/lib/actions/protocol';import { MAX_STORED_FILE_BYTES } from '@/lib/files/report';import { Wordmark } from '@/extension/components/brand';@@ -14,7 +14,7 @@ import { DropMask } from '@/extension/components/drop-mask';import { Greeting } from '@/extension/components/greeting';import { MonitorBar } from '@/extension/components/monitor-bar';import { PanelNav, type PanelTab } from '@/extension/components/panel-nav';-import { PhoneToggle } from '@/extension/components/phone-toggle';+import { PhoneToggle, usePhoneSwitch } from '@/extension/components/phone-toggle';import { currentTarget } from '@/lib/bridge/phone';import { useMirroredPhone } from '@/lib/bridge/phone-client';import { RecordingBar } from '@/extension/components/recording-bar';@@ -83,6 +83,11 @@ export default function App() {const tabUrl = useActiveTabUrl();const phone = useMirroredPhone();const onPhone = phone !== null;+ const phoneSwitch = usePhoneSwitch();+ const androidOption = useMemo(+ () => (import.meta.env.FIREFOX ? undefined : { on: phoneSwitch.on, problem: phoneSwitch.problem }),+ [phoneSwitch.on, phoneSwitch.problem],+ );const handsFree = handsFreeSupported && !onPhone;const pageUrl = phone ? (currentTarget(phone)?.url ?? '') : tabUrl;const blockedHere = useBlockedPattern(pageUrl);@@ -125,10 +130,7 @@ export default function App() {const voice = useVoiceComposer({active: voiceEnabled && connected && !run.running,onSubmit: (text) => {- if (handsFree && isHandsFreeCommand(text)) {- detach();- return;- }+ if (takeCommand(text)) return;run.send(text, { agentSkillId: attachedSkill?.id, focus: focus ?? undefined, liveTools });setAttachedSkill(null);setFocus(null);@@ -204,11 +206,21 @@ export default function App() {window.setTimeout(() => setDetaching(false), DETACH_MS + DETACH_STUCK_MS);}- function handleSend() {- if (handsFree && isHandsFreeCommand(voice.input)) {+ function takeCommand(text: string): boolean {+ if (handsFree && isHandsFreeCommand(text)) {detach();- return;+ return true;+ }+ if (isAndroidCommand(text)) {+ voice.setInput('');+ void phoneSwitch.toggle().then((result) => setAttachError(result.ok ? null : result.error.message));+ return true;}+ return false;+ }++ function handleSend() {+ if (takeCommand(voice.input)) return;if (!connected) return;if (scheduling) {schedule({ text: voice.input.trim(), url: tabUrl });@@ -510,12 +522,10 @@ export default function App() {onToggleActionCues={() => setActionCues(!actionCues)}onAttachSkill={setAttachedSkill}handsFree={handsFree}+ android={androidOption}onPhone={onPhone}onCommand={(command) => {- if (handsFree && isHandsFreeCommand(command)) {- detach();- return;- }+ if (takeCommand(command)) return;if (isRemoveToolsCommand(command)) {setShowTools(true);return;diff --git a/src/lib/bridge/commands.test.ts b/src/lib/bridge/commands.test.tsindex ac8582d..886a62b 100644--- a/src/lib/bridge/commands.test.ts+++ b/src/lib/bridge/commands.test.ts@@ -1,5 +1,16 @@import { describe, expect, it } from 'vitest';-import { isHandsFreeCommand } from './commands';+import { isAndroidCommand, isHandsFreeCommand } from './commands';++describe('isAndroidCommand', () => {+ it('takes the command and /phone, in any case and padding', () => {+ for (const typed of ['/android', '/phone', ' /Android ']) expect(isAndroidCommand(typed)).toBe(true);+ });++ it('leaves an instruction that merely mentions it alone', () => {+ expect(isAndroidCommand('/android open youtube')).toBe(false);+ expect(isAndroidCommand('android')).toBe(false);+ });+});describe('isHandsFreeCommand', () => {it('takes the command and the spellings people reach for', () => {diff --git a/src/lib/bridge/commands.ts b/src/lib/bridge/commands.tsindex 7a7f728..aa9ca22 100644--- a/src/lib/bridge/commands.ts+++ b/src/lib/bridge/commands.ts@@ -22,6 +22,19 @@ export const isHandsFreeCommand = (text: string): boolean => {return typed === HANDS_FREE_COMMAND || HANDS_FREE_ALIASES.some((alias) => typed === `/${alias}`);};+export const ANDROID_COMMAND = '/android';++export const ANDROID_ALIASES = ['phone'];++export const ANDROID_DESCRIPTION = 'Switch to Chrome on your Android phone, mirrored in a tab here.';++export const ANDROID_LEAVE_DESCRIPTION = 'Leave the phone and go back to this browser.';++export const isAndroidCommand = (text: string): boolean => {+ const typed = text.trim().toLowerCase();+ return typed === ANDROID_COMMAND || ANDROID_ALIASES.some((alias) => typed === `/${alias}`);+};+export const CONTEXT_COMMAND_DESCRIPTION ='See what this conversation carries — messages, files, recordings, tabs.';