feat(setup): implement setup wizard for CLI tools configuration

- Added a new SetupView component to guide users through the installation and authentication of Claude and Codex CLIs.
- Integrated IPC handlers for checking CLI status, installing, and authenticating both CLIs.
- Enhanced the app store to manage setup state, including first run detection and progress tracking.
- Updated the main application view to redirect to the setup wizard on first run.
- Improved user experience by providing clear instructions and feedback during the setup process.

These changes streamline the initial configuration of CLI tools, ensuring users can easily set up their development environment.

app/src/app/page.tsx

@@ -11,11 +11,14 @@ import { AgentToolsView } from "@/components/views/agent-tools-view";
 import { InterviewView } from "@/components/views/interview-view";
 import { ContextView } from "@/components/views/context-view";
 import { ProfilesView } from "@/components/views/profiles-view";
+import { SetupView } from "@/components/views/setup-view";
 import { useAppStore } from "@/store/app-store";
+import { useSetupStore } from "@/store/setup-store";
 import { getElectronAPI, isElectron } from "@/lib/electron";
 
 export default function Home() {
-  const { currentView, setIpcConnected, theme } = useAppStore();
+  const { currentView, setCurrentView, setIpcConnected, theme } = useAppStore();
+  const { isFirstRun, setupComplete } = useSetupStore();
   const [isMounted, setIsMounted] = useState(false);
 
   // Prevent hydration issues
@@ -23,6 +26,24 @@ export default function Home() {
     setIsMounted(true);
   }, []);
 
