feat(dev): ENABLE_DEV_AUTH — run the stack without Clerk for local dev

apps/web/.env.example

@@ -12,3 +12,8 @@ VITE_FASTAPI_URL=http://localhost:8000
 
 # Arcjet (server-only rate limiting / shield — copy from Arcjet dashboard)
 ARCJET_KEY=
+
+# LOCAL DEVELOPMENT ONLY — bypass Clerk entirely and sign in as a fixed dev user.
+# Pair with ENABLE_DEV_AUTH on the Convex deployment and the FastAPI gateway.
+# NEVER set this in production.
+# VITE_ENABLE_DEV_AUTH=true

apps/web/src/components/chat/chat-input.tsx

@@ -1,4 +1,3 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
@@ -29,6 +28,7 @@ import React, {
 	useState,
 } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import { useFileAttachments } from "../../hooks/use-file-attachments";
 import {
 	AGENT_MODES,

apps/web/src/components/chat/conversation-kebab.tsx

@@ -1,4 +1,3 @@
-import { useUser } from "@clerk/tanstack-react-start";
 import { useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
@@ -16,6 +15,7 @@ import {
 } from "lucide-react";
 import { useState } from "react";
 import toast from "react-hot-toast";
+import { useUser } from "@/lib/auth";
 import {
 	buildShareUrl,
 	copyToClipboard,

apps/web/src/components/chat/settings-dialog.tsx

@@ -1,9 +1,9 @@
-import { useClerk, useUser } from "@clerk/tanstack-react-start";
 import { convexQuery, useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { useNavigate } from "@tanstack/react-router";
 import { LogOut, User } from "lucide-react";
+import { useClerk, useUser } from "@/lib/auth";
 import { AgentConnections } from "../agent-connections";
 import { Avatar, AvatarFallback, AvatarImage } from "../ui/avatar";
 import { Button } from "../ui/button";

apps/web/src/components/chat/share-dialog.tsx

@@ -1,4 +1,3 @@
-import { useUser } from "@clerk/tanstack-react-start";
 import { convexQuery, useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
@@ -15,6 +14,7 @@ import {
 } from "lucide-react";
 import { useEffect, useState } from "react";
 import toast from "react-hot-toast";
+import { useUser } from "@/lib/auth";
 import {
 	buildShareUrl,
 	copyToClipboard,

apps/web/src/components/command-palette/commands/global-commands.tsx

@@ -1,4 +1,3 @@
-import { useAuth, useClerk } from "@clerk/tanstack-react-start";
 import { convexQuery } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import { useQuery } from "@tanstack/react-query";
@@ -14,6 +13,7 @@ import {
 	SlidersHorizontal,
 } from "lucide-react";
 import { useMemo } from "react";
+import { useAuth, useClerk } from "@/lib/auth";
 import { useRegisterCommands } from "../../../hooks/use-register-commands";
 import type { Command } from "../../../lib/command-palette/types";
 

apps/web/src/components/harness-creation-assistant.tsx

@@ -1,4 +1,3 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { convexQuery, useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import { useMutation, useQuery } from "@tanstack/react-query";
@@ -15,6 +14,7 @@ import {
 } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 import { PRESET_MCPS, presetIdsToServerEntries } from "../lib/mcp";
 import { MODELS } from "../lib/models";

apps/web/src/components/mcp-oauth-connect-row.tsx

@@ -1,8 +1,8 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { Server, Shield } from "lucide-react";
 import { motion } from "motion/react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 import type { McpServerEntry } from "../lib/mcp";
 import { RoseCurveSpinner } from "./rose-curve-spinner";

apps/web/src/components/mcp-server-status.test.ts

@@ -3,7 +3,12 @@ import { describe, expect, it, vi } from "vitest";
 // The module pulls in Clerk + convex query hooks at import time; mock the
 // heavier deps so the pure helper can be imported in isolation.
 vi.mock("@clerk/tanstack-react-start", () => ({
+	// The `@/lib/auth` wrapper re-exports all of these from Clerk, so the mock
+	// must provide each one even though the component only uses useAuth.
 	useAuth: () => ({ getToken: async () => null }),
+	useUser: () => ({ isLoaded: true, isSignedIn: true, user: null }),
+	useClerk: () => ({ signOut: async () => {} }),
+	useReverification: <T>(fn: T) => fn,
 }));
 vi.mock("@convex-dev/react-query", () => ({
 	convexQuery: () => ({}),

apps/web/src/components/mcp-server-status.tsx

@@ -1,4 +1,3 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { convexQuery, useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
@@ -17,6 +16,7 @@ import {
 import { AnimatePresence, motion } from "motion/react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 import {
 	fetchCommandsFromApi,

apps/web/src/components/princeton-connect-row.tsx

@@ -2,11 +2,11 @@ import {
 	isClerkRuntimeError,
 	isReverificationCancelledError,
 } from "@clerk/clerk-react/errors";
-import { useReverification, useUser } from "@clerk/tanstack-react-start";
 import { GraduationCap, Mail } from "lucide-react";
 import { motion } from "motion/react";
 import { useCallback, useState } from "react";
 import toast from "react-hot-toast";
+import { useReverification, useUser } from "@/lib/auth";
 import type { McpServerEntry } from "../lib/mcp";
 import { getPrincetonNetid } from "../lib/mcp";
 import { RoseCurveSpinner } from "./rose-curve-spinner";

apps/web/src/env.ts

@@ -18,6 +18,10 @@ export const env = createEnv({
 		VITE_CONVEX_URL: z.string().url(),
 		VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1),
 		VITE_FASTAPI_URL: z.string().url().optional(),
+		// LOCAL DEVELOPMENT ONLY: "true" bypasses Clerk entirely and signs you in
+		// as a fixed dev user. Pair with ENABLE_DEV_AUTH on the Convex deployment
+		// and the FastAPI gateway. Never set in production.
+		VITE_ENABLE_DEV_AUTH: z.enum(["true", "false"]).optional(),
 	},
 
 	/**

apps/web/src/hooks/use-mcp-health-check.ts

@@ -1,6 +1,6 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { useAuth } from "@/lib/auth";
 import type { HealthStatus } from "../components/mcp-server-status";
 import { env } from "../env";
 import type { McpAuthType } from "../lib/mcp";

apps/web/src/hooks/use-rewind.ts

@@ -1,10 +1,10 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
 import { useMutation } from "@tanstack/react-query";
 import { useCallback } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import { useChatStreamContext } from "../lib/chat-stream-context";
 import { resetAgentSessionForRewind } from "../lib/rewind";
 

apps/web/src/hooks/use-workspace-credentials.ts

@@ -1,8 +1,8 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { convexQuery, useConvexMutation } from "@convex-dev/react-query";
 import { api } from "@harness/convex-backend/convex/_generated/api";
 import type { Id } from "@harness/convex-backend/convex/_generated/dataModel";
 import { useMutation, useQuery } from "@tanstack/react-query";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 
 const FASTAPI_URL = env.VITE_FASTAPI_URL ?? "http://localhost:8000";

apps/web/src/lib/auth.ts

@@ -0,0 +1,63 @@
+import {
+	useAuth as clerkUseAuth,
+	useClerk as clerkUseClerk,
+	useReverification as clerkUseReverification,
+	useUser as clerkUseUser,
+} from "@clerk/tanstack-react-start";
+import { env } from "../env";
+
+/**
+ * Single switch for the loginless local-dev mode. When `VITE_ENABLE_DEV_AUTH` is
+ * "true", the app skips Clerk entirely and runs as a fixed dev user — pair it
+ * with `ENABLE_DEV_AUTH` on the Convex deployment and the FastAPI gateway.
+ *
+ * Off by default, and `DEV_AUTH` is a build-time constant, so the exported hooks
+ * below resolve to the REAL Clerk hooks in every normal build — this module is a
+ * pure pass-through unless a developer explicitly opts in. Import the auth hooks
+ * from here (`@/lib/auth`) instead of `@clerk/tanstack-react-start` so the
+ * bypass reaches every call site.
+ */
+export const DEV_AUTH = env.VITE_ENABLE_DEV_AUTH === "true";
+export const DEV_USER_ID = "dev-user";
+
+// Dev stubs — shapes mirror the subset of each Clerk hook's return the app reads.
+const devUseAuth = (() => ({
+	isLoaded: true,
+	isSignedIn: true,
+	userId: DEV_USER_ID,
+	sessionId: "dev-session",
+	orgId: null,
+	orgRole: null,
+	getToken: async () => "dev-auth",
+	signOut: async () => {},
+})) as unknown as typeof clerkUseAuth;
+
+const devUseUser = (() => ({
+	isLoaded: true,
+	isSignedIn: true,
+	user: {
+		id: DEV_USER_ID,
+		fullName: "Dev User",
+		firstName: "Dev",
+		lastName: "User",
+		primaryEmailAddress: { emailAddress: "dev@localhost" },
+		imageUrl: "",
+	},
+})) as unknown as typeof clerkUseUser;
+
+const devUseClerk = (() => ({
+	signOut: async () => {},
+	openSignIn: () => {},
+	openUserProfile: () => {},
+})) as unknown as typeof clerkUseClerk;
+
+// useReverification wraps an action that may need step-up auth; in dev, pass through.
+const devUseReverification = (<T>(fn: T) =>
+	fn) as unknown as typeof clerkUseReverification;
+
+export const useAuth = DEV_AUTH ? devUseAuth : clerkUseAuth;
+export const useUser = DEV_AUTH ? devUseUser : clerkUseUser;
+export const useClerk = DEV_AUTH ? devUseClerk : clerkUseClerk;
+export const useReverification = DEV_AUTH
+	? devUseReverification
+	: clerkUseReverification;

apps/web/src/lib/chat-stream-context.tsx

@@ -1,4 +1,3 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useQueryClient } from "@tanstack/react-query";
 import {
 	createContext,
@@ -12,6 +11,7 @@ import {
 	useState,
 } from "react";
 import toast from "react-hot-toast";
+import { useAuth } from "@/lib/auth";
 import {
 	type AgentPermissionRequest,
 	type AgentQuestionAction,

apps/web/src/lib/use-agent-catalog.ts

@@ -1,5 +1,5 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 import type { AgentMode } from "./agent-mode";
 

apps/web/src/lib/use-agent-session-config.ts

@@ -1,6 +1,6 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useMemo } from "react";
+import { useAuth } from "@/lib/auth";
 import {
 	type AgentCommand,
 	type AgentConfigOption,

apps/web/src/lib/use-chat-stream.ts

@@ -1,5 +1,5 @@
-import { useAuth, useUser } from "@clerk/tanstack-react-start";
 import { useCallback, useRef, useState } from "react";
+import { useAuth, useUser } from "@/lib/auth";
 import { env } from "../env";
 import {
 	type AgentMode,

apps/web/src/lib/use-follow-stream.ts

@@ -1,5 +1,5 @@
-import { useAuth } from "@clerk/tanstack-react-start";
 import { useCallback, useEffect, useState } from "react";
+import { useAuth } from "@/lib/auth";
 import { env } from "../env";
 import { agentStatusLabel } from "./agent-mode";
 import type { ConvoStreamState, StreamPart } from "./use-chat-stream";