feat: add multi-project support (#110)

* feat: Implement project management store with project path validation and synchronization

- Added `useProjectsStore` for managing projects, including adding, removing, renaming, and validating project paths.
- Implemented persistence for projects and active project ID using safe storage.
- Introduced synchronization from desktop settings to keep project data consistent.
- Enhanced session store to manage sessions by directory and added new methods for session management.
- Updated todo store to fetch session todos based on the directory context.
- Refactored server code to validate and resolve project directories for various API endpoints.
- Added project entry validation and sanitization to ensure data integrity.

* feat(settings): migrate legacy project settings and update settings loading logic

* feat: enhance project management with directory-aware settings and improved agent/command source handling

* feat: enhance session and project management with directory-aware settings and improved configuration refresh logic

* feat: enhance project management with worktree manager integration and project directory resolution

* feat: enhance agent groups store with project directory resolution and loading logic

* feat: add heartbeat management and global wrapping for SSE blocks in agent and chat providers

* feat: refactor command and project handling in useCommandsStore

- Replaced useDirectoryStore with useProjectsStore to manage project paths.
- Introduced getRequestDirectory function to determine the active project directory.
- Updated command fetching to respect project-level scoping.
- Enhanced error handling and logging for command configuration fetching.
- Improved command configuration saving and updating to utilize project directory context.

feat: enhance project path normalization in useProjectsStore

- Added resolveTildePath function to expand paths starting with ~.
- Updated normalizeProjectPath to utilize home directory for path expansion.

fix: update permission handling in useSessionStore

- Changed Permission type to PermissionRequest for clarity.
- Updated respondToPermission method to use requestId instead of permissionId.

refactor: improve permission utilities

- Introduced types for PermissionAction and PermissionRule.
- Enhanced getAgentDefinition and resolveConfigStore functions for better type safety.
- Added resolvePermissionAction to streamline permission resolution logic.

feat: add agent configuration retrieval endpoint

- Implemented new API endpoint to fetch agent configuration based on project directory.
- Enhanced getAgentPermissionSource to prioritize project-level permissions.

chore: update SDK version in package.json files

- Bumped @opencode-ai/sdk version to ^1.1.1 across all relevant package.json files.

refactor: streamline bridge message handling

- Updated handleBridgeMessage to accept directory parameter for agent and command requests.
- Improved local API request handling to extract directory from query parameters and headers.

feat: enhance project configuration management

- Added functions to retrieve and merge project configuration paths.
- Improved handling of existing project configuration files for agents and commands.

* feat: enhance VSCode integration and session management

- Added support for a sticky sidebar header background in light and dark themes.
- Introduced functions to read VSCode workspace directory and check if running in VSCode.
- Implemented detailed logging for session loading and creation processes.
- Enhanced session filtering based on directory structure and canonical paths.
- Added a new method to reorder projects and prevent modifications in VSCode workspace.
- Improved error handling and logging for app initialization and markdown file parsing.
- Updated API checks and health checks to ensure readiness before proceeding.
- Refactored code for better readability and maintainability across various modules.

* feat: improve agent and branch selection logic, enhance session management, and update multi-run creation response

* feat: add worktree management actions in agent group detail and sidebar, including delete and keep only options

* fix(ui): share IME guard and cover multi-run

* fix(session): reduce maximum visible sessions in group from 7 to 5

packages/ui/src/components/session/DirectoryExplorerDialog.tsx

@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { DirectoryTree } from './DirectoryTree';
 import { useDirectoryStore } from '@/stores/useDirectoryStore';
+import { useProjectsStore } from '@/stores/useProjectsStore';
 import { useFileSystemAccess } from '@/hooks/useFileSystemAccess';
 import { cn, formatPathForDisplay } from '@/lib/utils';
 import { toast } from 'sonner';
@@ -33,7 +34,8 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   open,
   onOpenChange,
 }) => {
-  const { currentDirectory, homeDirectory, setDirectory, isHomeReady } = useDirectoryStore();
+  const { currentDirectory, homeDirectory, isHomeReady } = useDirectoryStore();
+  const { addProject, getActiveProject } = useProjectsStore();
   const [pendingPath, setPendingPath] = React.useState<string | null>(null);
   const [pathInputValue, setPathInputValue] = React.useState('');
   const [hasUserSelection, setHasUserSelection] = React.useState(false);
@@ -67,12 +69,13 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
     if (open) {
       setHasUserSelection(false);
       setIsConfirming(false);
-      // Initialize with current directory
-      const initialPath = currentDirectory || homeDirectory || '';
+      // Initialize with active project or current directory
+      const activeProject = getActiveProject();
+      const initialPath = activeProject?.path || currentDirectory || homeDirectory || '';
       setPendingPath(initialPath);
       setPathInputValue(formatPath(initialPath));
     }
-  }, [open, currentDirectory, homeDirectory, formatPath]);
+  }, [open, currentDirectory, homeDirectory, formatPath, getActiveProject]);
 
   // Set initial pending path to home when ready (only if not yet selected)
   React.useEffect(() => {
@@ -104,13 +107,10 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
     if (!targetPath || isConfirming) {
       return;
     }
-    if (targetPath === currentDirectory) {
-      handleClose();
-      return;
-    }
     setIsConfirming(true);
     try {
       let resolvedPath = targetPath;
+      let projectId: string | undefined;
 
       if (isDesktop) {
         const accessResult = await requestAccess(targetPath);
@@ -121,6 +121,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
           return;
         }
         resolvedPath = accessResult.path ?? targetPath;
+        projectId = accessResult.projectId;
 
         const startResult = await startAccessing(resolvedPath);
         if (!startResult.success) {
@@ -131,7 +132,14 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
         }
       }
 
-      setDirectory(resolvedPath);
+      const added = addProject(resolvedPath, { id: projectId });
+      if (!added) {
+        toast.error('Failed to add project', {
+          description: 'Please select a valid directory path.',
+        });
+        return;
+      }
+
       handleClose();
     } catch (error) {
       toast.error('Failed to select directory', {
@@ -141,11 +149,10 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
       setIsConfirming(false);
     }
   }, [
-    currentDirectory,
+    addProject,
     handleClose,
     isDesktop,
     requestAccess,
-    setDirectory,
     startAccessing,
     isConfirming,
   ]);
@@ -200,9 +207,9 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
 
   const dialogHeader = (
     <DialogHeader className="flex-shrink-0 px-4 pb-2 pt-[calc(var(--oc-safe-area-top,0px)+0.5rem)] sm:px-0 sm:pb-3 sm:pt-0">
-      <DialogTitle>Select project directory</DialogTitle>
+      <DialogTitle>Add project directory</DialogTitle>
       <DialogDescription className="hidden sm:block">
-        Choose the working directory for sessions and OpenCode operations.
+        Choose a folder to add as a project.
       </DialogDescription>
     </DialogHeader>
   );
@@ -304,7 +311,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
         disabled={isConfirming || !hasUserSelection || (!pendingPath && !pathInputValue.trim())}
         className="flex-1 sm:flex-none sm:w-auto sm:min-w-[140px]"
       >
-        {isConfirming ? 'Applying...' : 'Open Directory'}
+        {isConfirming ? 'Adding...' : 'Add Project'}
       </Button>
     </>
   );
