@saadnvd1/agent-os 0.3.520 → 0.3.521

package/README.md

@@ -213,6 +213,17 @@ its WSL note, and Windows reached it at both `localhost:3011` and
 `wslview`/`explorer.exe`, mirrored networking, `agent-os enable` under
 systemd, the idle-timeout settings above, and Debian or other distros.
 
+### First run
+
+On a fresh install (no sessions, no projects of your own) the web app opens a
+short setup at `/?welcome`: it shows each agent CLI as ready, needing a
+sign-in, or missing, installs or signs one in from an embedded terminal, adds
+a first project (a folder, a clone or an empty one), then opens a session in
+it. Every step after the first can be skipped. It is remembered on the server,
+so a phone you pair later doesn't see it, and an install that already has work
+never does. Reopen it from Settings → Setup (**Run setup again**) or at
+`/welcome`; `AGENTOS_SKIP_WELCOME=1` turns it off.
+
 ### Supported agents
 
 | Agent       | Chat | Resume | Fork | Auto-approve                                 |

package/app/api/welcome/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { demoMode } from "@/lib/security/demo";
+import { completeWelcome, readWelcomeGate } from "@/lib/welcome";
+
+// Whether the first-run welcome should open on this server. An install
+// already in use is marked done here, so emptying it later doesn't bring it back.
+export async function GET() {
+  return NextResponse.json(readWelcomeGate(demoMode()));
+}
+
+// { action: "complete" }: setup finished or skipped.
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    if (body?.action !== "complete") throw new Error("Unknown action");
+    completeWelcome(new Date().toISOString(), undefined, true);
+    return NextResponse.json(readWelcomeGate(demoMode()));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

package/app/page.tsx

@@ -78,6 +78,11 @@ const SettingsDialog = dynamic(
     ),
   { ssr: false }
 );
