From 200332f4f5c4fd7257978c240116468f6420a201 Mon Sep 17 00:00:00 2001
From: Haileyesus <something@gmail.com>
Date: Fri, 20 Feb 2026 10:39:16 +0300
Subject: [PATCH] fix: make shell and standalone shell feature based components

- In addition, use one copy handler throughout the app.
---
 src/components/LoginModal.jsx                 |   2 +-
 src/components/NextTaskBanner.jsx             |   2 +-
 src/components/Shell.jsx                      | 692 ------------------
 src/components/StandaloneShell.jsx            | 105 ---
 src/components/TaskDetail.jsx                 |   3 +-
 src/components/TaskList.jsx                   |   2 +-
 src/components/TaskMasterSetupWizard.jsx      |   3 +-
 .../chat/tools/components/OneLineDisplay.tsx  |  49 +-
 .../chat/view/subcomponents/Markdown.tsx      |  40 +-
 .../markdown/MarkdownCodeBlock.tsx            |  11 +-
 .../main-content/view/MainContent.tsx         |   6 +-
 .../settings/hooks/useCredentialsSettings.ts  |   3 +-
 src/components/shell/constants/constants.ts   |  63 ++
 .../shell/hooks/useShellConnection.ts         | 215 ++++++
 src/components/shell/hooks/useShellRuntime.ts | 166 +++++
 .../shell/hooks/useShellTerminal.ts           | 233 ++++++
 src/components/shell/types/types.ts           |  73 ++
 src/components/shell/utils/auth.ts            |  24 +
 src/components/shell/utils/socket.ts          |  32 +
 src/components/shell/utils/terminalStyles.ts  |  29 +
 src/components/shell/view/Shell.tsx           | 162 ++++
 .../subcomponents/ShellConnectionOverlay.tsx  |  59 ++
 .../view/subcomponents/ShellEmptyState.tsx    |  25 +
 .../shell/view/subcomponents/ShellHeader.tsx  |  87 +++
 .../view/subcomponents/ShellMinimalView.tsx   | 113 +++
 .../view/modals/VersionUpgradeModal.tsx       |   7 +-
 .../standalone-shell/view/StandaloneShell.tsx |  74 ++
 .../StandaloneShellEmptyState.tsx             |  24 +
 .../subcomponents/StandaloneShellHeader.tsx   |  30 +
 src/utils/clipboard.ts                        |  50 ++
 30 files changed, 1478 insertions(+), 906 deletions(-)
 delete mode 100644 src/components/Shell.jsx
 delete mode 100644 src/components/StandaloneShell.jsx
 create mode 100644 src/components/shell/constants/constants.ts
 create mode 100644 src/components/shell/hooks/useShellConnection.ts
 create mode 100644 src/components/shell/hooks/useShellRuntime.ts
 create mode 100644 src/components/shell/hooks/useShellTerminal.ts
 create mode 100644 src/components/shell/types/types.ts
 create mode 100644 src/components/shell/utils/auth.ts
 create mode 100644 src/components/shell/utils/socket.ts
 create mode 100644 src/components/shell/utils/terminalStyles.ts
 create mode 100644 src/components/shell/view/Shell.tsx
 create mode 100644 src/components/shell/view/subcomponents/ShellConnectionOverlay.tsx
 create mode 100644 src/components/shell/view/subcomponents/ShellEmptyState.tsx
 create mode 100644 src/components/shell/view/subcomponents/ShellHeader.tsx
 create mode 100644 src/components/shell/view/subcomponents/ShellMinimalView.tsx
 create mode 100644 src/components/standalone-shell/view/StandaloneShell.tsx
 create mode 100644 src/components/standalone-shell/view/subcomponents/StandaloneShellEmptyState.tsx
 create mode 100644 src/components/standalone-shell/view/subcomponents/StandaloneShellHeader.tsx
 create mode 100644 src/utils/clipboard.ts

diff --git a/src/components/LoginModal.jsx b/src/components/LoginModal.jsx
index 5c3af51..f391c6d 100644
--- a/src/components/LoginModal.jsx
+++ b/src/components/LoginModal.jsx
@@ -1,5 +1,5 @@
 import { X } from 'lucide-react';
