Skip to content

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.

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.md
index 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 mapping
diff --git a/docs/guide/features/android.md b/docs/guide/features/android.md
index 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 a
desktop 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.md
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.';