+const WelcomeDialog = dynamic(
+  () =>
+    import("@/components/Welcome/WelcomeDialog").then((m) => m.WelcomeDialog),
+  { ssr: false }
+);
 const MessagesDialog = dynamic(
   () => import("@/components/Bus/MessagesDialog").then((m) => m.MessagesDialog),
   { ssr: false }
@@ -122,6 +127,7 @@ const AppDialogs = memo(function AppDialogs() {
   return (
     <>
       <TasksDialog />
+      <WelcomeDialog />
       <AddProjectDialog />
       <MessagesDialog />
       <ArchivedDialog />

package/app/welcome/page.tsx

@@ -0,0 +1,6 @@
+import { redirect } from "next/navigation";
+
+// Reopens the first-run welcome.
+export default function WelcomePage() {
+  redirect("/?welcome=agents");
+}

package/components/Projects/AddProject/AddProjectDialog.tsx

@@ -29,8 +29,8 @@ export function AddProjectDialog() {
   const { open } = useSnapshot(addProjectUi);
   const hostNames = useHostNames();
   const done = (projectId: string) => {
-    addProjectActions.close();
-    newDraft({ kind: "project", projectId });
+    if (!addProjectActions.finish(projectId))
+      newDraft({ kind: "project", projectId });
   };
 
   return (

package/components/Settings/SettingsDialog.tsx

@@ -11,6 +11,7 @@ import {
   Cpu,
   GitMerge,
   LayoutGrid,
+  ListChecks,
   Smartphone,
   X,
   type LucideIcon,
@@ -34,6 +35,7 @@ import { SETTINGS_SECTIONS, type SettingsSection } from "@/lib/settings-url";
 import { cn } from "@/lib/utils";
 import { schedulesUiActions } from "@/stores/schedulesUi";
 import { settingsUi, settingsUiActions } from "@/stores/settingsUi";
+import { SetupSection } from "./SetupSection";
 import {
   NotificationsSection,
   type BrowserNotifications,
@@ -78,6 +80,11 @@ export const SECTION_INFO: Record<
     hint: "Where sessions spent tokens and repeated work",
     icon: ClipboardList,
   },
+  setup: {
+    label: "Setup",
+    hint: "Agents on this machine, first-run setup",
+    icon: ListChecks,
+  },
 };
 
 function SectionBody({
@@ -102,6 +109,8 @@ function SectionBody({
       return <SchedulesPanel />;
     case "audits":
       return <AuditsPanel />;
+    case "setup":
+      return <SetupSection />;
   }
 }
 

package/components/Settings/SetupSection.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { AgentList } from "@/components/Welcome/AgentList";
+import { settingsUiActions } from "@/stores/settingsUi";
+import { welcomeUiActions } from "@/stores/welcomeUi";
+
+// What this machine has for running agents, and the first-run setup again.
+export function SetupSection() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="bg-muted/40 flex items-center gap-3 rounded-lg px-3 py-2.5">
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-medium">First-run setup</p>
+          <p className="text-muted-foreground text-xs">
+            Agents, your first project, and a first session.
+          </p>
+        </div>
+        <Button
+          size="sm"
+          variant="outline"
+          className="min-h-11 sm:min-h-8"
+          onClick={() => {
+            settingsUiActions.close();
+            welcomeUiActions.open("agents");
+          }}
+        >
+          Run setup again
+        </Button>
+      </div>
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-medium">Agents on this machine</h3>
+        <AgentList />
+      </div>
+    </div>
+  );
+}

package/components/Welcome/AgentList.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useAgentStatusQuery, useRecheckAgents } from "@/data/agents";
+import { FEATURED_AGENTS } from "@/lib/agents/setup-commands";
+import { getAllProviderDefinitions } from "@/lib/providers/registry";
+import { AgentRow, type AgentRun } from "./AgentRow";
+import { SetupTerminal } from "./SetupTerminal";
+
+/**
+ * Every agent CLI on this machine with what it needs, and an embedded
+ * terminal to install or sign one in. Checks again when it opens and when a
+ * terminal is closed, never on a timer.
+ */
+export function AgentList() {
+  const { data: agents } = useAgentStatusQuery();
+  const recheck = useRecheckAgents();
+  const [run, setRun] = useState<(AgentRun & { key: number }) | null>(null);
+  const [all, setAll] = useState(false);
+  const { mutate } = recheck;
+
+  useEffect(() => mutate(), [mutate]);
+
+  const providers = getAllProviderDefinitions().filter((p) => p.cli);
+  const shown = providers.filter((p) => all || FEATURED_AGENTS.includes(p.id));
+  const hidden = providers.length - shown.length;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <ul className="flex flex-col gap-2">
+        {shown.map((p) => (
+          <AgentRow
+            key={p.id}
+            provider={p}
+            probe={agents?.[p.id]}
+            onRun={(r) => setRun({ ...r, key: Date.now() })}
+          />
+        ))}
+      </ul>
+      {run && (
+        <SetupTerminal
+          key={run.key}
+          title={run.title}
+          command={run.command}
+          onDone={() => {
+            setRun(null);
+            mutate();
+          }}
+        />
+      )}
+      <div className="flex items-center justify-between gap-2">
+        {hidden > 0 ? (
+          <Button size="sm" variant="ghost" onClick={() => setAll(true)}>
+            Show {hidden} more
+          </Button>
+        ) : (
+          <span />
+        )}
+        <Button
+          size="sm"
+          variant="ghost"
+          disabled={recheck.isPending}
+          onClick={() => mutate()}
+        >
+          <RefreshCw className={recheck.isPending ? "animate-spin" : ""} />
+          Check again
+        </Button>
+      </div>
+    </div>
+  );
+}

package/components/Welcome/AgentRow.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { Check, Download, LogIn } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import type { AgentProbe } from "@/lib/agents/probe";
+import { agentState, SETUP_COMMANDS } from "@/lib/agents/setup-commands";
+import type { ProviderDefinition } from "@/lib/providers/registry";
+
+const LABEL = {
+  missing: "Not installed",
+  "needs-login": "Needs sign-in",
+  ready: "Ready",
+  installed: "Installed",
+} as const;
+
+export type AgentRun = { title: string; command: string };
+
+/** One agent CLI: its state, and the install or sign-in it needs. */
+export function AgentRow({
+  provider,
+  probe,
+  onRun,
+}: {
+  provider: ProviderDefinition;
+  probe: AgentProbe | undefined;
+  onRun: (run: AgentRun) => void;
+}) {
+  const state = probe ? agentState(probe) : null;
+  const commands = SETUP_COMMANDS[provider.id];
+  return (
+    <li className="bg-muted/40 flex min-h-11 items-center gap-3 rounded-lg px-3 py-2">
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-sm font-medium">{provider.name}</p>
+        <p className="text-muted-foreground truncate text-xs">
+          {probe?.version
+            ? `v${probe.version}`
+            : (probe?.hint ?? provider.description)}
+        </p>
+      </div>
+      {!state && <Badge variant="outline">Checking</Badge>}
+      {state === "ready" && (
+        <Badge variant="success">
+          <Check className="mr-1 size-3" />
+          {LABEL.ready}
+        </Badge>
+      )}
+      {state === "installed" && <Badge variant="outline">{LABEL[state]}</Badge>}
+      {state === "needs-login" && (
+        <>
+          <Badge variant="secondary">{LABEL[state]}</Badge>
+          {commands?.signIn && (
+            <Button
+              size="sm"
+              variant="outline"
+              className="min-h-11 sm:min-h-8"
+              onClick={() =>
+                onRun({
+                  title: `Sign in to ${provider.name}`,
+                  command: commands.signIn!,
+                })
+              }
+            >
+              <LogIn />
+              Sign in
+            </Button>
+          )}
+        </>
+      )}
+      {state === "missing" &&
+        (commands?.install ? (
+          <Button
+            size="sm"
+            variant="outline"
+            className="min-h-11 sm:min-h-8"
+            onClick={() =>
+              onRun({
+                title: `Install ${provider.name}`,
+                command: commands.install!,
+              })
+            }
+          >
+            <Download />
+            Install
+          </Button>
+        ) : commands?.docs ? (
+          <Button
+            size="sm"
+            variant="outline"
+            className="min-h-11 sm:min-h-8"
+            asChild
+          >
+            <a href={commands.docs} target="_blank" rel="noreferrer">
+              How to install
+            </a>
+          </Button>
+        ) : (
+          <Badge variant="outline">{LABEL.missing}</Badge>
+        ))}
+    </li>
+  );
+}

package/components/Welcome/ProjectStep.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { FolderGit2, FolderOpen, FolderPlus, Check } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useProjectsQuery } from "@/data/projects/queries";
+import { cn } from "@/lib/utils";
+import { addProjectActions, type AddProjectKind } from "@/stores/addProject";
+import { welcomeUi, welcomeUiActions } from "@/stores/welcomeUi";
+import { useSnapshot } from "valtio";
+
+const WAYS: {
+  kind: AddProjectKind;
+  title: string;
+  hint: string;
+  icon: typeof FolderOpen;
+}[] = [
+  {
+    kind: "folder",
+    title: "Open a folder",
+    hint: "A project already on this machine",
+    icon: FolderOpen,
+  },
+  {
+    kind: "clone",
+    title: "Clone a repo",
+    hint: "From a Git URL",
+    icon: FolderGit2,
+  },
+  {
+    kind: "name",
+    title: "Start an empty project",
+    hint: "A new folder with a name",
+    icon: FolderPlus,
+  },
+];
+
+/** Add the project the first session will open in, or pick one already there. */
+export function ProjectStep() {
+  const { projectId } = useSnapshot(welcomeUi);
+  const { data: projects = [] } = useProjectsQuery();
+  const own = projects.filter((p) => !p.is_uncategorized);
+
+  const add = (kind: AddProjectKind) =>
+    addProjectActions.show(kind, "local", (id) => {
+      welcomeUiActions.setProject(id);
+      welcomeUiActions.go("finish");
+    });
+
+  return (
+    <div className="flex flex-col gap-3">
+      {own.length > 0 && (
+        <ul className="flex flex-col gap-2">
+          {own.map((p) => (
+            <li key={p.id}>
+              <button
+                type="button"
+                onClick={() => {
+                  welcomeUiActions.setProject(p.id);
+                  welcomeUiActions.go("finish");
+                }}
+                className={cn(
+                  "bg-muted/40 hover:bg-accent flex min-h-11 w-full items-center gap-3 rounded-lg px-3 py-2 text-left",
+                  projectId === p.id && "ring-primary/40 ring-2"
+                )}
+              >
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate text-sm font-medium">
+                    {p.name}
+                  </span>
+                  <span className="text-muted-foreground block truncate text-xs">
+                    {p.working_directory}
+                  </span>
+                </span>
+                {projectId === p.id && <Check className="size-4" />}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <div className="flex flex-col gap-2">
+        {WAYS.map((w) => (
+          <Button
+            key={w.kind}
+            variant="outline"
+            className="h-auto min-h-11 justify-start gap-3 px-3 py-2.5 text-left"
+            onClick={() => add(w.kind)}
+          >
+            <w.icon />
+            <span className="min-w-0">
+              <span className="block text-sm font-medium">{w.title}</span>
+              <span className="text-muted-foreground block text-xs font-normal">
+                {w.hint}
+              </span>
+            </span>
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+}

package/components/Welcome/SetupTerminal.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import dynamic from "next/dynamic";
+import { Button } from "@/components/ui/button";
+import type { TerminalHandle } from "@/components/Terminal";
+
+const Terminal = dynamic(
+  () => import("@/components/Terminal").then((m) => m.Terminal),
+  { ssr: false }
+);
+
+/**
+ * A terminal on this machine with one setup command typed at the prompt, for
+ * the user to read and run with Enter. It goes into their own shell over the
+ * existing terminal socket; the server runs nothing.
+ */
+export function SetupTerminal({
+  title,
+  command,
+  onDone,
+}: {
+  title: string;
+  command: string;
+  onDone: () => void;
+}) {
+  const ref = useRef<TerminalHandle | null>(null);
+  const typed = useRef(false);
+  const box = useRef<HTMLDivElement>(null);
+
+  // On a phone it opens below the list, out of sight.
+  useEffect(() => {
+    box.current?.scrollIntoView?.({ block: "nearest", behavior: "smooth" });
+  }, []);
+
+  const connected = useCallback(() => {
+    if (typed.current) return;
+    typed.current = true;
+    setTimeout(() => {
+      ref.current?.sendInput("\x15");
+      // Typed, not run: the user reads it and presses Enter.
+      setTimeout(() => ref.current?.sendInput(command), 50);
+    }, 100);
+  }, [command]);
+
+  return (
+    <div
+      ref={box}
+      className="bg-muted/30 hairline flex flex-col overflow-hidden rounded-lg"
+    >
+      <div className="flex items-center justify-between gap-2 px-3 py-1.5">
+        <span className="text-muted-foreground truncate text-xs">
+          {title}. Press Enter to run it.
+        </span>
+        <Button size="sm" onClick={onDone}>
+          Done, check again
+        </Button>
+      </div>
+      <div className="h-64 min-h-0">
+        <Terminal ref={ref} onConnected={connected} />
+      </div>
+    </div>
+  );
+}

package/components/Welcome/WelcomeDialog.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import { memo } from "react";
+import { useSnapshot } from "valtio";
+import { Check } from "lucide-react";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { useProjectsQuery } from "@/data/projects/queries";
+import { useEndWelcome, useWelcomeUrl } from "@/hooks/useWelcome";
+import { cn } from "@/lib/utils";
+import { WELCOME_STEPS, type WelcomeStep } from "@/lib/welcome-url";
+import { welcomeUi, welcomeUiActions } from "@/stores/welcomeUi";
+import { AgentList } from "./AgentList";
+import { ProjectStep } from "./ProjectStep";
+
+const STEPS: Record<
+  WelcomeStep,
+  { label: string; title: string; hint: string }
+> = {
+  agents: {
+    label: "Agents",
+    title: "Connect your agents",
+    hint: "Install and sign in the coding agents you want to use. You need one.",
+  },
+  project: {
+    label: "Project",
+    title: "Add your first project",
+    hint: "A folder or repo for the first session to work in.",
+  },
+  finish: {
+    label: "Start",
+    title: "You're set",
+    hint: "Open a session in your project and give it a task.",
+  },
+};
+
+function FinishStep() {
+  const { projectId } = useSnapshot(welcomeUi);
+  const { data: projects = [] } = useProjectsQuery();
+  const project = projects.find((p) => p.id === projectId);
+  return (
+    <p className="text-muted-foreground bg-muted/40 rounded-lg px-3 py-3 text-sm">
+      {project ? (
+        <>
+          First session opens in{" "}
+          <span className="text-foreground font-medium">{project.name}</span>.
+        </>
+      ) : (
+        "No project yet. Add one from the sidebar whenever you are ready."
+      )}
+    </p>
+  );
+}
+
+/**
+ * First-run setup: agents, then a first project, then a session. It stays
+ * open until finished or skipped, and every step after the first can be skipped.
+ */
+export const WelcomeDialog = memo(function WelcomeDialog() {
+  useWelcomeUrl();
+  const { open, step, projectId } = useSnapshot(welcomeUi);
+  const end = useEndWelcome();
+  const at = WELCOME_STEPS.indexOf(step);
+  const info = STEPS[step];
+  const last = at === WELCOME_STEPS.length - 1;
+
+  return (
+    <Dialog open={open}>
+      <DialogContent
+        showCloseButton={false}
+        onInteractOutside={(e) => e.preventDefault()}
+        onEscapeKeyDown={(e) => e.preventDefault()}
+        className="max-h-[100dvh] overflow-y-auto max-sm:h-[100dvh] max-sm:max-w-full max-sm:rounded-none sm:max-h-[90dvh] sm:max-w-xl"
+      >
+        <nav aria-label="Setup steps" className="flex items-center gap-1">
+          {WELCOME_STEPS.map((s, i) => (
+            <button
+              key={s}
+              type="button"
+              disabled={i === at}
+              onClick={() => welcomeUiActions.go(s)}
+              aria-current={i === at ? "step" : undefined}
+              className={cn(
+                "flex min-h-11 flex-1 items-center justify-center gap-1.5 rounded-lg px-2 text-xs font-medium sm:min-h-8",
+                i === at
+                  ? "bg-foreground/[0.08] text-foreground"
+                  : "text-muted-foreground hover:bg-foreground/[0.06]"
+              )}
+            >
+              {i < at && <Check className="size-3" />}
+              {STEPS[s].label}
+            </button>
+          ))}
+          <Button
+            variant="ghost"
+            size="sm"
+            className="min-h-11 sm:min-h-8"
+            onClick={() => end()}
+          >
+            Skip setup
+          </Button>
+        </nav>
+        <div className="flex flex-col gap-1">
+          <DialogTitle>{info.title}</DialogTitle>
+          <DialogDescription>{info.hint}</DialogDescription>
+        </div>
+        {step === "agents" && <AgentList />}
+        {step === "project" && <ProjectStep />}
+        {step === "finish" && <FinishStep />}
+        <div className="flex items-center justify-between gap-2">
+          <Button
+            variant="ghost"
+            className="min-h-11 sm:min-h-9"
+            disabled={at === 0}
+            onClick={() => welcomeUiActions.go(WELCOME_STEPS[at - 1])}
+          >
+            Back
+          </Button>
+          <div className="flex items-center gap-2">
+            {step === "project" && (
+              <Button
+                variant="ghost"
+                className="min-h-11 sm:min-h-9"
+                onClick={() => welcomeUiActions.go("finish")}
+              >
+                Skip
+              </Button>
+            )}
+            <Button
+              className="min-h-11 sm:min-h-9"
+              onClick={() =>
+                last ? end(true) : welcomeUiActions.go(WELCOME_STEPS[at + 1])
+              }
+            >
+              {last
+                ? projectId
+                  ? "Start your first session"
+                  : "Go to AgentOS"
+                : step === "agents"
+                  ? "Continue"
+                  : "Next"}
+            </Button>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+});

package/data/agents/index.ts

@@ -1,4 +1,4 @@
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { AgentProbe } from "@/lib/agents/probe";
 
 export const agentKeys = {
@@ -20,3 +20,18 @@ export function useAgentStatusQuery() {
     refetchOnMount: "always",
   });
 }
+
+// Asks the server to probe again now, not from its minute-old answer, and
+// puts the result where the status query reads it.
+export function useRecheckAgents() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await fetch("/api/agents/status?fresh");
+      if (!res.ok) throw new Error("Couldn't check the agents");
+      return ((await res.json()) as { agents: Record<string, AgentProbe> })
+        .agents;
+    },
+    onSuccess: (agents) => client.setQueryData(agentKeys.status(), agents),
+  });
+}

package/data/welcome/index.ts

@@ -0,0 +1,36 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { WelcomeGate } from "@/lib/welcome";
+
+export const welcomeKeys = {
+  all: ["welcome"] as const,
+};
+
+export function useWelcomeQuery() {
+  return useQuery({
+    queryKey: welcomeKeys.all,
+    queryFn: async () => {
+      const res = await fetch("/api/welcome");
+      if (!res.ok) throw new Error("Couldn't check first-run setup");
+      return (await res.json()) as WelcomeGate;
+    },
+    // Asked once per load: it only flips when setup is done here.
+    staleTime: Infinity,
+    retry: false,
+  });
+}
+
+export function useCompleteWelcome() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await fetch("/api/welcome", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ action: "complete" }),
+      });
+      if (!res.ok) throw new Error("Couldn't save setup");
+      return (await res.json()) as WelcomeGate;
+    },
+    onSuccess: (gate) => client.setQueryData(welcomeKeys.all, gate),
+  });
+}

package/hooks/useWelcome.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { subscribe } from "valtio";
+import { useCompleteWelcome, useWelcomeQuery } from "@/data/welcome";
+import { hrefWithWelcome, welcomeFromHref } from "@/lib/welcome-url";
+import { newDraft } from "@/stores/drafts";
+import { welcomeUi, welcomeUiActions } from "@/stores/welcomeUi";
+
+function fromAddress() {
+  const at = welcomeFromHref(window.location.href);
+  if (at.open) welcomeUiActions.open(at.step);
+  else if (welcomeUi.open) welcomeUiActions.close();
+}
+
+/**
+ * `?welcome=<step>` opens the first-run welcome at that step, on load and on
+ * back/forward; the address follows it. Moving between steps adds a history
+ * entry, so Back goes to the step before. A fresh install with setup still to
+ * do opens it by itself, once.
+ */
+export function useWelcomeUrl() {
+  const { data: gate } = useWelcomeQuery();
+  const asked = useRef(false);
+
+  useEffect(() => {
+    fromAddress();
+    let was = { open: welcomeUi.open, step: welcomeUi.step };
+    const unsubscribe = subscribe(welcomeUi, () => {
+      const href = window.location.href;
+      const next = hrefWithWelcome(href, {
+        open: welcomeUi.open,
+        step: welcomeUi.step,
+      });
+      const url = new URL(href);
+      if (next !== url.pathname + url.search + url.hash) {
+        const move = was.open && welcomeUi.open && was.step !== welcomeUi.step;
+        window.history[move ? "pushState" : "replaceState"](
+          window.history.state,
+          "",
+          next
+        );
+      }
+      was = { open: welcomeUi.open, step: welcomeUi.step };
+    });
+    window.addEventListener("popstate", fromAddress);
+    return () => {
+      unsubscribe();
+      window.removeEventListener("popstate", fromAddress);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!gate?.show || asked.current || welcomeUi.open) return;
+    asked.current = true;
+    welcomeUiActions.open("agents");
+  }, [gate?.show]);
+}
+
+/** Setup is over, finished or skipped: remember it and close. */
+export function useEndWelcome() {
+  const { mutate } = useCompleteWelcome();
+  return (start?: boolean) => {
+    const projectId = welcomeUi.projectId;
+    mutate();
+    welcomeUiActions.close();
+    welcomeUiActions.setProject(null);
+    if (start && projectId) newDraft({ kind: "project", projectId });
+  };
+}

package/lib/agents/probe.ts

@@ -64,7 +64,34 @@ type AuthCheck = (
   env: NodeJS.ProcessEnv
 ) => Promise<AgentAuth> | AgentAuth;
 
+// Claude Code keeps who is signed in under `oauthAccount` in its config, at
+// $CLAUDE_CONFIG_DIR/.claude.json, or ~/.claude.json without that variable.
+function claudeAuth(env: NodeJS.ProcessEnv): AgentAuth {
+  const dir = env.CLAUDE_CONFIG_DIR?.trim();
+  const configDir = dir || home(".claude");
+  const config = dir ? path.join(dir, ".claude.json") : home(".claude.json");
+  if (
+    anyEnv(env, [
+      "ANTHROPIC_API_KEY",
+      "ANTHROPIC_AUTH_TOKEN",
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "CLAUDE_CODE_USE_BEDROCK",
+      "CLAUDE_CODE_USE_VERTEX",
+    ]) ||
+    hasJsonKeys(path.join(configDir, "settings.json"), "apiKeyHelper")
+  )
+    return "ready";
+  if (hasJsonKeys(config, "oauthAccount")) return "ready";
+  // A config without an account is a CLI that has never signed in; no config
+  // at all tells nothing.
+  return hasJsonKeys(config) ? "needs-login" : "unknown";
+}
+
 const AUTH: Partial<Record<ProviderId, { check: AuthCheck; hint: string }>> = {
+  claude: {
+    check: (_cli, env) => claudeAuth(env),
+    hint: "Run `claude auth login` in a terminal",
+  },
   codex: {
     // Exits 0 signed in, 1 not.
     check: async (cli, env) => {

package/lib/agents/setup-commands.ts

@@ -0,0 +1,54 @@
+/**
+ * The official commands the welcome runs in its terminal to install an agent
+ * CLI or sign it in. Typed into the user's own shell, never run by the
+ * server, so they are the same lines the install script (scripts/lib/ai-clis.sh)
+ * uses.
+ */
+
+import type { ProviderId } from "../providers/registry";
+
+export interface SetupCommands {
+  install?: string;
+  signIn?: string;
+  docs?: string;
+}
+
+export const SETUP_COMMANDS: Partial<Record<ProviderId, SetupCommands>> = {
+  claude: {
+    install: "curl -fsSL https://claude.ai/install.sh | bash",
+    signIn: "claude auth login",
+  },
+  codex: {
+    install: "npm install -g @openai/codex",
+    signIn: "codex login",
+  },
+  gemini: {
+    install: "npm install -g @google/gemini-cli",
+    signIn: "gemini",
+  },
+  kilocode: { install: "npm install -g @kilocode/cli", signIn: "kilo" },
+  cursor: { signIn: "cursor-agent login", docs: "https://cursor.com/cli" },
+  amp: { signIn: "amp login", docs: "https://ampcode.com" },
+  pi: { signIn: "pi" },
+  // No installer line we can vouch for from here; its own site has it.
+  opencode: { docs: "https://opencode.ai/docs" },
+};
+
+// The ones the welcome shows up front; the rest wait behind "Show all".
+export const FEATURED_AGENTS: ProviderId[] = [
+  "claude",
+  "codex",
+  "gemini",
+  "opencode",
+];
+
+export type AgentState = "missing" | "needs-login" | "ready" | "installed";
+
+export function agentState(p: {
+  installed: boolean;
+  auth: "ready" | "needs-login" | "unknown";
+}): AgentState {
+  if (!p.installed) return "missing";
+  if (p.auth === "needs-login") return "needs-login";
+  return p.auth === "ready" ? "ready" : "installed";
+}

package/lib/db/migrations.ts

@@ -1754,6 +1754,20 @@ const migrations: Migration[] = [
           db.exec(`ALTER TABLE ${table} ADD COLUMN plan_only INTEGER`);
     },
   },
+  {
+    id: 76,
+    name: "welcome_backfill",
+    up: (db) => {
+      // An install that already has a session or a project of its own has
+      // been set up; mark it so the first-run welcome never shows there.
+      db.exec(
+        `INSERT OR IGNORE INTO settings (key, value)
+         SELECT 'welcome.completed_at', 'existing-install'
+         WHERE EXISTS (SELECT 1 FROM sessions)
+            OR EXISTS (SELECT 1 FROM projects WHERE is_uncategorized = 0)`
+      );
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/settings-url.ts

@@ -12,6 +12,7 @@ export const SETTINGS_SECTIONS = [
   "notifications",
   "schedules",
   "audits",
+  "setup",
 ] as const;
 
 export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];

package/lib/welcome-url.ts

@@ -0,0 +1,33 @@
+// The welcome has its own address: `/?welcome=<step>`, beside `?settings=`
+// and `?session=`. `/welcome` redirects here.
+
+export const WELCOME_PARAM = "welcome";
+
+export const WELCOME_STEPS = ["agents", "project", "finish"] as const;
+
+export type WelcomeStep = (typeof WELCOME_STEPS)[number];
+
+export interface WelcomeLocation {
+  open: boolean;
+  step: WelcomeStep;
+}
+
+const BASE = "http://agentos.invalid";
+
+export const isWelcomeStep = (v: unknown): v is WelcomeStep =>
+  (WELCOME_STEPS as readonly unknown[]).includes(v);
+
+/** What the address says; a bare or unknown step starts at the first. */
+export function welcomeFromHref(href: string): WelcomeLocation {
+  const value = new URL(href, BASE).searchParams.get(WELCOME_PARAM);
+  if (value === null) return { open: false, step: WELCOME_STEPS[0] };
+  return { open: true, step: isWelcomeStep(value) ? value : WELCOME_STEPS[0] };
+}
+
+/** The same address with the welcome set (or removed), as path+query+hash. */
+export function hrefWithWelcome(href: string, at: WelcomeLocation): string {
+  const url = new URL(href, BASE);
+  if (at.open) url.searchParams.set(WELCOME_PARAM, at.step);
+  else url.searchParams.delete(WELCOME_PARAM);
+  return url.pathname + url.search + url.hash;
+}

package/lib/welcome.ts

@@ -0,0 +1,88 @@
+/**
+ * First-run welcome: shown once on a fresh install, never on one that
+ * already has work. Completion is the server's (one server, many devices),
+ * kept in `settings` as an ISO time, or "existing-install" when the install
+ * was already in use.
+ */
+
+import type Database from "better-sqlite3";
+import { db } from "./db";
+
+export const WELCOME_KEY = "welcome.completed_at";
+export const EXISTING_INSTALL = "existing-install";
+
+export interface WelcomeGate {
+  // The welcome should open now.
+  show: boolean;
+  // No sessions and no project of the user's own.
+  fresh: boolean;
+  completedAt: string | null;
+}
+
+export interface GateInput {
+  completedAt: string | null;
+  sessionCount: number;
+  // Projects other than the built-in Uncategorized one.
+  projectCount: number;
+  demo: boolean;
+  skip: boolean;
+}
+
+export function welcomeGate(i: GateInput): WelcomeGate {
+  const fresh = i.sessionCount === 0 && i.projectCount === 0;
+  return {
+    show: !i.completedAt && fresh && !i.demo && !i.skip,
+    fresh,
+    completedAt: i.completedAt,
+  };
+}
+
+export function readCompletedAt(d: Database.Database = db): string | null {
+  const row = d
+    .prepare(`SELECT value FROM settings WHERE key = ?`)
+    .get(WELCOME_KEY) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+// Keeps the first stamp unless `overwrite`.
+export function completeWelcome(
+  value: string = new Date().toISOString(),
+  d: Database.Database = db,
+  overwrite = false
+): void {
+  d.prepare(
+    overwrite
+      ? `INSERT INTO settings (key, value) VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      : `INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)`
+  ).run(WELCOME_KEY, value);
+}
+
+export function counts(d: Database.Database = db) {
+  const n = (sql: string) => (d.prepare(sql).get() as { n: number }).n;
+  return {
+    sessionCount: n(`SELECT COUNT(*) AS n FROM sessions`),
+    projectCount: n(
+      `SELECT COUNT(*) AS n FROM projects WHERE is_uncategorized = 0`
+    ),
+  };
+}
+
+/** The gate for this server. An install found in use is stamped as such. */
+export function readWelcomeGate(
+  demo: boolean,
+  d: Database.Database = db
+): WelcomeGate {
+  const c = counts(d);
+  let completedAt = readCompletedAt(d);
+  if (!completedAt && (c.sessionCount > 0 || c.projectCount > 0)) {
+    completeWelcome(EXISTING_INSTALL, d);
+    completedAt = readCompletedAt(d);
+  }
+  return welcomeGate({
+    completedAt,
+    ...c,
+    demo,
+    skip: !!process.env.AGENTOS_SKIP_WELCOME,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.520",
+  "version": "0.3.521",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"

package/stores/addProject.ts

@@ -13,14 +13,32 @@ export const addProjectUi = proxy<{
   } | null;
 }>({ open: null });
 
+// Who asked for the dialog and wants the new project instead of the draft
+// that opens in it. A function, so it stays out of the proxy.
+let onProjectAdded: ((projectId: string) => void) | null = null;
+
 export const addProjectActions = {
-  show: (kind: AddProjectKind, hostId: string) => {
+  show: (
+    kind: AddProjectKind,
+    hostId: string,
+    onDone?: (projectId: string) => void
+  ) => {
+    onProjectAdded = onDone ?? null;
     addProjectUi.open = { kind, hostId, workspaceId: sidebarUi.workspaceId };
   },
+  /** Called once a project is made; false if nobody took it over. */
+  finish: (projectId: string): boolean => {
+    const handler = onProjectAdded;
+    addProjectActions.close();
+    if (!handler) return false;
+    handler(projectId);
+    return true;
+  },
   setWorkspace: (workspaceId: string | null) => {
     if (addProjectUi.open) addProjectUi.open.workspaceId = workspaceId;
   },
   close: () => {
+    onProjectAdded = null;
     addProjectUi.open = null;
   },
 };

package/stores/welcomeUi.ts

@@ -0,0 +1,26 @@
+import { proxy } from "valtio";
+import type { WelcomeStep } from "@/lib/welcome-url";
+
+// The first-run welcome: whether it is on show, the step, and the project
+// the user made (or picked) to start in.
+export const welcomeUi = proxy<{
+  open: boolean;
+  step: WelcomeStep;
+  projectId: string | null;
+}>({ open: false, step: "agents", projectId: null });
+
+export const welcomeUiActions = {
+  open: (step: WelcomeStep = "agents") => {
+    welcomeUi.step = step;
+    welcomeUi.open = true;
+  },
+  go: (step: WelcomeStep) => {
+    welcomeUi.step = step;
+  },
+  setProject: (projectId: string | null) => {
+    welcomeUi.projectId = projectId;
+  },
+  close: () => {
+    welcomeUi.open = false;
+  },
+};