-import StandaloneShell from './StandaloneShell';
+import StandaloneShell from './standalone-shell/view/StandaloneShell';
 import { IS_PLATFORM } from '../constants/config';
 
 /**
diff --git a/src/components/NextTaskBanner.jsx b/src/components/NextTaskBanner.jsx
index 2a55cb8..49eb941 100644
--- a/src/components/NextTaskBanner.jsx
+++ b/src/components/NextTaskBanner.jsx
@@ -3,7 +3,7 @@ import { ArrowRight, List, Clock, Flag, CheckCircle, Circle, AlertCircle, Pause,
 import { cn } from '../lib/utils';
 import { useTaskMaster } from '../contexts/TaskMasterContext';
 import { api } from '../utils/api';
-import Shell from './Shell';
+import Shell from './shell/view/Shell';
 import TaskDetail from './TaskDetail';
 
 const NextTaskBanner = ({ onShowAllTasks, onStartTask, className = '' }) => {
diff --git a/src/components/Shell.jsx b/src/components/Shell.jsx
deleted file mode 100644
index 4e6dc3a..0000000
--- a/src/components/Shell.jsx
+++ /dev/null
@@ -1,692 +0,0 @@
-import React, { useEffect, useRef, useState, useCallback, useMemo } from 'react';
-import { Terminal } from '@xterm/xterm';
-import { FitAddon } from '@xterm/addon-fit';
-import { WebglAddon } from '@xterm/addon-webgl';
-import { WebLinksAddon } from '@xterm/addon-web-links';
-import '@xterm/xterm/css/xterm.css';
-import { useTranslation } from 'react-i18next';
-import { IS_PLATFORM } from '../constants/config';
-
-const xtermStyles = `
-  .xterm .xterm-screen {
-    outline: none !important;
-  }
-  .xterm:focus .xterm-screen {
-    outline: none !important;
-  }
-  .xterm-screen:focus {
-    outline: none !important;
-  }
-`;
-
-if (typeof document !== 'undefined') {
-  const styleSheet = document.createElement('style');
-  styleSheet.type = 'text/css';
-  styleSheet.innerText = xtermStyles;
-  document.head.appendChild(styleSheet);
-}
-
-function fallbackCopyToClipboard(text) {
-  if (!text || typeof document === 'undefined') return false;
-
-  const textarea = document.createElement('textarea');
-  textarea.value = text;
-  textarea.setAttribute('readonly', '');
-  textarea.style.position = 'fixed';
-  textarea.style.opacity = '0';
-  textarea.style.pointerEvents = 'none';
-  document.body.appendChild(textarea);
-  textarea.focus();
-  textarea.select();
-
-  let copied = false;
-  try {
-    copied = document.execCommand('copy');
-  } catch {
-    copied = false;
-  } finally {
-    document.body.removeChild(textarea);
-  }
-
-  return copied;
-}
-
-const CODEX_DEVICE_AUTH_URL = 'https://auth.openai.com/codex/device';
-
-function isCodexLoginCommand(command) {
-  return typeof command === 'string' && /\bcodex\s+login\b/i.test(command);
-}
-
-function Shell({ selectedProject, selectedSession, initialCommand, isPlainShell = false, onProcessComplete, minimal = false, autoConnect = false }) {
-  const { t } = useTranslation('chat');
-  const terminalRef = useRef(null);
-  const terminal = useRef(null);
-  const fitAddon = useRef(null);
-  const ws = useRef(null);
-  const [isConnected, setIsConnected] = useState(false);
-  const [isInitialized, setIsInitialized] = useState(false);
-  const [isRestarting, setIsRestarting] = useState(false);
-  const [lastSessionId, setLastSessionId] = useState(null);
-  const [isConnecting, setIsConnecting] = useState(false);
-  const [authUrl, setAuthUrl] = useState('');
-  const [authUrlCopyStatus, setAuthUrlCopyStatus] = useState('idle');
-  const [isAuthPanelHidden, setIsAuthPanelHidden] = useState(false);
-
-  const selectedProjectRef = useRef(selectedProject);
-  const selectedSessionRef = useRef(selectedSession);
-  const initialCommandRef = useRef(initialCommand);
-  const isPlainShellRef = useRef(isPlainShell);
-  const onProcessCompleteRef = useRef(onProcessComplete);
-  const authUrlRef = useRef('');
-
-  useEffect(() => {
-    selectedProjectRef.current = selectedProject;
-    selectedSessionRef.current = selectedSession;
-    initialCommandRef.current = initialCommand;
-    isPlainShellRef.current = isPlainShell;
-    onProcessCompleteRef.current = onProcessComplete;
-  });
-
-  const openAuthUrlInBrowser = useCallback((url = authUrlRef.current) => {
-    if (!url) return false;
-
-    const popup = window.open(url, '_blank', 'noopener,noreferrer');
-    if (popup) {
-      try {
-        popup.opener = null;
-      } catch {
-        // Ignore cross-origin restrictions when trying to null opener
-      }
-      return true;
-    }
-
-    return false;
-  }, []);
-
-  const copyAuthUrlToClipboard = useCallback(async (url = authUrlRef.current) => {
-    if (!url) return false;
-
-    let copied = false;
-    try {
-      if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
-        await navigator.clipboard.writeText(url);
-        copied = true;
-      }
-    } catch {
-      copied = false;
-    }
-
-    if (!copied) {
-      copied = fallbackCopyToClipboard(url);
-    }
-
-    return copied;
-  }, []);
-
-  const connectWebSocket = useCallback(async () => {
-    if (isConnecting || isConnected) return;
-
-    try {
-      let wsUrl;
-
-      if (IS_PLATFORM) {
-        const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-        wsUrl = `${protocol}//${window.location.host}/shell`;
-      } else {
-        const token = localStorage.getItem('auth-token');
-        if (!token) {
-          console.error('No authentication token found for Shell WebSocket connection');
-          return;
-        }
-
-        const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-        wsUrl = `${protocol}//${window.location.host}/shell?token=${encodeURIComponent(token)}`;
-      }
-
-      ws.current = new WebSocket(wsUrl);
-
-      ws.current.onopen = () => {
-        setIsConnected(true);
-        setIsConnecting(false);
-        authUrlRef.current = '';
-        setAuthUrl('');
-        setAuthUrlCopyStatus('idle');
-        setIsAuthPanelHidden(false);
-
-        setTimeout(() => {
-          if (fitAddon.current && terminal.current) {
-            fitAddon.current.fit();
-
-            ws.current.send(JSON.stringify({
-              type: 'init',
-              projectPath: selectedProjectRef.current.fullPath || selectedProjectRef.current.path,
-              sessionId: isPlainShellRef.current ? null : selectedSessionRef.current?.id,
-              hasSession: isPlainShellRef.current ? false : !!selectedSessionRef.current,
-              provider: isPlainShellRef.current ? 'plain-shell' : (selectedSessionRef.current?.__provider || 'claude'),
-              cols: terminal.current.cols,
-              rows: terminal.current.rows,
-              initialCommand: initialCommandRef.current,
-              isPlainShell: isPlainShellRef.current
-            }));
-          }
-        }, 100);
-      };
-
-      ws.current.onmessage = (event) => {
-        try {
-          const data = JSON.parse(event.data);
-
-          if (data.type === 'output') {
-            let output = data.data;
-
-            if (isPlainShellRef.current && onProcessCompleteRef.current) {
-              const cleanOutput = output.replace(/\x1b\[[0-9;]*m/g, '');
-              if (cleanOutput.includes('Process exited with code 0')) {
-                onProcessCompleteRef.current(0);
-              } else if (cleanOutput.match(/Process exited with code (\d+)/)) {
-                const exitCode = parseInt(cleanOutput.match(/Process exited with code (\d+)/)[1]);
-                if (exitCode !== 0) {
-                  onProcessCompleteRef.current(exitCode);
-                }
-              }
-            }
-
-            if (terminal.current) {
-              terminal.current.write(output);
-            }
-          } else if (data.type === 'auth_url' && data.url) {
-            authUrlRef.current = data.url;
-            setAuthUrl(data.url);
-            setAuthUrlCopyStatus('idle');
-            setIsAuthPanelHidden(false);
-          } else if (data.type === 'url_open') {
-            if (data.url) {
-              authUrlRef.current = data.url;
-              setAuthUrl(data.url);
-              setAuthUrlCopyStatus('idle');
-              setIsAuthPanelHidden(false);
-            }
-          }
-        } catch (error) {
-          console.error('[Shell] Error handling WebSocket message:', error, event.data);
-        }
-      };
-
-      ws.current.onclose = (event) => {
-        setIsConnected(false);
-        setIsConnecting(false);
-        setAuthUrlCopyStatus('idle');
-        setIsAuthPanelHidden(false);
-
-        if (terminal.current) {
-          terminal.current.clear();
-          terminal.current.write('\x1b[2J\x1b[H');
-        }
-      };
-
-      ws.current.onerror = (error) => {
-        setIsConnected(false);
-        setIsConnecting(false);
-      };
-    } catch (error) {
-      setIsConnected(false);
-      setIsConnecting(false);
-    }
-  }, [isConnecting, isConnected, openAuthUrlInBrowser]);
-
-  const connectToShell = useCallback(() => {
-    if (!isInitialized || isConnected || isConnecting) return;
-    setIsConnecting(true);
-    connectWebSocket();
-  }, [isInitialized, isConnected, isConnecting, connectWebSocket]);
-
-  const disconnectFromShell = useCallback(() => {
-    if (ws.current) {
-      ws.current.close();
-      ws.current = null;
-    }
-
-    if (terminal.current) {
-      terminal.current.clear();
-      terminal.current.write('\x1b[2J\x1b[H');
-    }
-
-    setIsConnected(false);
-    setIsConnecting(false);
-    authUrlRef.current = '';
-    setAuthUrl('');
-    setAuthUrlCopyStatus('idle');
-    setIsAuthPanelHidden(false);
-  }, []);
-
-  const sessionDisplayName = useMemo(() => {
-    if (!selectedSession) return null;
-    return selectedSession.__provider === 'cursor'
-      ? (selectedSession.name || 'Untitled Session')
-      : (selectedSession.summary || 'New Session');
-  }, [selectedSession]);
-
-  const sessionDisplayNameShort = useMemo(() => {
-    if (!sessionDisplayName) return null;
-    return sessionDisplayName.slice(0, 30);
-  }, [sessionDisplayName]);
-
-  const sessionDisplayNameLong = useMemo(() => {
-    if (!sessionDisplayName) return null;
-    return sessionDisplayName.slice(0, 50);
-  }, [sessionDisplayName]);
-
-  const restartShell = () => {
-    setIsRestarting(true);
-
-    if (ws.current) {
-      ws.current.close();
-      ws.current = null;
-    }
-
-    if (terminal.current) {
-      terminal.current.dispose();
-      terminal.current = null;
-      fitAddon.current = null;
-    }
-
-    setIsConnected(false);
-    setIsInitialized(false);
-    authUrlRef.current = '';
-    setAuthUrl('');
-    setAuthUrlCopyStatus('idle');
-    setIsAuthPanelHidden(false);
-
-    setTimeout(() => {
-      setIsRestarting(false);
-    }, 200);
-  };
-
-  useEffect(() => {
-    const currentSessionId = selectedSession?.id || null;
-
-    if (lastSessionId !== null && lastSessionId !== currentSessionId && isInitialized) {
-      disconnectFromShell();
-    }
-
-    setLastSessionId(currentSessionId);
-  }, [selectedSession?.id, isInitialized, disconnectFromShell]);
-
-  useEffect(() => {
-    if (!terminalRef.current || !selectedProject || isRestarting || terminal.current) {
-      return;
-    }
-
-
-    terminal.current = new Terminal({
-      cursorBlink: true,
-      fontSize: 14,
-      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
-      allowProposedApi: true,
-      allowTransparency: false,
-      convertEol: true,
-      scrollback: 10000,
-      tabStopWidth: 4,
-      windowsMode: false,
-      macOptionIsMeta: true,
-      macOptionClickForcesSelection: true,
-      theme: {
-        background: '#1e1e1e',
-        foreground: '#d4d4d4',
-        cursor: '#ffffff',
-        cursorAccent: '#1e1e1e',
-        selection: '#264f78',
-        selectionForeground: '#ffffff',
-        black: '#000000',
-        red: '#cd3131',
-        green: '#0dbc79',
-        yellow: '#e5e510',
-        blue: '#2472c8',
-        magenta: '#bc3fbc',
-        cyan: '#11a8cd',
-        white: '#e5e5e5',
-        brightBlack: '#666666',
-        brightRed: '#f14c4c',
-        brightGreen: '#23d18b',
-        brightYellow: '#f5f543',
-        brightBlue: '#3b8eea',
-        brightMagenta: '#d670d6',
-        brightCyan: '#29b8db',
-        brightWhite: '#ffffff',
-        extendedAnsi: [
-          '#000000', '#800000', '#008000', '#808000',
-          '#000080', '#800080', '#008080', '#c0c0c0',
-          '#808080', '#ff0000', '#00ff00', '#ffff00',
-          '#0000ff', '#ff00ff', '#00ffff', '#ffffff'
-        ]
-      }
-    });
-
-    fitAddon.current = new FitAddon();
-    const webglAddon = new WebglAddon();
-    const webLinksAddon = new WebLinksAddon();
-
-    terminal.current.loadAddon(fitAddon.current);
-    // Disable xterm link auto-detection in minimal (login) mode to avoid partial wrapped URL links.
-    if (!minimal) {
-      terminal.current.loadAddon(webLinksAddon);
-    }
-    // Note: ClipboardAddon removed - we handle clipboard operations manually in attachCustomKeyEventHandler
-
-    try {
-      terminal.current.loadAddon(webglAddon);
-    } catch (error) {
-      console.warn('[Shell] WebGL renderer unavailable, using Canvas fallback');
-    }
-
-    terminal.current.open(terminalRef.current);
-
-    terminal.current.attachCustomKeyEventHandler((event) => {
-      const activeAuthUrl = isCodexLoginCommand(initialCommandRef.current)
-        ? CODEX_DEVICE_AUTH_URL
-        : authUrlRef.current;
-
-      if (
-        event.type === 'keydown' &&
-        minimal &&
-        isPlainShellRef.current &&
-        activeAuthUrl &&
-        !event.ctrlKey &&
-        !event.metaKey &&
-        !event.altKey &&
-        event.key?.toLowerCase() === 'c'
-      ) {
-        copyAuthUrlToClipboard(activeAuthUrl).catch(() => {});
-      }
-
-      if (
-        event.type === 'keydown' &&
-        (event.ctrlKey || event.metaKey) &&
-        event.key?.toLowerCase() === 'c' &&
-        terminal.current.hasSelection()
-      ) {
-        event.preventDefault();
-        event.stopPropagation();
-        document.execCommand('copy');
-        return false;
-      }
-
-      if (
-        event.type === 'keydown' &&
-        (event.ctrlKey || event.metaKey) &&
-        event.key?.toLowerCase() === 'v'
-      ) {
-        // Block native browser/xterm paste so clipboard data is only sent after
-        // the explicit clipboard-read flow resolves (avoids duplicate pastes).
-        event.preventDefault();
-        event.stopPropagation();
-
-        navigator.clipboard.readText().then(text => {
-          if (ws.current && ws.current.readyState === WebSocket.OPEN) {
-            ws.current.send(JSON.stringify({
-              type: 'input',
-              data: text
-            }));
-          }
-        }).catch(() => {});
-        return false;
-      }
-
-      return true;
-    });
-
-    setTimeout(() => {
-      if (fitAddon.current) {
-        fitAddon.current.fit();
-        if (terminal.current && ws.current && ws.current.readyState === WebSocket.OPEN) {
-          ws.current.send(JSON.stringify({
-            type: 'resize',
-            cols: terminal.current.cols,
-            rows: terminal.current.rows
-          }));
-        }
-      }
-    }, 100);
-
-    setIsInitialized(true);
-    terminal.current.onData((data) => {
-      if (ws.current && ws.current.readyState === WebSocket.OPEN) {
-        ws.current.send(JSON.stringify({
-          type: 'input',
-          data: data
-        }));
-      }
-    });
-
-    const resizeObserver = new ResizeObserver(() => {
-      if (fitAddon.current && terminal.current) {
-        setTimeout(() => {
-          fitAddon.current.fit();
-          if (ws.current && ws.current.readyState === WebSocket.OPEN) {
-            ws.current.send(JSON.stringify({
-              type: 'resize',
-              cols: terminal.current.cols,
-              rows: terminal.current.rows
-            }));
-          }
-        }, 50);
-      }
-    });
-
-    if (terminalRef.current) {
-      resizeObserver.observe(terminalRef.current);
-    }
-
-    return () => {
-      resizeObserver.disconnect();
-
-      if (ws.current && (ws.current.readyState === WebSocket.OPEN || ws.current.readyState === WebSocket.CONNECTING)) {
-        ws.current.close();
-      }
-      ws.current = null;
-
-      if (terminal.current) {
-        terminal.current.dispose();
-        terminal.current = null;
-      }
-    };
-  }, [selectedProject?.path || selectedProject?.fullPath, isRestarting, minimal, copyAuthUrlToClipboard]);
-
-  useEffect(() => {
-    if (!autoConnect || !isInitialized || isConnecting || isConnected) return;
-    connectToShell();
-  }, [autoConnect, isInitialized, isConnecting, isConnected, connectToShell]);
-
-  if (!selectedProject) {
-    return (
-      <div className="h-full flex items-center justify-center">
-        <div className="text-center text-gray-500 dark:text-gray-400">
-          <div className="w-16 h-16 mx-auto mb-4 bg-gray-100 dark:bg-gray-800 rounded-full flex items-center justify-center">
-            <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v14a2 2 0 002 2z" />
-            </svg>
-          </div>
-          <h3 className="text-lg font-semibold mb-2">{t('shell.selectProject.title')}</h3>
-          <p>{t('shell.selectProject.description')}</p>
-        </div>
-      </div>
-    );
-  }
-
-  if (minimal) {
-    const displayAuthUrl = isCodexLoginCommand(initialCommand)
-      ? CODEX_DEVICE_AUTH_URL
-      : authUrl;
-    const hasAuthUrl = Boolean(displayAuthUrl);
-    const showMobileAuthPanel = hasAuthUrl && !isAuthPanelHidden;
-    const showMobileAuthPanelToggle = hasAuthUrl && isAuthPanelHidden;
-
-    return (
-      <div className="h-full w-full bg-gray-900 relative">
-        <div ref={terminalRef} className="h-full w-full focus:outline-none" style={{ outline: 'none' }} />
-        {showMobileAuthPanel && (
-          <div className="absolute inset-x-0 bottom-14 z-20 border-t border-gray-700/80 bg-gray-900/95 p-3 backdrop-blur-sm md:hidden">
-            <div className="flex flex-col gap-2">
-              <div className="flex items-center justify-between gap-2">
-                <p className="text-xs text-gray-300">Open or copy the login URL:</p>
-                <button
-                  type="button"
-                  onClick={() => setIsAuthPanelHidden(true)}
-                  className="rounded bg-gray-700 px-2 py-1 text-[10px] font-medium uppercase tracking-wide text-gray-100 hover:bg-gray-600"
-                >
-                  Hide
-                </button>
-              </div>
-              <input
-                type="text"
-                value={displayAuthUrl}
-                readOnly
-                onClick={(event) => event.currentTarget.select()}
-                className="w-full rounded border border-gray-600 bg-gray-800 px-2 py-1 text-xs text-gray-100 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                aria-label="Authentication URL"
-              />
-              <div className="flex items-center gap-2">
-                <button
-                  type="button"
-                  onClick={() => {
-                    openAuthUrlInBrowser(displayAuthUrl);
-                  }}
-                  className="flex-1 rounded bg-blue-600 px-3 py-2 text-xs font-medium text-white hover:bg-blue-700"
-                >
-                  Open URL
-                </button>
-                <button
-                  type="button"
-                  onClick={async () => {
-                    const copied = await copyAuthUrlToClipboard(displayAuthUrl);
-                    setAuthUrlCopyStatus(copied ? 'copied' : 'failed');
-                  }}
-                  className="flex-1 rounded bg-gray-700 px-3 py-2 text-xs font-medium text-white hover:bg-gray-600"
-                >
-                  {authUrlCopyStatus === 'copied' ? 'Copied' : 'Copy URL'}
-                </button>
-              </div>
-            </div>
-          </div>
-        )}
-        {showMobileAuthPanelToggle && (
-          <div className="absolute bottom-14 right-3 z-20 md:hidden">
-            <button
-              type="button"
-              onClick={() => setIsAuthPanelHidden(false)}
-              className="rounded bg-gray-800/95 px-3 py-2 text-xs font-medium text-gray-100 shadow-lg backdrop-blur-sm hover:bg-gray-700"
-            >
-              Show login URL
-            </button>
-          </div>
-        )}
-      </div>
-    );
-  }
-
-  return (
-    <div className="h-full flex flex-col bg-gray-900 w-full">
-      <div className="flex-shrink-0 bg-gray-800 border-b border-gray-700 px-4 py-2">
-        <div className="flex items-center justify-between">
-          <div className="flex items-center space-x-2">
-            <div className={`w-2 h-2 rounded-full ${isConnected ? 'bg-green-500' : 'bg-red-500'}`} />
-            {selectedSession && (
-              <span className="text-xs text-blue-300">
-                ({sessionDisplayNameShort}...)
-              </span>
-            )}
-            {!selectedSession && (
-              <span className="text-xs text-gray-400">{t('shell.status.newSession')}</span>
-            )}
-            {!isInitialized && (
-              <span className="text-xs text-yellow-400">{t('shell.status.initializing')}</span>
-            )}
-            {isRestarting && (
-              <span className="text-xs text-blue-400">{t('shell.status.restarting')}</span>
-            )}
-          </div>
-          <div className="flex items-center space-x-3">
-            {isConnected && (
-              <button
-                onClick={disconnectFromShell}
-                className="px-3 py-1 text-xs bg-red-600 text-white rounded hover:bg-red-700 flex items-center space-x-1"
-                title={t('shell.actions.disconnectTitle')}
-              >
-                <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                </svg>
-                <span>{t('shell.actions.disconnect')}</span>
-              </button>
-            )}
-
-            <button
-              onClick={restartShell}
-              disabled={isRestarting || isConnected}
-              className="text-xs text-gray-400 hover:text-white disabled:opacity-50 disabled:cursor-not-allowed flex items-center space-x-1"
-              title={t('shell.actions.restartTitle')}
-            >
-              <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
-              </svg>
-              <span>{t('shell.actions.restart')}</span>
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <div className="flex-1 p-2 overflow-hidden relative">
-        <div ref={terminalRef} className="h-full w-full focus:outline-none" style={{ outline: 'none' }} />
-
-        {!isInitialized && (
-          <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90">
-            <div className="text-white">{t('shell.loading')}</div>
-          </div>
-        )}
-
-        {isInitialized && !isConnected && !isConnecting && (
-          <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
-            <div className="text-center max-w-sm w-full">
-              <button
-                onClick={connectToShell}
-                className="px-6 py-3 bg-green-600 text-white rounded-lg hover:bg-green-700 transition-colors flex items-center justify-center space-x-2 text-base font-medium w-full sm:w-auto"
-                title={t('shell.actions.connectTitle')}
-              >
-                <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
-                </svg>
-                <span>{t('shell.actions.connect')}</span>
-              </button>
-              <p className="text-gray-400 text-sm mt-3 px-2">
-                {isPlainShell ?
-                  t('shell.runCommand', { command: initialCommand || t('shell.defaultCommand'), projectName: selectedProject.displayName }) :
-                  selectedSession ?
-                    t('shell.resumeSession', { displayName: sessionDisplayNameLong }) :
-                    t('shell.startSession')
-                }
-              </p>
-            </div>
-          </div>
-        )}
-
-        {isConnecting && (
-          <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
-            <div className="text-center max-w-sm w-full">
-              <div className="flex items-center justify-center space-x-3 text-yellow-400">
-                <div className="w-6 h-6 animate-spin rounded-full border-2 border-yellow-400 border-t-transparent"></div>
-                <span className="text-base font-medium">{t('shell.connecting')}</span>
-              </div>
-              <p className="text-gray-400 text-sm mt-3 px-2">
-                {isPlainShell ?
-                  t('shell.runCommand', { command: initialCommand || t('shell.defaultCommand'), projectName: selectedProject.displayName }) :
-                  t('shell.startCli', { projectName: selectedProject.displayName })
-                }
-              </p>
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-export default Shell;
diff --git a/src/components/StandaloneShell.jsx b/src/components/StandaloneShell.jsx
deleted file mode 100644
index 9f6f9f2..0000000
--- a/src/components/StandaloneShell.jsx
+++ /dev/null
@@ -1,105 +0,0 @@
-import React, { useState, useCallback } from 'react';
-import Shell from './Shell.jsx';
-
-/**
- * Generic Shell wrapper that can be used in tabs, modals, and other contexts.
- * Provides a flexible API for both standalone and session-based usage.
- *
- * @param {Object} project - Project object with name, fullPath/path, displayName
- * @param {Object} session - Session object (optional, for tab usage)
- * @param {string} command - Initial command to run (optional)
- * @param {boolean} isPlainShell - Use plain shell mode vs Claude CLI (default: auto-detect)
- * @param {boolean} autoConnect - Whether to auto-connect when mounted (default: true)
- * @param {function} onComplete - Callback when process completes (receives exitCode)
- * @param {function} onClose - Callback for close button (optional)
- * @param {string} title - Custom header title (optional)
- * @param {string} className - Additional CSS classes
- * @param {boolean} showHeader - Whether to show custom header (default: true)
- * @param {boolean} compact - Use compact layout (default: false)
- * @param {boolean} minimal - Use minimal mode: no header, no overlays, auto-connect (default: false)
- */
-function StandaloneShell({
-  project,
-  session = null,
-  command = null,
-  isPlainShell = null,
-  autoConnect = true,
-  onComplete = null,
-  onClose = null,
-  title = null,
-  className = "",
-  showHeader = true,
-  compact = false,
-  minimal = false
-}) {
-  const [isCompleted, setIsCompleted] = useState(false);
-
-  const shouldUsePlainShell = isPlainShell !== null ? isPlainShell : (command !== null);
-
-  const handleProcessComplete = useCallback((exitCode) => {
-    setIsCompleted(true);
-    if (onComplete) {
-      onComplete(exitCode);
-    }
-  }, [onComplete]);
-
-  if (!project) {
-    return (
-      <div className={`h-full flex items-center justify-center ${className}`}>
-        <div className="text-center text-gray-500 dark:text-gray-400">
-          <div className="w-16 h-16 mx-auto mb-4 bg-gray-100 dark:bg-gray-800 rounded-full flex items-center justify-center">
-            <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 002 2z" />
-            </svg>
-          </div>
-          <h3 className="text-lg font-semibold mb-2">No Project Selected</h3>
-          <p>A project is required to open a shell</p>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div className={`h-full w-full flex flex-col ${className}`}>
-      {/* Optional custom header */}
-      {!minimal && showHeader && title && (
-        <div className="flex-shrink-0 bg-gray-800 border-b border-gray-700 px-4 py-2">
-          <div className="flex items-center justify-between">
-            <div className="flex items-center space-x-2">
-              <h3 className="text-sm font-medium text-gray-200">{title}</h3>
-              {isCompleted && (
-                <span className="text-xs text-green-400">(Completed)</span>
-              )}
-            </div>
-            {onClose && (
-              <button
-                onClick={onClose}
-                className="text-gray-400 hover:text-white"
-                title="Close"
-              >
-                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                </svg>
-              </button>
-            )}
-          </div>
-        </div>
-      )}
-
-      {/* Shell component wrapper */}
-      <div className="flex-1 w-full min-h-0">
-        <Shell
-          selectedProject={project}
-          selectedSession={session}
-          initialCommand={command}
-          isPlainShell={shouldUsePlainShell}
-          onProcessComplete={handleProcessComplete}
-          minimal={minimal}
-          autoConnect={minimal ? true : autoConnect}
-        />
-      </div>
-    </div>
-  );
-}
-
-export default StandaloneShell;
\ No newline at end of file
diff --git a/src/components/TaskDetail.jsx b/src/components/TaskDetail.jsx
index 8316983..4d88186 100644
--- a/src/components/TaskDetail.jsx
+++ b/src/components/TaskDetail.jsx
@@ -4,6 +4,7 @@ import { cn } from '../lib/utils';
 import TaskIndicator from './TaskIndicator';
 import { api } from '../utils/api';
 import { useTaskMaster } from '../contexts/TaskMasterContext';
+import { copyTextToClipboard } from '../utils/clipboard';
 
 const TaskDetail = ({ 
   task, 
@@ -79,7 +80,7 @@ const TaskDetail = ({
   };
 
   const copyTaskId = () => {
-    navigator.clipboard.writeText(task.id.toString());
+    copyTextToClipboard(task.id.toString());
   };
 
   const getStatusConfig = (status) => {
diff --git a/src/components/TaskList.jsx b/src/components/TaskList.jsx
index 2fae577..b91bef2 100644
--- a/src/components/TaskList.jsx
+++ b/src/components/TaskList.jsx
@@ -4,7 +4,7 @@ import { cn } from '../lib/utils';
 import TaskCard from './TaskCard';
 import CreateTaskModal from './CreateTaskModal';
 import { useTaskMaster } from '../contexts/TaskMasterContext';
-import Shell from './Shell';
+import Shell from './shell/view/Shell';
 import { api } from '../utils/api';
 import { useTranslation } from 'react-i18next';
 
diff --git a/src/components/TaskMasterSetupWizard.jsx b/src/components/TaskMasterSetupWizard.jsx
index 813889b..6bcb173 100644
--- a/src/components/TaskMasterSetupWizard.jsx
+++ b/src/components/TaskMasterSetupWizard.jsx
@@ -2,6 +2,7 @@ import React, { useState, useEffect } from 'react';
 import { X, ChevronRight, ChevronLeft, CheckCircle, AlertCircle, Settings, Server, FileText, Sparkles, ExternalLink, Copy } from 'lucide-react';
 import { cn } from '../lib/utils';
 import { api } from '../utils/api';
+import { copyTextToClipboard } from '../utils/clipboard';
 
 const TaskMasterSetupWizard = ({ 
   isOpen = true, 
@@ -175,7 +176,7 @@ const TaskMasterSetupWizard = ({
     }
   }
 }`;
-    navigator.clipboard.writeText(mcpConfig);
+    copyTextToClipboard(mcpConfig);
   };
 
   const renderStepContent = () => {
diff --git a/src/components/chat/tools/components/OneLineDisplay.tsx b/src/components/chat/tools/components/OneLineDisplay.tsx
index 52fc0f1..a73bd22 100644
--- a/src/components/chat/tools/components/OneLineDisplay.tsx
+++ b/src/components/chat/tools/components/OneLineDisplay.tsx
@@ -1,9 +1,9 @@
 import React, { useState } from 'react';
+import { copyTextToClipboard } from '../../../../utils/clipboard';
 
 type ActionType = 'copy' | 'open-file' | 'jump-to-results' | 'none';
 
 interface OneLineDisplayProps {
-
   toolName: string;
   icon?: string;
   label?: string;
@@ -25,52 +25,6 @@ interface OneLineDisplayProps {
   toolId?: string;
 }
 
-// Fallback for environments where the async Clipboard API is unavailable or blocked.
-const copyWithLegacyExecCommand = (text: string): boolean => {
-  if (typeof document === 'undefined' || !document.body) {
-    return false;
-  }
-
-  const textarea = document.createElement('textarea');
-  textarea.value = text;
-  textarea.setAttribute('readonly', '');
-  textarea.style.position = 'fixed';
-  textarea.style.opacity = '0';
-  textarea.style.left = '-9999px';
-  document.body.appendChild(textarea);
-  textarea.select();
-  textarea.setSelectionRange(0, text.length);
-
-  let copied = false;
-  try {
-    copied = document.execCommand('copy');
-  } catch {
-    copied = false;
-  } finally {
-    document.body.removeChild(textarea);
-  }
-
-  return copied;
-};
-
-const copyTextToClipboard = async (text: string): Promise<boolean> => {
-  if (
-    typeof navigator !== 'undefined' &&
-    typeof window !== 'undefined' &&
-    window.isSecureContext &&
-    navigator.clipboard?.writeText
-  ) {
-    try {
-      await navigator.clipboard.writeText(text);
-      return true;
-    } catch {
-      // Fall back below when writeText is rejected (permissions/insecure contexts/browser limits).
-    }
-  }
-
-  return copyWithLegacyExecCommand(text);
-};
-
 /**
  * Unified one-line display for simple tool inputs and results
  * Used by: Bash, Read, Grep/Glob (minimized), TodoRead, etc.
@@ -92,7 +46,6 @@ export const OneLineDisplay: React.FC<OneLineDisplayProps> = ({
     border: 'border-gray-300 dark:border-gray-600',
     icon: 'text-gray-500 dark:text-gray-400'
   },
-  resultId,
   toolResult,
   toolId
 }) => {
diff --git a/src/components/chat/view/subcomponents/Markdown.tsx b/src/components/chat/view/subcomponents/Markdown.tsx
index 7a0e43c..bbb3db1 100644
--- a/src/components/chat/view/subcomponents/Markdown.tsx
+++ b/src/components/chat/view/subcomponents/Markdown.tsx
@@ -7,6 +7,7 @@ import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';
 import { useTranslation } from 'react-i18next';
 import { normalizeInlineCodeFences } from '../../utils/chatFormatting';
+import { copyTextToClipboard } from '../../../../utils/clipboard';
 
 type MarkdownProps = {
   children: React.ReactNode;
@@ -43,43 +44,6 @@ const CodeBlock = ({ node, inline, className, children, ...props }: CodeBlockPro
 
   const match = /language-(\w+)/.exec(className || '');
   const language = match ? match[1] : 'text';
-  const textToCopy = raw;
-
-  const handleCopy = () => {
-    const doSet = () => {
-      setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
-    };
-    try {
-      if (navigator && navigator.clipboard && navigator.clipboard.writeText) {
-        navigator.clipboard.writeText(textToCopy).then(doSet).catch(() => {
-          const ta = document.createElement('textarea');
-          ta.value = textToCopy;
-          ta.style.position = 'fixed';
-          ta.style.opacity = '0';
-          document.body.appendChild(ta);
-          ta.select();
-          try {
-            document.execCommand('copy');
-          } catch {}
-          document.body.removeChild(ta);
-          doSet();
-        });
-      } else {
-        const ta = document.createElement('textarea');
-        ta.value = textToCopy;
-        ta.style.position = 'fixed';
-        ta.style.opacity = '0';
-        document.body.appendChild(ta);
-        ta.select();
-        try {
-          document.execCommand('copy');
-        } catch {}
-        document.body.removeChild(ta);
-        doSet();
-      }
-    } catch {}
-  };
 
   return (
     <div className="relative group my-2">
@@ -89,7 +53,7 @@ const CodeBlock = ({ node, inline, className, children, ...props }: CodeBlockPro
 
       <button
         type="button"
-        onClick={handleCopy}
+        onClick={() => copyTextToClipboard(raw).then(() => setCopied(true))}
         className="absolute top-2 right-2 z-10 opacity-0 group-hover:opacity-100 focus:opacity-100 active:opacity-100 transition-opacity text-xs px-2 py-1 rounded-md bg-gray-700/80 hover:bg-gray-700 text-white border border-gray-600"
         title={copied ? t('codeBlock.copied') : t('codeBlock.copyCode')}
         aria-label={copied ? t('codeBlock.copied') : t('codeBlock.copyCode')}
diff --git a/src/components/code-editor/view/subcomponents/markdown/MarkdownCodeBlock.tsx b/src/components/code-editor/view/subcomponents/markdown/MarkdownCodeBlock.tsx
index 47ca835..3dfe615 100644
--- a/src/components/code-editor/view/subcomponents/markdown/MarkdownCodeBlock.tsx
+++ b/src/components/code-editor/view/subcomponents/markdown/MarkdownCodeBlock.tsx
@@ -2,6 +2,7 @@ import { useState } from 'react';
 import type { ComponentProps } from 'react';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { oneDark as prismOneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import { copyTextToClipboard } from '../../../../../utils/clipboard';
 
 type MarkdownCodeBlockProps = {
   inline?: boolean;
@@ -34,14 +35,6 @@ export default function MarkdownCodeBlock({
   const languageMatch = /language-(\w+)/.exec(className || '');
   const language = languageMatch ? languageMatch[1] : 'text';
 
-  const handleCopy = () => {
-    const copyPromise = navigator.clipboard?.writeText(rawContent);
-    void copyPromise?.then(() => {
-      setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
-    });
-  };
-
   return (
     <div className="relative group my-2">
       {language !== 'text' && (
@@ -50,7 +43,7 @@ export default function MarkdownCodeBlock({
 
       <button
         type="button"
-        onClick={handleCopy}
+        onClick={() => copyTextToClipboard(rawContent).then(() => setCopied(true))}
         className="absolute top-2 right-2 z-10 opacity-0 group-hover:opacity-100 transition-opacity text-xs px-2 py-1 rounded-md bg-gray-700/80 hover:bg-gray-700 text-white border border-gray-600"
       >
         {copied ? 'Copied!' : 'Copy'}
diff --git a/src/components/main-content/view/MainContent.tsx b/src/components/main-content/view/MainContent.tsx
index 1db0136..e0c3dbf 100644
--- a/src/components/main-content/view/MainContent.tsx
+++ b/src/components/main-content/view/MainContent.tsx
@@ -2,7 +2,7 @@ import React, { useEffect } from 'react';
 
 import ChatInterface from '../../chat/view/ChatInterface';
 import FileTree from '../../file-tree/view/FileTree';
-import StandaloneShell from '../../StandaloneShell';
+import StandaloneShell from '../../standalone-shell/view/StandaloneShell';
 import GitPanel from '../../git-panel/view/GitPanel';
 import ErrorBoundary from '../../ErrorBoundary';
 
@@ -18,8 +18,6 @@ import { useEditorSidebar } from '../../code-editor/hooks/useEditorSidebar';
 import EditorSidebar from '../../code-editor/view/EditorSidebar';
 import type { Project } from '../../../types/app';
 
-const AnyStandaloneShell = StandaloneShell as any;
-
 type TaskMasterContextValue = {
   currentProject?: Project | null;
   setCurrentProject?: ((project: Project) => void) | null;
@@ -147,7 +145,7 @@ function MainContent({
 
           {activeTab === 'shell' && (
             <div className="h-full w-full overflow-hidden">
-              <AnyStandaloneShell project={selectedProject} session={selectedSession} showHeader={false} />
+              <StandaloneShell project={selectedProject} session={selectedSession} showHeader={false} />
             </div>
           )}
 
diff --git a/src/components/settings/hooks/useCredentialsSettings.ts b/src/components/settings/hooks/useCredentialsSettings.ts
index 941ea65..4a9afc4 100644
--- a/src/components/settings/hooks/useCredentialsSettings.ts
+++ b/src/components/settings/hooks/useCredentialsSettings.ts
@@ -7,6 +7,7 @@ import type {
   GithubCredentialItem,
   GithubCredentialsResponse,
 } from '../view/tabs/api-settings/types';
+import { copyTextToClipboard } from '../../../utils/clipboard';
 
 type UseCredentialsSettingsArgs = {
   confirmDeleteApiKeyText: string;
@@ -205,7 +206,7 @@ export function useCredentialsSettings({
 
   const copyToClipboard = useCallback(async (text: string, id: string) => {
     try {
-      await navigator.clipboard.writeText(text);
+      await copyTextToClipboard(text);
       setCopiedKey(id);
       window.setTimeout(() => setCopiedKey(null), 2000);
     } catch (error) {
diff --git a/src/components/shell/constants/constants.ts b/src/components/shell/constants/constants.ts
new file mode 100644
index 0000000..3f4a1cf
--- /dev/null
+++ b/src/components/shell/constants/constants.ts
@@ -0,0 +1,63 @@
+import type { ITerminalOptions } from '@xterm/xterm';
+
+export const CODEX_DEVICE_AUTH_URL = 'https://auth.openai.com/codex/device';
+export const SHELL_RESTART_DELAY_MS = 200;
+export const TERMINAL_INIT_DELAY_MS = 100;
+export const TERMINAL_RESIZE_DELAY_MS = 50;
+
+export const TERMINAL_OPTIONS: ITerminalOptions = {
+  cursorBlink: true,
+  fontSize: 14,
+  fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+  allowProposedApi: true,
+  allowTransparency: false,
+  convertEol: true,
+  scrollback: 10000,
+  tabStopWidth: 4,
+  windowsMode: false,
+  macOptionIsMeta: true,
+  macOptionClickForcesSelection: true,
+  // Keep the runtime theme keys used by the previous JSX implementation.
+  theme: {
+    background: '#1e1e1e',
+    foreground: '#d4d4d4',
+    cursor: '#ffffff',
+    cursorAccent: '#1e1e1e',
+    selection: '#264f78',
+    selectionForeground: '#ffffff',
+    black: '#000000',
+    red: '#cd3131',
+    green: '#0dbc79',
+    yellow: '#e5e510',
+    blue: '#2472c8',
+    magenta: '#bc3fbc',
+    cyan: '#11a8cd',
+    white: '#e5e5e5',
+    brightBlack: '#666666',
+    brightRed: '#f14c4c',
+    brightGreen: '#23d18b',
+    brightYellow: '#f5f543',
+    brightBlue: '#3b8eea',
+    brightMagenta: '#d670d6',
+    brightCyan: '#29b8db',
+    brightWhite: '#ffffff',
+    extendedAnsi: [
+      '#000000',
+      '#800000',
+      '#008000',
+      '#808000',
+      '#000080',
+      '#800080',
+      '#008080',
+      '#c0c0c0',
+      '#808080',
+      '#ff0000',
+      '#00ff00',
+      '#ffff00',
+      '#0000ff',
+      '#ff00ff',
+      '#00ffff',
+      '#ffffff',
+    ],
+  } as any,
+};
diff --git a/src/components/shell/hooks/useShellConnection.ts b/src/components/shell/hooks/useShellConnection.ts
new file mode 100644
index 0000000..f7b62c9
--- /dev/null
+++ b/src/components/shell/hooks/useShellConnection.ts
@@ -0,0 +1,215 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { MutableRefObject } from 'react';
+import type { FitAddon } from '@xterm/addon-fit';
+import type { Terminal } from '@xterm/xterm';
+import type { Project, ProjectSession } from '../../../types/app';
+import { TERMINAL_INIT_DELAY_MS } from '../constants/constants';
+import { getShellWebSocketUrl, parseShellMessage, sendSocketMessage } from '../utils/socket';
+
+const ANSI_ESCAPE_REGEX = /\x1b\[[0-9;]*m/g;
+const PROCESS_EXIT_REGEX = /Process exited with code (\d+)/;
+
+type UseShellConnectionOptions = {
+  wsRef: MutableRefObject<WebSocket | null>;
+  terminalRef: MutableRefObject<Terminal | null>;
+  fitAddonRef: MutableRefObject<FitAddon | null>;
+  selectedProjectRef: MutableRefObject<Project | null | undefined>;
+  selectedSessionRef: MutableRefObject<ProjectSession | null | undefined>;
+  initialCommandRef: MutableRefObject<string | null | undefined>;
+  isPlainShellRef: MutableRefObject<boolean>;
+  onProcessCompleteRef: MutableRefObject<((exitCode: number) => void) | null | undefined>;
+  isInitialized: boolean;
+  autoConnect: boolean;
+  closeSocket: () => void;
+  clearTerminalScreen: () => void;
+  setAuthUrl: (nextAuthUrl: string) => void;
+};
+
+type UseShellConnectionResult = {
+  isConnected: boolean;
+  isConnecting: boolean;
+  closeSocket: () => void;
+  connectToShell: () => void;
+  disconnectFromShell: () => void;
+};
+
+export function useShellConnection({
+  wsRef,
+  terminalRef,
+  fitAddonRef,
+  selectedProjectRef,
+  selectedSessionRef,
+  initialCommandRef,
+  isPlainShellRef,
+  onProcessCompleteRef,
+  isInitialized,
+  autoConnect,
+  closeSocket,
+  clearTerminalScreen,
+  setAuthUrl,
+}: UseShellConnectionOptions): UseShellConnectionResult {
+  const [isConnected, setIsConnected] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+
+  const handleProcessCompletion = useCallback(
+    (output: string) => {
+      if (!isPlainShellRef.current || !onProcessCompleteRef.current) {
+        return;
+      }
+
+      const cleanOutput = output.replace(ANSI_ESCAPE_REGEX, '');
+      if (cleanOutput.includes('Process exited with code 0')) {
+        onProcessCompleteRef.current(0);
+        return;
+      }
+
+      const match = cleanOutput.match(PROCESS_EXIT_REGEX);
+      if (!match) {
+        return;
+      }
+
+      const exitCode = Number.parseInt(match[1], 10);
+      if (!Number.isNaN(exitCode) && exitCode !== 0) {
+        onProcessCompleteRef.current(exitCode);
+      }
+    },
+    [isPlainShellRef, onProcessCompleteRef],
+  );
+
+  const handleSocketMessage = useCallback(
+    (rawPayload: string) => {
+      const message = parseShellMessage(rawPayload);
+      if (!message) {
+        console.error('[Shell] Error handling WebSocket message:', rawPayload);
+        return;
+      }
+
+      if (message.type === 'output') {
+        const output = typeof message.data === 'string' ? message.data : '';
+        handleProcessCompletion(output);
+        terminalRef.current?.write(output);
+        return;
+      }
+
+      if (message.type === 'auth_url' || message.type === 'url_open') {
+        const nextAuthUrl = typeof message.url === 'string' ? message.url : '';
+        if (nextAuthUrl) {
+          setAuthUrl(nextAuthUrl);
+        }
+      }
+    },
+    [handleProcessCompletion, setAuthUrl, terminalRef],
+  );
+
+  const connectWebSocket = useCallback(() => {
+    if (isConnecting || isConnected) {
+      return;
+    }
+
+    try {
+      const wsUrl = getShellWebSocketUrl();
+      if (!wsUrl) {
+        return;
+      }
+
+      const socket = new WebSocket(wsUrl);
+      wsRef.current = socket;
+
+      socket.onopen = () => {
+        setIsConnected(true);
+        setIsConnecting(false);
+        setAuthUrl('');
+
+        window.setTimeout(() => {
+          const currentTerminal = terminalRef.current;
+          const currentFitAddon = fitAddonRef.current;
+          const currentProject = selectedProjectRef.current;
+          if (!currentTerminal || !currentFitAddon || !currentProject) {
+            return;
+          }
+
+          currentFitAddon.fit();
+
+          sendSocketMessage(wsRef.current, {
+            type: 'init',
+            projectPath: currentProject.fullPath || currentProject.path || '',
+            sessionId: isPlainShellRef.current ? null : selectedSessionRef.current?.id || null,
+            hasSession: isPlainShellRef.current ? false : Boolean(selectedSessionRef.current),
+            provider: isPlainShellRef.current
+              ? 'plain-shell'
+              : selectedSessionRef.current?.__provider || 'claude',
+            cols: currentTerminal.cols,
+            rows: currentTerminal.rows,
+            initialCommand: initialCommandRef.current,
+            isPlainShell: isPlainShellRef.current,
+          });
+        }, TERMINAL_INIT_DELAY_MS);
+      };
+
+      socket.onmessage = (event) => {
+        const rawPayload = typeof event.data === 'string' ? event.data : String(event.data ?? '');
+        handleSocketMessage(rawPayload);
+      };
+
+      socket.onclose = () => {
+        setIsConnected(false);
+        setIsConnecting(false);
+        clearTerminalScreen();
+      };
+
+      socket.onerror = () => {
+        setIsConnected(false);
+        setIsConnecting(false);
+      };
+    } catch {
+      setIsConnected(false);
+      setIsConnecting(false);
+    }
+  }, [
+    clearTerminalScreen,
+    fitAddonRef,
+    handleSocketMessage,
+    initialCommandRef,
+    isConnected,
+    isConnecting,
+    isPlainShellRef,
+    selectedProjectRef,
+    selectedSessionRef,
+    setAuthUrl,
+    terminalRef,
+    wsRef,
+  ]);
+
+  const connectToShell = useCallback(() => {
+    if (!isInitialized || isConnected || isConnecting) {
+      return;
+    }
+
+    setIsConnecting(true);
+    connectWebSocket();
+  }, [connectWebSocket, isConnected, isConnecting, isInitialized]);
+
+  const disconnectFromShell = useCallback(() => {
+    closeSocket();
+    clearTerminalScreen();
+    setIsConnected(false);
+    setIsConnecting(false);
+    setAuthUrl('');
+  }, [clearTerminalScreen, closeSocket, setAuthUrl]);
+
+  useEffect(() => {
+    if (!autoConnect || !isInitialized || isConnecting || isConnected) {
+      return;
+    }
+
+    connectToShell();
+  }, [autoConnect, connectToShell, isConnected, isConnecting, isInitialized]);
+
+  return {
+    isConnected,
+    isConnecting,
+    closeSocket,
+    connectToShell,
+    disconnectFromShell,
+  };
+}
diff --git a/src/components/shell/hooks/useShellRuntime.ts b/src/components/shell/hooks/useShellRuntime.ts
new file mode 100644
index 0000000..c334287
--- /dev/null
+++ b/src/components/shell/hooks/useShellRuntime.ts
@@ -0,0 +1,166 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { FitAddon } from '@xterm/addon-fit';
+import type { Terminal } from '@xterm/xterm';
+import { useShellConnection } from './useShellConnection';
+import { useShellTerminal } from './useShellTerminal';
+import type { UseShellRuntimeOptions, UseShellRuntimeResult } from '../types/types';
+import { copyTextToClipboard } from '../../../utils/clipboard';
+
+export function useShellRuntime({
+  selectedProject,
+  selectedSession,
+  initialCommand,
+  isPlainShell,
+  minimal,
+  autoConnect,
+  isRestarting,
+  onProcessComplete,
+}: UseShellRuntimeOptions): UseShellRuntimeResult {
+  const terminalContainerRef = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<Terminal | null>(null);
+  const fitAddonRef = useRef<FitAddon | null>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+
+  const [authUrl, setAuthUrl] = useState('');
+  const [authUrlVersion, setAuthUrlVersion] = useState(0);
+
+  const selectedProjectRef = useRef(selectedProject);
+  const selectedSessionRef = useRef(selectedSession);
+  const initialCommandRef = useRef(initialCommand);
+  const isPlainShellRef = useRef(isPlainShell);
+  const onProcessCompleteRef = useRef(onProcessComplete);
+  const authUrlRef = useRef('');
+  const lastSessionIdRef = useRef<string | null>(selectedSession?.id ?? null);
+
+  // Keep mutable values in refs so websocket handlers always read current data.
+  useEffect(() => {
+    selectedProjectRef.current = selectedProject;
+    selectedSessionRef.current = selectedSession;
+    initialCommandRef.current = initialCommand;
+    isPlainShellRef.current = isPlainShell;
+    onProcessCompleteRef.current = onProcessComplete;
+  }, [selectedProject, selectedSession, initialCommand, isPlainShell, onProcessComplete]);
+
+  const setCurrentAuthUrl = useCallback((nextAuthUrl: string) => {
+    authUrlRef.current = nextAuthUrl;
+    setAuthUrl(nextAuthUrl);
+    setAuthUrlVersion((previous) => previous + 1);
+  }, []);
+
+  const closeSocket = useCallback(() => {
+    const activeSocket = wsRef.current;
+    if (!activeSocket) {
+      return;
+    }
+
+    if (
+      activeSocket.readyState === WebSocket.OPEN ||
+      activeSocket.readyState === WebSocket.CONNECTING
+    ) {
+      activeSocket.close();
+    }
+
+    wsRef.current = null;
+  }, []);
+
+  const openAuthUrlInBrowser = useCallback((url = authUrlRef.current) => {
+    if (!url) {
+      return false;
+    }
+
+    const popup = window.open(url, '_blank', 'noopener,noreferrer');
+    if (popup) {
+      try {
+        popup.opener = null;
+      } catch {
+        // Ignore cross-origin restrictions when trying to null opener.
+      }
+      return true;
+    }
+
+    return false;
+  }, []);
+
+  const copyAuthUrlToClipboard = useCallback(async (url = authUrlRef.current) => {
+    if (!url) {
+      return false;
+    }
+
+    return copyTextToClipboard(url);
+  }, []);
+
+  const { isInitialized, clearTerminalScreen, disposeTerminal } = useShellTerminal({
+    terminalContainerRef,
+    terminalRef,
+    fitAddonRef,
+    wsRef,
+    selectedProject,
+    minimal,
+    isRestarting,
+    initialCommandRef,
+    isPlainShellRef,
+    authUrlRef,
+    copyAuthUrlToClipboard,
+    closeSocket,
+  });
+
+  const { isConnected, isConnecting, connectToShell, disconnectFromShell } = useShellConnection({
+    wsRef,
+    terminalRef,
+    fitAddonRef,
+    selectedProjectRef,
+    selectedSessionRef,
+    initialCommandRef,
+    isPlainShellRef,
+    onProcessCompleteRef,
+    isInitialized,
+    autoConnect,
+    closeSocket,
+    clearTerminalScreen,
+    setAuthUrl: setCurrentAuthUrl,
+  });
+
+  useEffect(() => {
+    if (!isRestarting) {
+      return;
+    }
+
+    disconnectFromShell();
+    disposeTerminal();
+  }, [disconnectFromShell, disposeTerminal, isRestarting]);
+
+  useEffect(() => {
+    if (selectedProject) {
+      return;
+    }
+
+    disconnectFromShell();
+    disposeTerminal();
+  }, [disconnectFromShell, disposeTerminal, selectedProject]);
+
+  useEffect(() => {
+    const currentSessionId = selectedSession?.id ?? null;
+    if (
+      lastSessionIdRef.current !== null &&
+      lastSessionIdRef.current !== currentSessionId &&
+      isInitialized
+    ) {
+      disconnectFromShell();
+    }
+
+    lastSessionIdRef.current = currentSessionId;
+  }, [disconnectFromShell, isInitialized, selectedSession?.id]);
+
+  return {
+    terminalContainerRef,
+    isConnected,
+    isInitialized,
+    isConnecting,
+    authUrl,
+    authUrlVersion,
+    connectToShell,
+    disconnectFromShell,
+    openAuthUrlInBrowser,
+    copyAuthUrlToClipboard,
+  };
+}
diff --git a/src/components/shell/hooks/useShellTerminal.ts b/src/components/shell/hooks/useShellTerminal.ts
new file mode 100644
index 0000000..ce0e787
--- /dev/null
+++ b/src/components/shell/hooks/useShellTerminal.ts
@@ -0,0 +1,233 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import { WebglAddon } from '@xterm/addon-webgl';
+import { Terminal } from '@xterm/xterm';
+import type { Project } from '../../../types/app';
+import {
+  CODEX_DEVICE_AUTH_URL,
+  TERMINAL_INIT_DELAY_MS,
+  TERMINAL_OPTIONS,
+  TERMINAL_RESIZE_DELAY_MS,
+} from '../constants/constants';
+import { isCodexLoginCommand } from '../utils/auth';
+import { sendSocketMessage } from '../utils/socket';
+import { ensureXtermFocusStyles } from '../utils/terminalStyles';
+
+type UseShellTerminalOptions = {
+  terminalContainerRef: RefObject<HTMLDivElement>;
+  terminalRef: MutableRefObject<Terminal | null>;
+  fitAddonRef: MutableRefObject<FitAddon | null>;
+  wsRef: MutableRefObject<WebSocket | null>;
+  selectedProject: Project | null | undefined;
+  minimal: boolean;
+  isRestarting: boolean;
+  initialCommandRef: MutableRefObject<string | null | undefined>;
+  isPlainShellRef: MutableRefObject<boolean>;
+  authUrlRef: MutableRefObject<string>;
+  copyAuthUrlToClipboard: (url?: string) => Promise<boolean>;
+  closeSocket: () => void;
+};
+
+type UseShellTerminalResult = {
+  isInitialized: boolean;
+  clearTerminalScreen: () => void;
+  disposeTerminal: () => void;
+};
+
+export function useShellTerminal({
+  terminalContainerRef,
+  terminalRef,
+  fitAddonRef,
+  wsRef,
+  selectedProject,
+  minimal,
+  isRestarting,
+  initialCommandRef,
+  isPlainShellRef,
+  authUrlRef,
+  copyAuthUrlToClipboard,
+  closeSocket,
+}: UseShellTerminalOptions): UseShellTerminalResult {
+  const [isInitialized, setIsInitialized] = useState(false);
+  const selectedProjectKey = selectedProject?.fullPath || selectedProject?.path || '';
+  const hasSelectedProject = Boolean(selectedProject);
+
+  useEffect(() => {
+    ensureXtermFocusStyles();
+  }, []);
+
+  const clearTerminalScreen = useCallback(() => {
+    if (!terminalRef.current) {
+      return;
+    }
+
+    terminalRef.current.clear();
+    terminalRef.current.write('\x1b[2J\x1b[H');
+  }, [terminalRef]);
+
+  const disposeTerminal = useCallback(() => {
+    if (terminalRef.current) {
+      terminalRef.current.dispose();
+      terminalRef.current = null;
+    }
+
+    fitAddonRef.current = null;
+    setIsInitialized(false);
+  }, [fitAddonRef, terminalRef]);
+
+  useEffect(() => {
+    if (!terminalContainerRef.current || !hasSelectedProject || isRestarting || terminalRef.current) {
+      return;
+    }
+
+    const nextTerminal = new Terminal(TERMINAL_OPTIONS);
+    terminalRef.current = nextTerminal;
+
+    const nextFitAddon = new FitAddon();
+    fitAddonRef.current = nextFitAddon;
+    nextTerminal.loadAddon(nextFitAddon);
+
+    // Avoid wrapped partial links in compact login flows.
+    if (!minimal) {
+      nextTerminal.loadAddon(new WebLinksAddon());
+    }
+
+    try {
+      nextTerminal.loadAddon(new WebglAddon());
+    } catch {
+      console.warn('[Shell] WebGL renderer unavailable, using Canvas fallback');
+    }
+
+    nextTerminal.open(terminalContainerRef.current);
+
+    nextTerminal.attachCustomKeyEventHandler((event) => {
+      const activeAuthUrl = isCodexLoginCommand(initialCommandRef.current)
+        ? CODEX_DEVICE_AUTH_URL
+        : authUrlRef.current;
+
+      if (
+        event.type === 'keydown' &&
+        minimal &&
+        isPlainShellRef.current &&
+        activeAuthUrl &&
+        !event.ctrlKey &&
+        !event.metaKey &&
+        !event.altKey &&
+        event.key?.toLowerCase() === 'c'
+      ) {
+        void copyAuthUrlToClipboard(activeAuthUrl);
+      }
+
+      if (
+        event.type === 'keydown' &&
+        (event.ctrlKey || event.metaKey) &&
+        event.key?.toLowerCase() === 'c' &&
+        nextTerminal.hasSelection()
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        document.execCommand('copy');
+        return false;
+      }
+
+      if (
+        event.type === 'keydown' &&
+        (event.ctrlKey || event.metaKey) &&
+        event.key?.toLowerCase() === 'v'
+      ) {
+        // Block native paste so data is only injected after clipboard-read resolves.
+        event.preventDefault();
+        event.stopPropagation();
+
+        if (typeof navigator !== 'undefined' && navigator.clipboard?.readText) {
+          navigator.clipboard
+            .readText()
+            .then((text) => {
+              sendSocketMessage(wsRef.current, {
+                type: 'input',
+                data: text,
+              });
+            })
+            .catch(() => {});
+        }
+
+        return false;
+      }
+
+      return true;
+    });
+
+    window.setTimeout(() => {
+      const currentFitAddon = fitAddonRef.current;
+      const currentTerminal = terminalRef.current;
+      if (!currentFitAddon || !currentTerminal) {
+        return;
+      }
+
+      currentFitAddon.fit();
+      sendSocketMessage(wsRef.current, {
+        type: 'resize',
+        cols: currentTerminal.cols,
+        rows: currentTerminal.rows,
+      });
+    }, TERMINAL_INIT_DELAY_MS);
+
+    setIsInitialized(true);
+
+    const dataSubscription = nextTerminal.onData((data) => {
+      sendSocketMessage(wsRef.current, {
+        type: 'input',
+        data,
+      });
+    });
+
+    const resizeObserver = new ResizeObserver(() => {
+      window.setTimeout(() => {
+        const currentFitAddon = fitAddonRef.current;
+        const currentTerminal = terminalRef.current;
+        if (!currentFitAddon || !currentTerminal) {
+          return;
+        }
+
+        currentFitAddon.fit();
+        sendSocketMessage(wsRef.current, {
+          type: 'resize',
+          cols: currentTerminal.cols,
+          rows: currentTerminal.rows,
+        });
+      }, TERMINAL_RESIZE_DELAY_MS);
+    });
+
+    resizeObserver.observe(terminalContainerRef.current);
+
+    return () => {
+      resizeObserver.disconnect();
+      dataSubscription.dispose();
+      closeSocket();
+      disposeTerminal();
+    };
+  }, [
+    authUrlRef,
+    closeSocket,
+    copyAuthUrlToClipboard,
+    disposeTerminal,
+    fitAddonRef,
+    initialCommandRef,
+    isPlainShellRef,
+    isRestarting,
+    minimal,
+    hasSelectedProject,
+    selectedProjectKey,
+    terminalContainerRef,
+    terminalRef,
+    wsRef,
+  ]);
+
+  return {
+    isInitialized,
+    clearTerminalScreen,
+    disposeTerminal,
+  };
+}
diff --git a/src/components/shell/types/types.ts b/src/components/shell/types/types.ts
new file mode 100644
index 0000000..b681ad7
--- /dev/null
+++ b/src/components/shell/types/types.ts
@@ -0,0 +1,73 @@
+import type { MutableRefObject, RefObject } from 'react';
+import type { FitAddon } from '@xterm/addon-fit';
+import type { Terminal } from '@xterm/xterm';
+import type { Project, ProjectSession } from '../../../types/app';
+
+export type AuthCopyStatus = 'idle' | 'copied' | 'failed';
+
+export type ShellInitMessage = {
+  type: 'init';
+  projectPath: string;
+  sessionId: string | null;
+  hasSession: boolean;
+  provider: string;
+  cols: number;
+  rows: number;
+  initialCommand: string | null | undefined;
+  isPlainShell: boolean;
+};
+
+export type ShellResizeMessage = {
+  type: 'resize';
+  cols: number;
+  rows: number;
+};
+
+export type ShellInputMessage = {
+  type: 'input';
+  data: string;
+};
+
+export type ShellOutgoingMessage = ShellInitMessage | ShellResizeMessage | ShellInputMessage;
+
+export type ShellIncomingMessage =
+  | { type: 'output'; data: string }
+  | { type: 'auth_url'; url?: string }
+  | { type: 'url_open'; url?: string }
+  | { type: string; [key: string]: unknown };
+
+export type UseShellRuntimeOptions = {
+  selectedProject: Project | null | undefined;
+  selectedSession: ProjectSession | null | undefined;
+  initialCommand: string | null | undefined;
+  isPlainShell: boolean;
+  minimal: boolean;
+  autoConnect: boolean;
+  isRestarting: boolean;
+  onProcessComplete?: ((exitCode: number) => void) | null;
+};
+
+export type ShellSharedRefs = {
+  wsRef: MutableRefObject<WebSocket | null>;
+  terminalRef: MutableRefObject<Terminal | null>;
+  fitAddonRef: MutableRefObject<FitAddon | null>;
+  authUrlRef: MutableRefObject<string>;
+  selectedProjectRef: MutableRefObject<Project | null | undefined>;
+  selectedSessionRef: MutableRefObject<ProjectSession | null | undefined>;
+  initialCommandRef: MutableRefObject<string | null | undefined>;
+  isPlainShellRef: MutableRefObject<boolean>;
+  onProcessCompleteRef: MutableRefObject<((exitCode: number) => void) | null | undefined>;
+};
+
+export type UseShellRuntimeResult = {
+  terminalContainerRef: RefObject<HTMLDivElement>;
+  isConnected: boolean;
+  isInitialized: boolean;
+  isConnecting: boolean;
+  authUrl: string;
+  authUrlVersion: number;
+  connectToShell: () => void;
+  disconnectFromShell: () => void;
+  openAuthUrlInBrowser: (url?: string) => boolean;
+  copyAuthUrlToClipboard: (url?: string) => Promise<boolean>;
+};
diff --git a/src/components/shell/utils/auth.ts b/src/components/shell/utils/auth.ts
new file mode 100644
index 0000000..d55041b
--- /dev/null
+++ b/src/components/shell/utils/auth.ts
@@ -0,0 +1,24 @@
+import type { ProjectSession } from '../../../types/app';
+import { CODEX_DEVICE_AUTH_URL } from '../constants/constants';
+
+export function isCodexLoginCommand(command: string | null | undefined): boolean {
+  return typeof command === 'string' && /\bcodex\s+login\b/i.test(command);
+}
+
+export function resolveAuthUrlForDisplay(command: string | null | undefined, authUrl: string): string {
+  if (isCodexLoginCommand(command)) {
+    return CODEX_DEVICE_AUTH_URL;
+  }
+
+  return authUrl;
+}
+
+export function getSessionDisplayName(session: ProjectSession | null | undefined): string | null {
+  if (!session) {
+    return null;
+  }
+
+  return session.__provider === 'cursor'
+    ? session.name || 'Untitled Session'
+    : session.summary || 'New Session';
+}
\ No newline at end of file
diff --git a/src/components/shell/utils/socket.ts b/src/components/shell/utils/socket.ts
new file mode 100644
index 0000000..6cb18d6
--- /dev/null
+++ b/src/components/shell/utils/socket.ts
@@ -0,0 +1,32 @@
+import { IS_PLATFORM } from '../../../constants/config';
+import type { ShellIncomingMessage, ShellOutgoingMessage } from '../types/types';
+
+export function getShellWebSocketUrl(): string | null {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+
+  if (IS_PLATFORM) {
+    return `${protocol}//${window.location.host}/shell`;
+  }
+
+  const token = localStorage.getItem('auth-token');
+  if (!token) {
+    console.error('No authentication token found for Shell WebSocket connection');
+    return null;
+  }
+
+  return `${protocol}//${window.location.host}/shell?token=${encodeURIComponent(token)}`;
+}
+
+export function parseShellMessage(payload: string): ShellIncomingMessage | null {
+  try {
+    return JSON.parse(payload) as ShellIncomingMessage;
+  } catch {
+    return null;
+  }
+}
+
+export function sendSocketMessage(ws: WebSocket | null, message: ShellOutgoingMessage): void {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(message));
+  }
+}
\ No newline at end of file
diff --git a/src/components/shell/utils/terminalStyles.ts b/src/components/shell/utils/terminalStyles.ts
new file mode 100644
index 0000000..387abe7
--- /dev/null
+++ b/src/components/shell/utils/terminalStyles.ts
@@ -0,0 +1,29 @@
+const XTERM_STYLE_ELEMENT_ID = 'shell-xterm-focus-style';
+
+const XTERM_FOCUS_STYLES = `
+  .xterm .xterm-screen {
+    outline: none !important;
+  }
+  .xterm:focus .xterm-screen {
+    outline: none !important;
+  }
+  .xterm-screen:focus {
+    outline: none !important;
+  }
+`;
+
+export function ensureXtermFocusStyles(): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  if (document.getElementById(XTERM_STYLE_ELEMENT_ID)) {
+    return;
+  }
+
+  const styleSheet = document.createElement('style');
+  styleSheet.id = XTERM_STYLE_ELEMENT_ID;
+  styleSheet.type = 'text/css';
+  styleSheet.innerText = XTERM_FOCUS_STYLES;
+  document.head.appendChild(styleSheet);
+}
\ No newline at end of file
diff --git a/src/components/shell/view/Shell.tsx b/src/components/shell/view/Shell.tsx
new file mode 100644
index 0000000..4fa563b
--- /dev/null
+++ b/src/components/shell/view/Shell.tsx
@@ -0,0 +1,162 @@
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import '@xterm/xterm/css/xterm.css';
+import type { Project, ProjectSession } from '../../../types/app';
+import { SHELL_RESTART_DELAY_MS } from '../constants/constants';
+import { useShellRuntime } from '../hooks/useShellRuntime';
+import { getSessionDisplayName } from '../utils/auth';
+import ShellConnectionOverlay from './subcomponents/ShellConnectionOverlay';
+import ShellEmptyState from './subcomponents/ShellEmptyState';
+import ShellHeader from './subcomponents/ShellHeader';
+import ShellMinimalView from './subcomponents/ShellMinimalView';
+
+type ShellProps = {
+  selectedProject?: Project | null;
+  selectedSession?: ProjectSession | null;
+  initialCommand?: string | null;
+  isPlainShell?: boolean;
+  onProcessComplete?: ((exitCode: number) => void) | null;
+  minimal?: boolean;
+  autoConnect?: boolean;
+  isActive?: boolean;
+};
+
+export default function Shell({
+  selectedProject = null,
+  selectedSession = null,
+  initialCommand = null,
+  isPlainShell = false,
+  onProcessComplete = null,
+  minimal = false,
+  autoConnect = false,
+  isActive,
+}: ShellProps) {
+  const { t } = useTranslation('chat');
+  const [isRestarting, setIsRestarting] = useState(false);
+
+  // Keep the public API stable for existing callers that still pass `isActive`.
+  void isActive;
+
+  const {
+    terminalContainerRef,
+    isConnected,
+    isInitialized,
+    isConnecting,
+    authUrl,
+    authUrlVersion,
+    connectToShell,
+    disconnectFromShell,
+    openAuthUrlInBrowser,
+    copyAuthUrlToClipboard,
+  } = useShellRuntime({
+    selectedProject,
+    selectedSession,
+    initialCommand,
+    isPlainShell,
+    minimal,
+    autoConnect,
+    isRestarting,
+    onProcessComplete,
+  });
+
+  const sessionDisplayName = useMemo(() => getSessionDisplayName(selectedSession), [selectedSession]);
+  const sessionDisplayNameShort = useMemo(
+    () => (sessionDisplayName ? sessionDisplayName.slice(0, 30) : null),
+    [sessionDisplayName],
+  );
+  const sessionDisplayNameLong = useMemo(
+    () => (sessionDisplayName ? sessionDisplayName.slice(0, 50) : null),
+    [sessionDisplayName],
+  );
+
+  const handleRestartShell = useCallback(() => {
+    setIsRestarting(true);
+    window.setTimeout(() => {
+      setIsRestarting(false);
+    }, SHELL_RESTART_DELAY_MS);
+  }, []);
+
+  if (!selectedProject) {
+    return (
+      <ShellEmptyState
+        title={t('shell.selectProject.title')}
+        description={t('shell.selectProject.description')}
+      />
+    );
+  }
+
+  if (minimal) {
+    return (
+      <ShellMinimalView
+        terminalContainerRef={terminalContainerRef}
+        authUrl={authUrl}
+        authUrlVersion={authUrlVersion}
+        initialCommand={initialCommand}
+        isConnected={isConnected}
+        openAuthUrlInBrowser={openAuthUrlInBrowser}
+        copyAuthUrlToClipboard={copyAuthUrlToClipboard}
+      />
+    );
+  }
+
+  const readyDescription = isPlainShell
+    ? t('shell.runCommand', {
+        command: initialCommand || t('shell.defaultCommand'),
+        projectName: selectedProject.displayName,
+      })
+    : selectedSession
+      ? t('shell.resumeSession', { displayName: sessionDisplayNameLong })
+      : t('shell.startSession');
+
+  const connectingDescription = isPlainShell
+    ? t('shell.runCommand', {
+        command: initialCommand || t('shell.defaultCommand'),
+        projectName: selectedProject.displayName,
+      })
+    : t('shell.startCli', { projectName: selectedProject.displayName });
+
+  const overlayMode = !isInitialized ? 'loading' : isConnecting ? 'connecting' : !isConnected ? 'connect' : null;
+  const overlayDescription = overlayMode === 'connecting' ? connectingDescription : readyDescription;
+
+  return (
+    <div className="h-full flex flex-col bg-gray-900 w-full">
+      <ShellHeader
+        isConnected={isConnected}
+        isInitialized={isInitialized}
+        isRestarting={isRestarting}
+        hasSession={Boolean(selectedSession)}
+        sessionDisplayNameShort={sessionDisplayNameShort}
+        onDisconnect={disconnectFromShell}
+        onRestart={handleRestartShell}
+        statusNewSessionText={t('shell.status.newSession')}
+        statusInitializingText={t('shell.status.initializing')}
+        statusRestartingText={t('shell.status.restarting')}
+        disconnectLabel={t('shell.actions.disconnect')}
+        disconnectTitle={t('shell.actions.disconnectTitle')}
+        restartLabel={t('shell.actions.restart')}
+        restartTitle={t('shell.actions.restartTitle')}
+        disableRestart={isRestarting || isConnected}
+      />
+
+      <div className="flex-1 p-2 overflow-hidden relative">
+        <div
+          ref={terminalContainerRef}
+          className="h-full w-full focus:outline-none"
+          style={{ outline: 'none' }}
+        />
+
+        {overlayMode && (
+          <ShellConnectionOverlay
+            mode={overlayMode}
+            description={overlayDescription}
+            loadingLabel={t('shell.loading')}
+            connectLabel={t('shell.actions.connect')}
+            connectTitle={t('shell.actions.connectTitle')}
+            connectingLabel={t('shell.connecting')}
+            onConnect={connectToShell}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/shell/view/subcomponents/ShellConnectionOverlay.tsx b/src/components/shell/view/subcomponents/ShellConnectionOverlay.tsx
new file mode 100644
index 0000000..32b2249
--- /dev/null
+++ b/src/components/shell/view/subcomponents/ShellConnectionOverlay.tsx
@@ -0,0 +1,59 @@
+type ShellConnectionOverlayProps = {
+  mode: 'loading' | 'connect' | 'connecting';
+  description: string;
+  loadingLabel: string;
+  connectLabel: string;
+  connectTitle: string;
+  connectingLabel: string;
+  onConnect: () => void;
+};
+
+export default function ShellConnectionOverlay({
+  mode,
+  description,
+  loadingLabel,
+  connectLabel,
+  connectTitle,
+  connectingLabel,
+  onConnect,
+}: ShellConnectionOverlayProps) {
+  if (mode === 'loading') {
+    return (
+      <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90">
+        <div className="text-white">{loadingLabel}</div>
+      </div>
+    );
+  }
+
+  if (mode === 'connect') {
+    return (
+      <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
+        <div className="text-center max-w-sm w-full">
+          <button
+            onClick={onConnect}
+            className="px-6 py-3 bg-green-600 text-white rounded-lg hover:bg-green-700 transition-colors flex items-center justify-center space-x-2 text-base font-medium w-full sm:w-auto"
+            title={connectTitle}
+          >
+            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
+            </svg>
+            <span>{connectLabel}</span>
+          </button>
+          <p className="text-gray-400 text-sm mt-3 px-2">{description}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
+      <div className="text-center max-w-sm w-full">
+        <div className="flex items-center justify-center space-x-3 text-yellow-400">
+          <div className="w-6 h-6 animate-spin rounded-full border-2 border-yellow-400 border-t-transparent"></div>
+          <span className="text-base font-medium">{connectingLabel}</span>
+        </div>
+        <p className="text-gray-400 text-sm mt-3 px-2">{description}</p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/shell/view/subcomponents/ShellEmptyState.tsx b/src/components/shell/view/subcomponents/ShellEmptyState.tsx
new file mode 100644
index 0000000..34e2bb1
--- /dev/null
+++ b/src/components/shell/view/subcomponents/ShellEmptyState.tsx
@@ -0,0 +1,25 @@
+type ShellEmptyStateProps = {
+  title: string;
+  description: string;
+};
+
+export default function ShellEmptyState({ title, description }: ShellEmptyStateProps) {
+  return (
+    <div className="h-full flex items-center justify-center">
+      <div className="text-center text-gray-500 dark:text-gray-400">
+        <div className="w-16 h-16 mx-auto mb-4 bg-gray-100 dark:bg-gray-800 rounded-full flex items-center justify-center">
+          <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v14a2 2 0 002 2z"
+            />
+          </svg>
+        </div>
+        <h3 className="text-lg font-semibold mb-2">{title}</h3>
+        <p>{description}</p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/shell/view/subcomponents/ShellHeader.tsx b/src/components/shell/view/subcomponents/ShellHeader.tsx
new file mode 100644
index 0000000..56131fd
--- /dev/null
+++ b/src/components/shell/view/subcomponents/ShellHeader.tsx
@@ -0,0 +1,87 @@
+type ShellHeaderProps = {
+  isConnected: boolean;
+  isInitialized: boolean;
+  isRestarting: boolean;
+  hasSession: boolean;
+  sessionDisplayNameShort: string | null;
+  onDisconnect: () => void;
+  onRestart: () => void;
+  statusNewSessionText: string;
+  statusInitializingText: string;
+  statusRestartingText: string;
+  disconnectLabel: string;
+  disconnectTitle: string;
+  restartLabel: string;
+  restartTitle: string;
+  disableRestart: boolean;
+};
+
+export default function ShellHeader({
+  isConnected,
+  isInitialized,
+  isRestarting,
+  hasSession,
+  sessionDisplayNameShort,
+  onDisconnect,
+  onRestart,
+  statusNewSessionText,
+  statusInitializingText,
+  statusRestartingText,
+  disconnectLabel,
+  disconnectTitle,
+  restartLabel,
+  restartTitle,
+  disableRestart,
+}: ShellHeaderProps) {
+  return (
+    <div className="flex-shrink-0 bg-gray-800 border-b border-gray-700 px-4 py-2">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-2">
+          <div className={`w-2 h-2 rounded-full ${isConnected ? 'bg-green-500' : 'bg-red-500'}`} />
+
+          {hasSession && sessionDisplayNameShort && (
+            <span className="text-xs text-blue-300">({sessionDisplayNameShort}...)</span>
+          )}
+
+          {!hasSession && <span className="text-xs text-gray-400">{statusNewSessionText}</span>}
+
+          {!isInitialized && <span className="text-xs text-yellow-400">{statusInitializingText}</span>}
+
+          {isRestarting && <span className="text-xs text-blue-400">{statusRestartingText}</span>}
+        </div>
+
+        <div className="flex items-center space-x-3">
+          {isConnected && (
+            <button
+              onClick={onDisconnect}
+              className="px-3 py-1 text-xs bg-red-600 text-white rounded hover:bg-red-700 flex items-center space-x-1"
+              title={disconnectTitle}
+            >
+              <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+              </svg>
+              <span>{disconnectLabel}</span>
+            </button>
+          )}
+
+          <button
+            onClick={onRestart}
+            disabled={disableRestart}
+            className="text-xs text-gray-400 hover:text-white disabled:opacity-50 disabled:cursor-not-allowed flex items-center space-x-1"
+            title={restartTitle}
+          >
+            <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"
+              />
+            </svg>
+            <span>{restartLabel}</span>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/shell/view/subcomponents/ShellMinimalView.tsx b/src/components/shell/view/subcomponents/ShellMinimalView.tsx
new file mode 100644
index 0000000..bdd2d40
--- /dev/null
+++ b/src/components/shell/view/subcomponents/ShellMinimalView.tsx
@@ -0,0 +1,113 @@
+import { useEffect, useMemo, useState } from 'react';
+import type { RefObject } from 'react';
+import type { AuthCopyStatus } from '../../types/types';
+import { resolveAuthUrlForDisplay } from '../../utils/auth';
+
+type ShellMinimalViewProps = {
+  terminalContainerRef: RefObject<HTMLDivElement>;
+  authUrl: string;
+  authUrlVersion: number;
+  initialCommand: string | null | undefined;
+  isConnected: boolean;
+  openAuthUrlInBrowser: (url: string) => boolean;
+  copyAuthUrlToClipboard: (url: string) => Promise<boolean>;
+};
+
+export default function ShellMinimalView({
+  terminalContainerRef,
+  authUrl,
+  authUrlVersion,
+  initialCommand,
+  isConnected,
+  openAuthUrlInBrowser,
+  copyAuthUrlToClipboard,
+}: ShellMinimalViewProps) {
+  const [authUrlCopyStatus, setAuthUrlCopyStatus] = useState<AuthCopyStatus>('idle');
+  const [isAuthPanelHidden, setIsAuthPanelHidden] = useState(false);
+
+  const displayAuthUrl = useMemo(
+    () => resolveAuthUrlForDisplay(initialCommand, authUrl),
+    [authUrl, initialCommand],
+  );
+
+  // Keep auth panel UI state local to minimal mode and reset it when connection/url changes.
+  useEffect(() => {
+    setAuthUrlCopyStatus('idle');
+    setIsAuthPanelHidden(false);
+  }, [authUrlVersion, displayAuthUrl, isConnected]);
+
+  const hasAuthUrl = Boolean(displayAuthUrl);
+  const showMobileAuthPanel = hasAuthUrl && !isAuthPanelHidden;
+  const showMobileAuthPanelToggle = hasAuthUrl && isAuthPanelHidden;
+
+  return (
+    <div className="h-full w-full bg-gray-900 relative">
+      <div
+        ref={terminalContainerRef}
+        className="h-full w-full focus:outline-none"
+        style={{ outline: 'none' }}
+      />
+
+      {showMobileAuthPanel && (
+        <div className="absolute inset-x-0 bottom-14 z-20 border-t border-gray-700/80 bg-gray-900/95 p-3 backdrop-blur-sm md:hidden">
+          <div className="flex flex-col gap-2">
+            <div className="flex items-center justify-between gap-2">
+              <p className="text-xs text-gray-300">Open or copy the login URL:</p>
+              <button
+                type="button"
+                onClick={() => setIsAuthPanelHidden(true)}
+                className="rounded bg-gray-700 px-2 py-1 text-[10px] font-medium uppercase tracking-wide text-gray-100 hover:bg-gray-600"
+              >
+                Hide
+              </button>
+            </div>
+
+            <input
+              type="text"
+              value={displayAuthUrl}
+              readOnly
+              onClick={(event) => event.currentTarget.select()}
+              className="w-full rounded border border-gray-600 bg-gray-800 px-2 py-1 text-xs text-gray-100 focus:outline-none focus:ring-1 focus:ring-blue-500"
+              aria-label="Authentication URL"
+            />
+
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                onClick={() => {
+                  openAuthUrlInBrowser(displayAuthUrl);
+                }}
+                className="flex-1 rounded bg-blue-600 px-3 py-2 text-xs font-medium text-white hover:bg-blue-700"
+              >
+                Open URL
+              </button>
+
+              <button
+                type="button"
+                onClick={async () => {
+                  const copied = await copyAuthUrlToClipboard(displayAuthUrl);
+                  setAuthUrlCopyStatus(copied ? 'copied' : 'failed');
+                }}
+                className="flex-1 rounded bg-gray-700 px-3 py-2 text-xs font-medium text-white hover:bg-gray-600"
+              >
+                {authUrlCopyStatus === 'copied' ? 'Copied' : 'Copy URL'}
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {showMobileAuthPanelToggle && (
+        <div className="absolute bottom-14 right-3 z-20 md:hidden">
+          <button
+            type="button"
+            onClick={() => setIsAuthPanelHidden(false)}
+            className="rounded bg-gray-800/95 px-3 py-2 text-xs font-medium text-gray-100 shadow-lg backdrop-blur-sm hover:bg-gray-700"
+          >
+            Show login URL
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/sidebar/view/modals/VersionUpgradeModal.tsx b/src/components/sidebar/view/modals/VersionUpgradeModal.tsx
index 891bd44..e787dee 100644
--- a/src/components/sidebar/view/modals/VersionUpgradeModal.tsx
+++ b/src/components/sidebar/view/modals/VersionUpgradeModal.tsx
@@ -2,6 +2,7 @@ import { useCallback, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { authenticatedFetch } from "../../../../utils/api";
 import { ReleaseInfo } from "../../../../types/sharedTypes";
+import { copyTextToClipboard } from "../../../../utils/clipboard";
 
 interface VersionUpgradeModalProps {
     isOpen: boolean;
@@ -22,7 +23,7 @@ export default function VersionUpgradeModal({
     const [isUpdating, setIsUpdating] = useState(false);
     const [updateOutput, setUpdateOutput] = useState('');
     const [updateError, setUpdateError] = useState('');
-    
+
     const handleUpdateNow = useCallback(async () => {
         setIsUpdating(true);
         setUpdateOutput('Starting update...\n');
@@ -170,9 +171,7 @@ export default function VersionUpgradeModal({
                     {!updateOutput && (
                         <>
                             <button
-                                onClick={() => {
-                                    navigator.clipboard.writeText('git checkout main && git pull && npm install');
-                                }}
+                                onClick={() => copyTextToClipboard('git checkout main && git pull && npm install')}
                                 className="flex-1 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-md transition-colors"
                             >
                                 {t('versionUpdate.buttons.copyCommand')}
diff --git a/src/components/standalone-shell/view/StandaloneShell.tsx b/src/components/standalone-shell/view/StandaloneShell.tsx
new file mode 100644
index 0000000..11cc1bd
--- /dev/null
+++ b/src/components/standalone-shell/view/StandaloneShell.tsx
@@ -0,0 +1,74 @@
+import { useCallback, useState } from 'react';
+import type { Project, ProjectSession } from '../../../types/app';
+import Shell from '../../shell/view/Shell';
+import StandaloneShellEmptyState from './subcomponents/StandaloneShellEmptyState';
+import StandaloneShellHeader from './subcomponents/StandaloneShellHeader';
+
+type StandaloneShellProps = {
+  project?: Project | null;
+  session?: ProjectSession | null;
+  command?: string | null;
+  isPlainShell?: boolean | null;
+  autoConnect?: boolean;
+  onComplete?: ((exitCode: number) => void) | null;
+  onClose?: (() => void) | null;
+  title?: string | null;
+  className?: string;
+  showHeader?: boolean;
+  compact?: boolean;
+  minimal?: boolean;
+};
+
+export default function StandaloneShell({
+  project = null,
+  session = null,
+  command = null,
+  isPlainShell = null,
+  autoConnect = true,
+  onComplete = null,
+  onClose = null,
+  title = null,
+  className = '',
+  showHeader = true,
+  compact = false,
+  minimal = false,
+}: StandaloneShellProps) {
+  const [isCompleted, setIsCompleted] = useState(false);
+
+  // Keep `compact` in the public API for compatibility with existing callers.
+  void compact;
+
+  const shouldUsePlainShell = isPlainShell !== null ? isPlainShell : command !== null;
+
+  const handleProcessComplete = useCallback(
+    (exitCode: number) => {
+      setIsCompleted(true);
+      onComplete?.(exitCode);
+    },
+    [onComplete],
+  );
+
+  if (!project) {
+    return <StandaloneShellEmptyState className={className} />;
+  }
+
+  return (
+    <div className={`h-full w-full flex flex-col ${className}`}>
+      {!minimal && showHeader && title && (
+        <StandaloneShellHeader title={title} isCompleted={isCompleted} onClose={onClose} />
+      )}
+
+      <div className="flex-1 w-full min-h-0">
+        <Shell
+          selectedProject={project}
+          selectedSession={session}
+          initialCommand={command}
+          isPlainShell={shouldUsePlainShell}
+          onProcessComplete={handleProcessComplete}
+          minimal={minimal}
+          autoConnect={minimal ? true : autoConnect}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/standalone-shell/view/subcomponents/StandaloneShellEmptyState.tsx b/src/components/standalone-shell/view/subcomponents/StandaloneShellEmptyState.tsx
new file mode 100644
index 0000000..1f9cf75
--- /dev/null
+++ b/src/components/standalone-shell/view/subcomponents/StandaloneShellEmptyState.tsx
@@ -0,0 +1,24 @@
+type StandaloneShellEmptyStateProps = {
+  className: string;
+};
+
+export default function StandaloneShellEmptyState({ className }: StandaloneShellEmptyStateProps) {
+  return (
+    <div className={`h-full flex items-center justify-center ${className}`}>
+      <div className="text-center text-gray-500 dark:text-gray-400">
+        <div className="w-16 h-16 mx-auto mb-4 bg-gray-100 dark:bg-gray-800 rounded-full flex items-center justify-center">
+          <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 002 2z"
+            />
+          </svg>
+        </div>
+        <h3 className="text-lg font-semibold mb-2">No Project Selected</h3>
+        <p>A project is required to open a shell</p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/standalone-shell/view/subcomponents/StandaloneShellHeader.tsx b/src/components/standalone-shell/view/subcomponents/StandaloneShellHeader.tsx
new file mode 100644
index 0000000..e988a92
--- /dev/null
+++ b/src/components/standalone-shell/view/subcomponents/StandaloneShellHeader.tsx
@@ -0,0 +1,30 @@
+type StandaloneShellHeaderProps = {
+  title: string;
+  isCompleted: boolean;
+  onClose?: (() => void) | null;
+};
+
+export default function StandaloneShellHeader({
+  title,
+  isCompleted,
+  onClose = null,
+}: StandaloneShellHeaderProps) {
+  return (
+    <div className="flex-shrink-0 bg-gray-800 border-b border-gray-700 px-4 py-2">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-2">
+          <h3 className="text-sm font-medium text-gray-200">{title}</h3>
+          {isCompleted && <span className="text-xs text-green-400">(Completed)</span>}
+        </div>
+
+        {onClose && (
+          <button onClick={onClose} className="text-gray-400 hover:text-white" title="Close">
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/utils/clipboard.ts b/src/utils/clipboard.ts
new file mode 100644
index 0000000..1fd9ed5
--- /dev/null
+++ b/src/utils/clipboard.ts
@@ -0,0 +1,50 @@
+function fallbackCopyToClipboard(text: string): boolean {
+  if (!text || typeof document === 'undefined') {
+    return false;
+  }
+
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.setAttribute('readonly', '');
+  textarea.style.position = 'fixed';
+  textarea.style.opacity = '0';
+  textarea.style.pointerEvents = 'none';
+
+  document.body.appendChild(textarea);
+  textarea.focus();
+  textarea.select();
+
+  let copied = false;
+  try {
+    copied = document.execCommand('copy');
+  } catch {
+    copied = false;
+  } finally {
+    document.body.removeChild(textarea);
+  }
+
+  return copied;
+}
+
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  if (!text) {
+    return false;
+  }
+
+  let copied = false;
+
+  try {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      copied = true;
+    }
+  } catch {
+    copied = false;
+  }
+
+  if (!copied) {
+    copied = fallbackCopyToClipboard(text);
+  }
+
+  return copied;
+}
\ No newline at end of file