Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat: improve onboarding UX with guided tour and step indicators

Gener8534a2b1d01e
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f95a5ebec..d4f7fa1c9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -185,6 +185,9 @@ importers:
clsx:
specifier: ^2.1.1
version: 2.1.1
+ driver.js:
+ specifier: ^1.4.0
+ version: 1.4.0
embla-carousel-autoplay:
specifier: ^8.6.0
version: 8.6.0([email protected])
@@ -3768,6 +3771,9 @@ packages:
resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-Gm64jm6PmcU+si21sQhBrTAM1JvUrR0QhNmjkprNLxohOBzul9+pNHXgQaT9lW84gwg9GMLB3NZGuGolsz5uew==}
+
resolution: {integrity: sha512-kY0BSaTNYWnoDMVoyY8uxmyHjpJW1geOmBMdSSicKo9CIIWkSxMIj2rkeSR51b8KAPB7m+qysjuHme5nKP+E5Q==}
peerDependencies:
@@ -10871,6 +10877,8 @@ snapshots:
+
optionalDependencies:
'@cloudflare/workers-types': 4.20260504.1
@@ -11128,7 +11136,7 @@ snapshots:
'@next/eslint-plugin-next': 16.2.4
eslint: 9.39.4([email protected])
eslint-import-resolver-node: 0.3.10
+ eslint-import-resolver-typescript: 3.10.1([email protected])([email protected]([email protected]))
eslint-plugin-jsx-a11y: 6.10.2([email protected]([email protected]))
eslint-plugin-react: 7.37.5([email protected]([email protected]))
@@ -11151,7 +11159,7 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@nolyfill/is-core-module': 1.0.39
debug: 4.4.3
@@ -11166,14 +11174,14 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
debug: 3.2.7
optionalDependencies:
'@typescript-eslint/parser': 8.58.2([email protected]([email protected]))([email protected])
eslint: 9.39.4([email protected])
eslint-import-resolver-node: 0.3.10
+ eslint-import-resolver-typescript: 3.10.1([email protected])([email protected]([email protected]))
transitivePeerDependencies:
- supports-color
@@ -11188,7 +11196,7 @@ snapshots:
doctrine: 2.1.0
eslint: 9.39.4([email protected])
eslint-import-resolver-node: 0.3.10
hasown: 2.0.3
is-core-module: 2.16.1
is-glob: 4.0.3
diff --git a/src/web/package.json b/src/web/package.json
index 7075e103f..4a5166581 100644
--- a/src/web/package.json
+++ b/src/web/package.json
@@ -43,6 +43,7 @@
"better-auth": "^1.6.9",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
+ "driver.js": "^1.4.0",
"embla-carousel-autoplay": "^8.6.0",
"embla-carousel-react": "^8.6.0",
"gsap": "^3.15.0",
diff --git a/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx b/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx
index d04bbe0d2..f557dc009 100644
--- a/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx
+++ b/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx
@@ -1,18 +1,20 @@
"use client";
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef, useCallback } from "react";
import { useRouter } from "next/navigation";
import { useAgentContext } from "@/contexts/agent-context";
import { useWorkspace } from "@/contexts/workspace-context";
import { AgentCreateForm } from "@/components/agent-create-form";
import { fetchModelOptions, createEmailAccount } from "@/lib/api";
import { toast } from "sonner";
+import { CircleHelp } from "lucide-react";
export default function CreateAgentPage() {
const router = useRouter();
const { slug, workspaceId } = useWorkspace();
const {
+ agents,
runtimes,
handleCreateAgent,
getFirstOnlineRuntimeId,
@@ -20,21 +22,36 @@ export default function CreateAgentPage() {
const [saving, setSaving] = useState(false);
const [modelOptions, setModelOptions] = useState<Record<string, string[]>>({});
+ const startTourRef = useRef<(() => void) | null>(null);
useEffect(() => {
fetchModelOptions().then(setModelOptions).catch(() => {});
}, []);
+ const handleTourReady = useCallback((startTour: () => void) => {
+ startTourRef.current = startTour;
+ }, []);
+
return (
<>
<div className="flex items-center gap-2 border-b border-border/50 px-3 md:px-5 py-2.5">
<h1 className="text-sm font-medium">Create Agent</h1>
+ <button
+ type="button"
+ title="Show guided tour"
+ onClick={() => startTourRef.current?.()}
+ className="text-muted-foreground hover:text-foreground transition-colors"
+ >
+ <CircleHelp className="size-3.5" />
+ </button>
</div>
<AgentCreateForm
runtimes={runtimes}
defaultRuntimeId={getFirstOnlineRuntimeId()}
modelOptions={modelOptions}
+ guided={agents.length === 0}
+ onTourReady={handleTourReady}
saving={saving}
onCancel={() => router.back()}
onSave={async (data) => {
diff --git a/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx b/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx
index f78ae992e..fda6fe532 100644
--- a/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx
+++ b/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx
@@ -22,7 +22,7 @@ import {
import { ConfirmDialog } from "@/components/ui/confirm-dialog";
import { toast } from "sonner";
import { Skeleton } from "@/components/ui/skeleton";
-import { Monitor, Plus } from "lucide-react";
+import { Monitor, Plus, Check } from "lucide-react";
import type { AgentRuntime as Runtime } from "@alook/shared";
import { semverGte } from "@alook/shared";
@@ -31,16 +31,34 @@ import { ProviderLogo } from "@/components/provider-logo";
import { triggerRuntimeUpdate, triggerRuntimeRescan, fetchLatestCliVersion } from "@/lib/api";
import { Loader2, RefreshCw } from "lucide-react";
+function StepIndicator({ step, completed }: { step: number; completed: boolean }) {
+ if (completed) {
+ return (
+ <span className="flex items-center justify-center size-5 rounded-full bg-emerald-500 text-white transition-all duration-300">
+ <Check className="size-3" strokeWidth={3} />
+ </span>
+ );
+ }
+ return (
+ <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">
+ {step}
+ </span>
+ );
+}
+
function ConnectMachineSteps({
generatedToken,
generatingToken,
onGenerateToken,
+ registered,
}: {
generatedToken: string;
generatingToken: boolean;
onGenerateToken: () => void;
+ registered: boolean;
}) {
const hasTriggered = useRef(false);
+
useEffect(() => {
if (!generatedToken && !generatingToken && !hasTriggered.current) {
hasTriggered.current = true;
@@ -48,8 +66,13 @@ function ConnectMachineSteps({
}
}, [generatedToken, generatingToken, onGenerateToken]);
- const copyToClipboard = (text: string) => {
- navigator.clipboard.writeText(text);
+ const copyRegister = () => {
+ navigator.clipboard.writeText(`${CLI_CMD} register --token ${generatedToken}`);
+ toast.success("Copied to clipboard");
+ };
+
+ const copyDaemon = () => {
+ navigator.clipboard.writeText(`${CLI_CMD} daemon start --foreground`);
toast.success("Copied to clipboard");
};
@@ -58,10 +81,9 @@ function ConnectMachineSteps({
{/* Step 1 */}
<div className="space-y-2">
<p className="text-xs font-medium flex items-center gap-2">
- <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">
- 1
- </span>
+ <StepIndicator step={1} completed={registered} />
Register your CLI
+ {registered && <span className="text-[10px] text-emerald-500 font-normal">Done</span>}
</p>
<p className="text-xs text-muted-foreground pl-7">
Run this in your terminal to link your machine.
@@ -76,11 +98,7 @@ function ConnectMachineSteps({
<div className="pl-7 space-y-2">
<div
className="rounded-md bg-muted p-2.5 font-mono text-xs text-muted-foreground cursor-pointer hover:bg-muted/80 transition-colors"
- onClick={() =>
- copyToClipboard(
- `${CLI_CMD} register --token ${generatedToken}`
- )
- }
+ onClick={copyRegister}
title="Click to copy"
>
{CLI_CMD} register --token{" "}
@@ -88,30 +106,25 @@ function ConnectMachineSteps({
{generatedToken.slice(0, 12)}...
</span>
</div>
- <Button
- size="sm"
- onClick={() => {
- navigator.clipboard.writeText(
- `${CLI_CMD} register --token ${generatedToken}`
- );
- toast.success("Copied to clipboard");
- }}
- className="w-full"
- >
- Copy Command
- </Button>
+ {!registered && (
+ <Button
+ size="sm"
+ onClick={copyRegister}
+ className="w-full"
+ >
+ Copy Command
+ </Button>
+ )}
</div>
) : null}
</div>
{/* Step 2 */}
<div
- className={`space-y-2 ${!generatedToken ? "opacity-40 pointer-events-none" : ""}`}
+ className={`space-y-2 transition-opacity duration-300 ${!registered ? "opacity-40 pointer-events-none" : ""}`}
>
<p className="text-xs font-medium flex items-center gap-2">
- <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">
- 2
- </span>
+ <StepIndicator step={2} completed={false} />
Start the daemon
</p>
<p className="text-xs text-muted-foreground pl-7">
@@ -119,13 +132,22 @@ function ConnectMachineSteps({
</p>
<div
className="ml-7 rounded-md bg-muted p-2.5 font-mono text-xs text-muted-foreground cursor-pointer hover:bg-muted/80 transition-colors"
- onClick={() =>
- copyToClipboard(`${CLI_CMD} daemon start --foreground`)
- }
+ onClick={copyDaemon}
title="Click to copy"
>
{CLI_CMD} daemon start --foreground
</div>
+ {registered && (
+ <div className="pl-7">
+ <Button
+ size="sm"
+ onClick={copyDaemon}
+ className="w-full"
+ >
+ Copy Command
+ </Button>
+ </div>
+ )}
</div>
</div>
@@ -133,7 +155,7 @@ function ConnectMachineSteps({
}
export default function RuntimesPage() {
- const { runtimes, loading, handleGenerateToken, handleDeleteMachine, subscribeWs, workspaceId } =
+ const { agents, runtimes, loading, handleGenerateToken, handleDeleteMachine, subscribeWs, workspaceId } =
useAgentContext();
const searchParams = useSearchParams();
const router = useRouter();
@@ -142,6 +164,7 @@ export default function RuntimesPage() {
const [sheetOpen, setSheetOpen] = useState(() => searchParams.has("connect"));
const [generatedToken, setGeneratedToken] = useState("");
const [generatingToken, setGeneratingToken] = useState(false);
+ const [machineRegistered, setMachineRegistered] = useState(false);
const [latestCliVersion, setLatestCliVersion] = useState<string | null>(null);
const [updatingDaemons, setUpdatingDaemons] = useState<Set<string>>(new Set());
@@ -169,24 +192,33 @@ export default function RuntimesPage() {
}
}, [searchParams, router, pathname]);
- // Close the sheet only after the daemon is actually online. Runtime
- // registration can happen before the user starts the daemon process.
+ // Listen for registration + online events while the sheet is open.
const sheetOpenRef = useRef(sheetOpen);
useEffect(() => { sheetOpenRef.current = sheetOpen; }, [sheetOpen]);
+ const agentsRef = useRef(agents);
+ useEffect(() => { agentsRef.current = agents; }, [agents]);
useEffect(() => {
return subscribeWs((msg) => {
+ if (!sheetOpenRef.current) return;
+ if (msg.type === "runtime.registered" && msg.workspaceId === workspaceId) {
+ setMachineRegistered(true);
+ }
if (
msg.type === "runtime.status" &&
msg.workspaceId === workspaceId &&
- msg.status === "online" &&
- sheetOpenRef.current
+ msg.status === "online"
) {
setSheetOpen(false);
setGeneratedToken("");
+ setMachineRegistered(false);
toast.success("Machine connected");
+ if (agentsRef.current.length === 0) {
+ const slug = pathname.split("/")[2];
+ router.push(`/w/${slug}/agents/new`);
+ }
}
});
- }, [subscribeWs, workspaceId]);
+ }, [subscribeWs, workspaceId, pathname, router]);
const openConfirm = (
title: string,
@@ -358,6 +390,7 @@ export default function RuntimesPage() {
variant="outline"
onClick={() => {
setGeneratedToken("");
+ setMachineRegistered(false);
setSheetOpen(true);
}}
disabled={generatingToken}
@@ -566,6 +599,7 @@ export default function RuntimesPage() {
generatedToken={generatedToken}
generatingToken={generatingToken}
onGenerateToken={onGenerateToken}
+ registered={machineRegistered}
/>
</SheetBody>
</SheetContent>
diff --git a/src/web/src/components/agent-create-form.tsx b/src/web/src/components/agent-create-form.tsx
index 1dd2591b8..bb9ce28b7 100644
--- a/src/web/src/components/agent-create-form.tsx
+++ b/src/web/src/components/agent-create-form.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useState, useRef } from "react";
+import { useState, useRef, useEffect } from "react";
import { Button } from "@/components/ui/button";
import type { AgentRuntime as Runtime } from "@alook/shared";
import {
@@ -30,6 +30,8 @@ interface AgentCreateFormProps {
runtimes: Runtime[];
defaultRuntimeId?: string;
modelOptions?: Record<string, string[]>;
+ guided?: boolean;
+ onTourReady?: (startTour: () => void) => void;
onSave: (data: {
name: string;
description: string;
@@ -44,10 +46,52 @@ interface AgentCreateFormProps {
saving: boolean;
}
+// Stable initial config to avoid hydration mismatch (randomConfig uses Math.random)
+const INITIAL_AVATAR: AvatarConfig = { shape: "circle", eye: "dots", nose: "dot", bg: 0 };
+
+async function runTour() {
+ const { driver } = await import("driver.js");
+ await import("driver.js/dist/driver.css");
+
+ const d = driver({
+ showProgress: true,
+ animate: true,
+ allowClose: true,
+ overlayClickBehavior: () => {},
+ overlayColor: "black",
+ overlayOpacity: 0.4,
+ popoverClass: "agent-tour-popover",
+ steps: [
+ {
+ element: "#agent-name",
+ popover: {
+ title: "Name your agent",
+ description: "Give your agent a name — this is how you'll identify it.",
+ side: "bottom" as const,
+ align: "start" as const,
+ },
+ },
+ {
+ element: "#agent-runtime-select",
+ disableActiveInteraction: false,
+ popover: {
+ title: "Choose a runtime",
+ description: "Select which machine and provider will run this agent.",
+ side: "bottom" as const,
+ align: "start" as const,
+ },
+ },
+ ],
+ });
+ d.drive();
+}
+
export function AgentCreateForm({
runtimes,
defaultRuntimeId = "",
modelOptions,
+ guided = false,
+ onTourReady,
onSave,
onCancel,
saving,
@@ -65,7 +109,16 @@ export function AgentCreateForm({
null
);
const [model, setModel] = useState("");
- const [avatarConfig, setAvatarConfig] = useState<AvatarConfig>(() => randomConfig());
+ const [avatarConfig, setAvatarConfig] = useState<AvatarConfig>(INITIAL_AVATAR);
+
+ // Randomize avatar on client mount to avoid hydration mismatch
+ const avatarInitialized = useRef(false);
+ useEffect(() => {
+ if (!avatarInitialized.current) {
+ avatarInitialized.current = true;
+ setAvatarConfig(randomConfig());
+ }
+ }, []);
const selectedRuntime = runtimes.find((r) => r.id === runtimeId);
const providerModels =
@@ -77,6 +130,18 @@ export function AgentCreateForm({
const effectiveHandle = emailHandle || derivedHandle;
const handleError = getHandleError(effectiveHandle);
+ // Driver.js guided tour for first-time agent creation
+ const driverStarted = useRef(false);
+ useEffect(() => {
+ onTourReady?.(() => runTour());
+ }, [onTourReady]);
+ useEffect(() => {
+ if (!guided || driverStarted.current) return;
+ driverStarted.current = true;
+ const timeout = setTimeout(() => runTour(), 500);
+ return () => clearTimeout(timeout);
+ }, [guided]);
+
const updateName = (value: string) => {
setName(value);
if (fieldErrors.name && value.trim()) {
@@ -85,7 +150,12 @@ export function AgentCreateForm({
};
const updateRuntimeId = (value: string) => {
+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;
+ const newProvider = runtimes.find((r) => r.id === value)?.provider;
setRuntimeId(value);
+ if (oldProvider && oldProvider !== newProvider) {
+ setModel("");
+ }
if (fieldErrors.runtimeId && value) {
setFieldErrors((prev) => ({ ...prev, runtimeId: undefined }));
}
@@ -134,6 +204,7 @@ export function AgentCreateForm({
runtimes={runtimes}
providerModels={providerModels}
errors={fieldErrors}
+ runtimeAsRadio
/>
<div className="border-t border-border/50 pt-4 mt-4 space-y-4">
diff --git a/src/web/src/components/agent-form-fields.tsx b/src/web/src/components/agent-form-fields.tsx
index 128b55995..2abe3eef4 100644
--- a/src/web/src/components/agent-form-fields.tsx
+++ b/src/web/src/components/agent-form-fields.tsx
@@ -22,6 +22,7 @@ import {
DialogClose,
} from "@/components/ui/dialog";
import { RuntimeSelect } from "@/components/runtime-select";
+import { ProviderLogo } from "@/components/provider-logo";
import { isValidHandle } from "@alook/shared";
import type { AgentRuntime as Runtime } from "@alook/shared";
import { cn } from "@/lib/utils";
@@ -72,6 +73,7 @@ interface GeneralFieldsProps {
name?: string;
runtimeId?: string;
};
+ runtimeAsRadio?: boolean;
}
export function GeneralFields({
@@ -88,6 +90,7 @@ export function GeneralFields({
runtimes,
providerModels,
errors,
+ runtimeAsRadio = false,
}: GeneralFieldsProps) {
return (
<>
@@ -153,26 +156,77 @@ export function GeneralFields({
</p>
</div>
- <div className="space-y-1.5">
- <Label htmlFor="agent-runtime">Runtime <span className="text-destructive">*</span></Label>
- <RuntimeSelect
- value={runtimeId}
- onValueChange={(newId) => {
- const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;
- const newProvider = runtimes.find((r) => r.id === newId)?.provider;
- setRuntimeId(newId);
- if (oldProvider && oldProvider !== newProvider) {
- setModel("");
- }
- }}
- runtimes={runtimes}
- triggerProps={{
- "aria-invalid": Boolean(errors?.runtimeId),
- "aria-describedby": errors?.runtimeId
- ? "agent-runtime-error"
- : undefined,
- }}
- />
+ <div id="agent-runtime-select" className="space-y-1.5">
+ <Label>Runtime <span className="text-destructive">*</span></Label>
+ {runtimeAsRadio ? (
+ <div className="space-y-1.5" role="radiogroup" aria-label="Runtime">
+ {runtimes.length === 0 ? (
+ <p className="text-xs text-muted-foreground">No runtimes — start a daemon first</p>
+ ) : (
+ runtimes.map((rt) => {
+ const isOnline = rt.status === "online";
+ const isSelected = runtimeId === rt.id;
+ const machine = typeof rt.device_info === "string" ? rt.device_info : "";
+ return (
+ <label
+ key={rt.id}
+ className={cn(
+ "flex items-center gap-2.5 rounded-lg border p-2.5 cursor-pointer transition-colors",
+ isSelected
+ ? "border-primary bg-primary/5"
+ : "border-border hover:border-foreground/20",
+ !isOnline && "opacity-40 pointer-events-none"
+ )}
+ >
+ <input
+ type="radio"
+ name="runtime"
+ value={rt.id}
+ checked={isSelected}
+ disabled={!isOnline}
+ onChange={() => {
+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;
+ const newProvider = rt.provider;
+ setRuntimeId(rt.id);
+ if (oldProvider && oldProvider !== newProvider) {
+ setModel("");
+ }
+ }}
+ className="accent-primary size-3.5"
+ />
+ <ProviderLogo provider={rt.provider} className="h-4 w-4 shrink-0" />
+ <span className="text-sm">{rt.provider}</span>
+ {machine && (
+ <span className="text-xs text-muted-foreground">{machine}</span>
+ )}
+ {!isOnline && (
+ <span className="text-xs text-muted-foreground ml-auto">offline</span>
+ )}
+ </label>
+ );
+ })
+ )}
+ </div>
+ ) : (
+ <RuntimeSelect
+ value={runtimeId}
+ onValueChange={(newId) => {
+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;
+ const newProvider = runtimes.find((r) => r.id === newId)?.provider;
+ setRuntimeId(newId);
+ if (oldProvider && oldProvider !== newProvider) {
+ setModel("");
+ }
+ }}
+ runtimes={runtimes}
+ triggerProps={{
+ "aria-invalid": Boolean(errors?.runtimeId),
+ "aria-describedby": errors?.runtimeId
+ ? "agent-runtime-error"
+ : undefined,
+ }}
+ />
+ )}
{errors?.runtimeId && (
<p id="agent-runtime-error" className="text-xs text-destructive">
{errors.runtimeId}