+  // Check if this is first run and redirect to setup if needed
+  useEffect(() => {
+    console.log("[Setup Flow] Checking setup state:", {
+      isMounted,
+      isFirstRun,
+      setupComplete,
+      currentView,
+      shouldShowSetup: isMounted && isFirstRun && !setupComplete,
+    });
+
+    if (isMounted && isFirstRun && !setupComplete) {
+      console.log("[Setup Flow] Redirecting to setup wizard (first run, not complete)");
+      setCurrentView("setup");
+    } else if (isMounted && setupComplete) {
+      console.log("[Setup Flow] Setup already complete, showing normal view");
+    }
+  }, [isMounted, isFirstRun, setupComplete, setCurrentView, currentView]);
+
   // Test IPC connection on mount
   useEffect(() => {
     const testConnection = async () => {
@@ -96,6 +117,8 @@ export default function Home() {
     switch (currentView) {
       case "welcome":
         return <WelcomeView />;
+      case "setup":
+        return <SetupView />;
       case "board":
         return <BoardView />;
       case "spec":
@@ -117,6 +140,21 @@ export default function Home() {
     }
   };
 
+  // Setup view is full-screen without sidebar
+  if (currentView === "setup") {
+    return (
+      <main className="h-screen overflow-hidden" data-testid="app-container">
+        <SetupView />
+        {/* Environment indicator */}
+        {isMounted && !isElectron() && (
+          <div className="fixed bottom-4 right-4 px-3 py-1.5 bg-yellow-500/10 text-yellow-500 text-xs rounded-full border border-yellow-500/20 pointer-events-none">
+            Web Mode (Mock IPC)
+          </div>
+        )}
+      </main>
+    );
+  }
+
   return (
     <main className="flex h-screen overflow-hidden" data-testid="app-container">
       <Sidebar />

app/src/lib/electron.ts

@@ -172,6 +172,54 @@ export interface ElectronAPI {
   git?: GitAPI;
   suggestions?: SuggestionsAPI;
   specRegeneration?: SpecRegenerationAPI;
+  setup?: {
+    getClaudeStatus: () => Promise<{
+      success: boolean;
+      status?: string;
+      method?: string;
+      version?: string;
+      path?: string;
+      auth?: {
+        authenticated: boolean;
+        method: string;
+        hasCredentialsFile: boolean;
+        hasToken: boolean;
+      };
+      error?: string;
+    }>;
+    getCodexStatus: () => Promise<{
+      success: boolean;
+      status?: string;
+      method?: string;
+      version?: string;
+      path?: string;
+      auth?: {
+        authenticated: boolean;
+        method: string;
+        hasAuthFile: boolean;
+        hasEnvKey: boolean;
+      };
+      error?: string;
+    }>;
+    installClaude: () => Promise<{ success: boolean; message?: string; error?: string }>;
+    installCodex: () => Promise<{ success: boolean; message?: string; error?: string }>;
+    authClaude: () => Promise<{ success: boolean; requiresManualAuth?: boolean; command?: string; error?: string }>;
+    authCodex: (apiKey?: string) => Promise<{ success: boolean; requiresManualAuth?: boolean; command?: string; error?: string }>;
+    storeApiKey: (provider: string, apiKey: string) => Promise<{ success: boolean; error?: string }>;
+    getApiKeys: () => Promise<{ success: boolean; hasAnthropicKey: boolean; hasOpenAIKey: boolean; hasGoogleKey: boolean }>;
+    configureCodexMcp: (projectPath: string) => Promise<{ success: boolean; configPath?: string; error?: string }>;
+    getPlatform: () => Promise<{
+      success: boolean;
+      platform: string;
+      arch: string;
+      homeDir: string;
+      isWindows: boolean;
+      isMac: boolean;
+      isLinux: boolean;
+    }>;
+    onInstallProgress?: (callback: (progress: any) => void) => () => void;
+    onAuthProgress?: (callback: (progress: any) => void) => () => void;
+  };
 }
 
 // Note: Window interface is declared in @/types/electron.d.ts
@@ -461,6 +509,9 @@ export const getElectronAPI = (): ElectronAPI => {
       error: "OpenAI connection test is only available in the Electron app.",
     }),
 
+    // Mock Setup API
+    setup: createMockSetupAPI(),
+
     // Mock Auto Mode API
     autoMode: createMockAutoModeAPI(),
 
@@ -478,6 +529,175 @@ export const getElectronAPI = (): ElectronAPI => {
   };
 };
 
+// Setup API interface
+interface SetupAPI {
+  getClaudeStatus: () => Promise<{
+    success: boolean;
+    status?: string;
+    method?: string;
+    version?: string;
+    path?: string;
+    auth?: {
+      authenticated: boolean;
+      method: string;
+      hasCredentialsFile: boolean;
+      hasToken: boolean;
+    };
+    error?: string;
+  }>;
+  getCodexStatus: () => Promise<{
+    success: boolean;
+    status?: string;
+    method?: string;
+    version?: string;
+    path?: string;
+    auth?: {
+      authenticated: boolean;
+      method: string;
+      hasAuthFile: boolean;
+      hasEnvKey: boolean;
+    };
+    error?: string;
+  }>;
+  installClaude: () => Promise<{ success: boolean; message?: string; error?: string }>;
+  installCodex: () => Promise<{ success: boolean; message?: string; error?: string }>;
+  authClaude: () => Promise<{ success: boolean; requiresManualAuth?: boolean; command?: string; error?: string }>;
+  authCodex: (apiKey?: string) => Promise<{ success: boolean; requiresManualAuth?: boolean; command?: string; error?: string }>;
+  storeApiKey: (provider: string, apiKey: string) => Promise<{ success: boolean; error?: string }>;
+  getApiKeys: () => Promise<{ success: boolean; hasAnthropicKey: boolean; hasOpenAIKey: boolean; hasGoogleKey: boolean }>;
+  configureCodexMcp: (projectPath: string) => Promise<{ success: boolean; configPath?: string; error?: string }>;
+  getPlatform: () => Promise<{
+    success: boolean;
+    platform: string;
+    arch: string;
+    homeDir: string;
+    isWindows: boolean;
+    isMac: boolean;
+    isLinux: boolean;
+  }>;
+  onInstallProgress?: (callback: (progress: any) => void) => () => void;
+  onAuthProgress?: (callback: (progress: any) => void) => () => void;
+}
+
+// Mock Setup API implementation
+function createMockSetupAPI(): SetupAPI {
+  return {
+    getClaudeStatus: async () => {
+      console.log("[Mock] Getting Claude status");
+      return {
+        success: true,
+        status: "not_installed",
+        auth: {
+          authenticated: false,
+          method: "none",
+          hasCredentialsFile: false,
+          hasToken: false,
+        },
+      };
+    },
+
+    getCodexStatus: async () => {
+      console.log("[Mock] Getting Codex status");
+      return {
+        success: true,
+        status: "not_installed",
+        auth: {
+          authenticated: false,
+          method: "none",
+          hasAuthFile: false,
+          hasEnvKey: false,
+        },
+      };
+    },
+
+    installClaude: async () => {
+      console.log("[Mock] Installing Claude CLI");
+      // Simulate installation delay
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      return {
+        success: false,
+        error: "CLI installation is only available in the Electron app. Please run the command manually.",
+      };
+    },
+
+    installCodex: async () => {
+      console.log("[Mock] Installing Codex CLI");
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      return {
+        success: false,
+        error: "CLI installation is only available in the Electron app. Please run the command manually.",
+      };
+    },
+
+    authClaude: async () => {
+      console.log("[Mock] Auth Claude CLI");
+      return {
+        success: true,
+        requiresManualAuth: true,
+        command: "claude login",
+      };
+    },
+
+    authCodex: async (apiKey?: string) => {
+      console.log("[Mock] Auth Codex CLI", { hasApiKey: !!apiKey });
+      if (apiKey) {
+        return { success: true };
+      }
+      return {
+        success: true,
+        requiresManualAuth: true,
+        command: "codex auth login",
+      };
+    },
+
+    storeApiKey: async (provider: string, apiKey: string) => {
+      console.log("[Mock] Storing API key for:", provider);
+      // In mock mode, we just pretend to store it (it's already in the app store)
+      return { success: true };
+    },
+
+    getApiKeys: async () => {
+      console.log("[Mock] Getting API keys");
+      return {
+        success: true,
+        hasAnthropicKey: false,
+        hasOpenAIKey: false,
+        hasGoogleKey: false,
+      };
+    },
+
+    configureCodexMcp: async (projectPath: string) => {
+      console.log("[Mock] Configuring Codex MCP for:", projectPath);
+      return {
+        success: true,
+        configPath: `${projectPath}/.codex/config.toml`,
+      };
+    },
+
+    getPlatform: async () => {
+      return {
+        success: true,
+        platform: "darwin",
+        arch: "arm64",
+        homeDir: "/Users/mock",
+        isWindows: false,
+        isMac: true,
+        isLinux: false,
+      };
+    },
+
+    onInstallProgress: (callback) => {
+      // Mock progress events
+      return () => {};
+    },
+
+    onAuthProgress: (callback) => {
+      // Mock auth events
+      return () => {};
+    },
+  };
+}
+
 // Mock Worktree API implementation
 function createMockWorktreeAPI(): WorktreeAPI {
   return {

app/src/store/app-store.ts

@@ -4,6 +4,7 @@ import type { Project, TrashedProject } from "@/lib/electron";
 
 export type ViewMode =
   | "welcome"
+  | "setup"
   | "spec"
   | "board"
   | "agent"

app/src/store/setup-store.ts

@@ -0,0 +1,182 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+// CLI Installation Status
+export interface CliStatus {
+  installed: boolean;
+  path: string | null;
+  version: string | null;
+  method: string;
+  error?: string;
+}
+
+// Claude Auth Status
+export interface ClaudeAuthStatus {
+  authenticated: boolean;
+  method: "oauth" | "api_key" | "none";
+  hasCredentialsFile: boolean;
+  oauthTokenValid?: boolean;
+  apiKeyValid?: boolean;
+  error?: string;
+}
+
+// Codex Auth Status
+export interface CodexAuthStatus {
+  authenticated: boolean;
+  method: "api_key" | "env" | "none";
+  apiKeyValid?: boolean;
+  mcpConfigured?: boolean;
+  error?: string;
+}
+
+// Installation Progress
+export interface InstallProgress {
+  isInstalling: boolean;
+  currentStep: string;
+  progress: number; // 0-100
+  output: string[];
+  error?: string;
+}
+
+export type SetupStep =
+  | "welcome"
+  | "claude_detect"
+  | "claude_auth"
+  | "codex_detect"
+  | "codex_auth"
+  | "complete";
+
+export interface SetupState {
+  // Setup wizard state
+  isFirstRun: boolean;
+  setupComplete: boolean;
+  currentStep: SetupStep;
+
+  // Claude CLI state
+  claudeCliStatus: CliStatus | null;
+  claudeAuthStatus: ClaudeAuthStatus | null;
+  claudeInstallProgress: InstallProgress;
+
+  // Codex CLI state
+  codexCliStatus: CliStatus | null;
+  codexAuthStatus: CodexAuthStatus | null;
+  codexInstallProgress: InstallProgress;
+
+  // Setup preferences
+  skipClaudeSetup: boolean;
+  skipCodexSetup: boolean;
+}
+
+export interface SetupActions {
+  // Setup flow
+  setCurrentStep: (step: SetupStep) => void;
+  completeSetup: () => void;
+  resetSetup: () => void;
+  setIsFirstRun: (isFirstRun: boolean) => void;
+
+  // Claude CLI
+  setClaudeCliStatus: (status: CliStatus | null) => void;
+  setClaudeAuthStatus: (status: ClaudeAuthStatus | null) => void;
+  setClaudeInstallProgress: (progress: Partial<InstallProgress>) => void;
+  resetClaudeInstallProgress: () => void;
+
+  // Codex CLI
+  setCodexCliStatus: (status: CliStatus | null) => void;
+  setCodexAuthStatus: (status: CodexAuthStatus | null) => void;
+  setCodexInstallProgress: (progress: Partial<InstallProgress>) => void;
+  resetCodexInstallProgress: () => void;
+
+  // Preferences
+  setSkipClaudeSetup: (skip: boolean) => void;
+  setSkipCodexSetup: (skip: boolean) => void;
+}
+
+const initialInstallProgress: InstallProgress = {
+  isInstalling: false,
+  currentStep: "",
+  progress: 0,
+  output: [],
+};
+
+const initialState: SetupState = {
+  isFirstRun: true,
+  setupComplete: false,
+  currentStep: "welcome",
+
+  claudeCliStatus: null,
+  claudeAuthStatus: null,
+  claudeInstallProgress: { ...initialInstallProgress },
+
+  codexCliStatus: null,
+  codexAuthStatus: null,
+  codexInstallProgress: { ...initialInstallProgress },
+
+  skipClaudeSetup: false,
+  skipCodexSetup: false,
+};
+
+export const useSetupStore = create<SetupState & SetupActions>()(
+  persist(
+    (set, get) => ({
+      ...initialState,
+
+      // Setup flow
+      setCurrentStep: (step) => set({ currentStep: step }),
+
+      completeSetup: () => set({ setupComplete: true, currentStep: "complete" }),
+
+      resetSetup: () => set({
+        ...initialState,
+        isFirstRun: false, // Don't reset first run flag
+      }),
+
+      setIsFirstRun: (isFirstRun) => set({ isFirstRun }),
+
+      // Claude CLI
+      setClaudeCliStatus: (status) => set({ claudeCliStatus: status }),
+
+      setClaudeAuthStatus: (status) => set({ claudeAuthStatus: status }),
+
+      setClaudeInstallProgress: (progress) => set({
+        claudeInstallProgress: {
+          ...get().claudeInstallProgress,
+          ...progress,
+        },
+      }),
+
+      resetClaudeInstallProgress: () => set({
+        claudeInstallProgress: { ...initialInstallProgress },
+      }),
+
+      // Codex CLI
+      setCodexCliStatus: (status) => set({ codexCliStatus: status }),
+
+      setCodexAuthStatus: (status) => set({ codexAuthStatus: status }),
+
+      setCodexInstallProgress: (progress) => set({
+        codexInstallProgress: {
+          ...get().codexInstallProgress,
+          ...progress,
+        },
+      }),
+
+      resetCodexInstallProgress: () => set({
+        codexInstallProgress: { ...initialInstallProgress },
+      }),
+
+      // Preferences
+      setSkipClaudeSetup: (skip) => set({ skipClaudeSetup: skip }),
+
+      setSkipCodexSetup: (skip) => set({ skipCodexSetup: skip }),
+    }),
+    {
+      name: "automaker-setup",
+      partialize: (state) => ({
+        isFirstRun: state.isFirstRun,
+        setupComplete: state.setupComplete,
+        skipClaudeSetup: state.skipClaudeSetup,
+        skipCodexSetup: state.skipCodexSetup,
+      }),
+    }
+  )
+);