@@ -314,7 +321,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
       <MobileOverlayPanel
         open={open}
         onClose={() => onOpenChange(false)}
-        title="Select project directory"
+        title="Add project directory"
         className="max-w-full"
         contentMaxHeightClassName="max-h-[min(70vh,520px)] h-[min(70vh,520px)]"
         footer={<div className="flex flex-row gap-2">{renderActionButtons()}</div>}

packages/ui/src/components/session/SessionDialogs.tsx

@@ -38,6 +38,9 @@ import {
 import { checkIsGitRepository, ensureOpenChamberIgnored, getGitBranches } from '@/lib/gitApi';
 import { useSessionStore } from '@/stores/useSessionStore';
 import { useDirectoryStore } from '@/stores/useDirectoryStore';
+import { useProjectsStore } from '@/stores/useProjectsStore';
+import { useFileSystemAccess } from '@/hooks/useFileSystemAccess';
+import { isDesktopRuntime } from '@/lib/desktop';
 import { useConfigStore } from '@/stores/useConfigStore';
 import { useUIStore } from '@/stores/useUIStore';
 import { useDeviceInfo } from '@/lib/device';
@@ -122,6 +125,7 @@ export const SessionDialogs: React.FC = () => {
     const [isCheckingGitRepository, setIsCheckingGitRepository] = React.useState(false);
     const [isGitRepository, setIsGitRepository] = React.useState<boolean | null>(null);
     const [isCreatingWorktree, setIsCreatingWorktree] = React.useState(false);
+    const [worktreeManagerProjectId, setWorktreeManagerProjectId] = React.useState<string | null>(null);
     const ensuredIgnoreDirectories = React.useRef<Set<string>>(new Set());
     const [deleteDialog, setDeleteDialog] = React.useState<DeleteDialogState | null>(null);
     const [deleteDialogSummaries, setDeleteDialogSummaries] = React.useState<Array<{ session: Session; metadata: WorktreeMetadata }>>([]);
@@ -140,13 +144,22 @@ export const SessionDialogs: React.FC = () => {
         getWorktreeMetadata,
         isLoading,
     } = useSessionStore();
-    const { currentDirectory, homeDirectory, hasPersistedDirectory, isHomeReady } = useDirectoryStore();
+    const { currentDirectory, homeDirectory, isHomeReady, setDirectory } = useDirectoryStore();
+    const { projects, addProject, activeProjectId } = useProjectsStore();
+    const { requestAccess, startAccessing } = useFileSystemAccess();
     const { agents } = useConfigStore();
     const { isSessionCreateDialogOpen, setSessionCreateDialogOpen } = useUIStore();
     const { isMobile, isTablet, hasTouchInput } = useDeviceInfo();
     const useMobileOverlay = isMobile || isTablet || hasTouchInput;
 
-    const projectDirectory = React.useMemo(() => normalizeProjectDirectory(currentDirectory), [currentDirectory]);
+    const projectDirectory = React.useMemo(() => {
+        const targetProjectId = worktreeManagerProjectId ?? activeProjectId;
+        const targetProject = targetProjectId
+            ? projects.find((project) => project.id === targetProjectId) ?? null
+            : null;
+        const targetPath = targetProject?.path ?? currentDirectory;
+        return normalizeProjectDirectory(targetPath);
+    }, [activeProjectId, currentDirectory, projects, worktreeManagerProjectId]);
     const sanitizedNewBranchName = React.useMemo(() => sanitizeBranchNameInput(branchName), [branchName]);
     const worktreeTargetBranch = React.useMemo(
         () => (worktreeCreateMode === 'existing' ? existingWorktreeBranch.trim() : sanitizedNewBranchName),
@@ -213,15 +226,75 @@ export const SessionDialogs: React.FC = () => {
         loadSessions();
     }, [loadSessions, currentDirectory]);
 
+    const projectsKey = React.useMemo(
+        () => projects.map((project) => `${project.id}:${project.path}`).join('|'),
+        [projects],
+    );
+    const lastProjectsKeyRef = React.useRef(projectsKey);
+
     React.useEffect(() => {
-        if (!hasShownInitialDirectoryPrompt && isHomeReady && !hasPersistedDirectory) {
-            setIsDirectoryDialogOpen(true);
-            setHasShownInitialDirectoryPrompt(true);
+        if (projectsKey === lastProjectsKeyRef.current) {
+            return;
         }
-    }, [hasPersistedDirectory, hasShownInitialDirectoryPrompt, isHomeReady]);
+
+        lastProjectsKeyRef.current = projectsKey;
+        loadSessions();
+    }, [loadSessions, projectsKey]);
+
+    React.useEffect(() => {
+        if (hasShownInitialDirectoryPrompt || !isHomeReady || projects.length > 0) {
+            return;
+        }
+
+        setHasShownInitialDirectoryPrompt(true);
+
+        if (isDesktopRuntime()) {
+            requestAccess('')
+                .then(async (result) => {
+                    if (!result.success || !result.path) {
+                        if (result.error && result.error !== 'Directory selection cancelled') {
+                            toast.error('Failed to select directory', {
+                                description: result.error,
+                            });
+                        }
+                        return;
+                    }
+
+                    const accessResult = await startAccessing(result.path);
+                    if (!accessResult.success) {
+                        toast.error('Failed to open directory', {
+                            description: accessResult.error || 'Desktop could not grant file access.',
+                        });
+                        return;
+                    }
+
+                    const added = addProject(result.path, { id: result.projectId });
+                    if (!added) {
+                        toast.error('Failed to add project', {
+                            description: 'Please select a valid directory path.',
+                        });
+                    }
+                })
+                .catch((error) => {
+                    console.error('Desktop: Error selecting directory:', error);
+                    toast.error('Failed to select directory');
+                });
+            return;
+        }
+
+        setIsDirectoryDialogOpen(true);
+    }, [
+        addProject,
+        hasShownInitialDirectoryPrompt,
+        isHomeReady,
+        projects.length,
+        requestAccess,
+        startAccessing,
+    ]);
 
     React.useEffect(() => {
         if (!isSessionCreateDialogOpen) {
+            setWorktreeManagerProjectId(null);
             setWorktreeCreateMode('new');
             setBranchName('');
             setExistingWorktreeBranch('');
@@ -372,7 +445,9 @@ export const SessionDialogs: React.FC = () => {
     }, []);
 
     React.useEffect(() => {
-        return sessionEvents.onCreateRequest(() => {
+        return sessionEvents.onCreateRequest((request) => {
+            const projectId = typeof request?.projectId === 'string' && request.projectId.trim() ? request.projectId : null;
+            setWorktreeManagerProjectId(projectId);
             setWorktreeCreateMode('new');
             setBranchName('');
             setExistingWorktreeBranch('');
@@ -555,6 +630,9 @@ export const SessionDialogs: React.FC = () => {
             setSessionDirectory(session.id, metadata.path);
             setWorktreeMetadata(session.id, createdMetadata);
 
+            // Ensure directory-scoped caches and session lists include the new worktree.
+            setDirectory(metadata.path, { showOverlay: false });
+
             await refreshWorktrees();
             setBranchName('');
             setExistingWorktreeBranch('');