{"id":33345474,"url":"https://github.com/crosschainer/shelled","last_synced_at":"2025-11-23T04:00:53.712Z","repository":{"id":325115963,"uuid":"1098435427","full_name":"crosschainer/shelled","owner":"crosschainer","description":"This project is a Windows shell replacement that aims to fully replace `explorer.exe` as the system shell, while keeping the UI layer purely HTML/CSS/JS for easy customization.","archived":false,"fork":false,"pushed_at":"2025-11-19T15:35:04.000Z","size":3331,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-19T17:24:36.526Z","etag":null,"topics":["win32","windows","windows-11","windows-desktop"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crosschainer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-17T17:26:24.000Z","updated_at":"2025-11-19T17:08:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/crosschainer/shelled","commit_stats":null,"previous_names":["crosschainer/shelled"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/crosschainer/shelled","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crosschainer%2Fshelled","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crosschainer%2Fshelled/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crosschainer%2Fshelled/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crosschainer%2Fshelled/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crosschainer","download_url":"https://codeload.github.com/crosschainer/shelled/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crosschainer%2Fshelled/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285898429,"owners_count":27250309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-23T02:00:06.149Z","response_time":135,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["win32","windows","windows-11","windows-desktop"],"created_at":"2025-11-22T03:00:37.767Z","updated_at":"2025-11-23T04:00:53.704Z","avatar_url":"https://github.com/crosschainer.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shelled – Modern Desktop Environment for Windows 11\n\n![Shelled Desktop Preview](preview.png)\n\nShelled is a **modern desktop environment replacement for Windows 11**.  \nInstead of skinning or theming the existing shell, Shelled replaces `explorer.exe`\nwith a native backbone plus a fully web-based desktop UI.\n\nThe goal is to give Windows the kind of separation you expect on Linux:\na small, testable core that talks to the OS, and a flexible HTML/CSS/JS\nenvironment that defines everything the user sees and interacts with.\n\n\u003e ⚠️ Shelled is experimental and can completely replace the normal Windows desktop.\n\u003e If you are not comfortable recovering from a broken shell, use the **safe test\n\u003e mode** below and keep Explorer as your main shell.\n\n---\n\n## Quick Start for Non‑technical Users\n\nIf you just want to *try* Shelled and see what it looks like, start here.\nYou do **not** need to edit the registry or replace Explorer for this.\n\n### What you need\n\n- Windows 11\n- .NET 8 Desktop Runtime (or SDK)\n- WebView2 runtime (usually already installed on Windows 11)\n\nYou can either download a prebuilt package (from the GitHub Releases page, if\navailable) or build it yourself using the instructions in the **Development**\nsection further down.\n\n### Option 1 – Try Shelled safely (recommended)\n\nThis runs Shelled **on top of** your existing desktop:\n\n- Explorer keeps running in the background.\n- Windows Taskbar will still show up when switching windows.\n- No registry keys are changed.\n- You can always close Shelled and go back to normal Windows.\n\n1. Build or download Shelled  \n   If you are building from source:\n   ```powershell\n   cd path\\to\\shelled\n   dotnet build -c Release\n   ```\n   After a successful build, `myshell-bootstrap.exe` will usually be in  \n   `src\\Shell.Bootstrap\\bin\\Release\\net8.0-windows7.0\\myshell-bootstrap.exe`.\n\n2. Open PowerShell in the folder that contains `myshell-bootstrap.exe`.\n\n3. Start Shelled in **development mode** (safe mode that never touches the shell):\n   ```powershell\n   $env:SHELL_DEV_MODE = \"1\"\n   .\\myshell-bootstrap.exe\n   ```\n\n4. A full-screen desktop will appear with Shelled’s taskbar, launcher and\n   workspace strip. Explorer is still running underneath; you can:\n   - Use `Alt+Tab` to switch back to other windows.\n   - Close the `myshell-bootstrap.exe` console window to exit Shelled.\n\n5. If something looks wrong or the UI glitches:\n   - Press `Ctrl+Shift+Esc` to open **Task Manager**.\n   - Use **File → Run new task** and type `explorer.exe` to bring the normal\n     desktop to the front.\n\nThis mode is the safest way to see whether you like Shelled without changing\nhow Windows starts.\n\n### Option 2 – Run Shelled as your real shell (Winlogon)\n\nThis makes Shelled start **instead of Explorer** when you sign in.\nOnly do this if you are comfortable with Windows recovery tools.\n\n**Strongly recommended before you begin:**\n\n- Create a separate local user account (for example `ShelledTest`) and use\n  that account for your first experiments.\n- Keep at least one administrator account that still uses the normal Windows\n  desktop.\n\n#### 1. Build a Release build\n\nIf you have not already:\n\n```powershell\ncd path\\to\\shelled\ndotnet build -c Release\n```\n\nAfter that, the bootstrap executable should be here (or similar):\n\n- `src\\Shell.Bootstrap\\bin\\Release\\net8.0-windows7.0\\myshell-bootstrap.exe`\n\nMake a note of the **full absolute path** to `myshell-bootstrap.exe`\n(for example `C:\\Users\\You\\shelled\\src\\Shell.Bootstrap\\bin\\Release\\net8.0-windows7.0\\myshell-bootstrap.exe`).\n\n#### 2. Register Shelled as the shell for one user\n\nShelled is designed to register itself as a **per-user** shell using the\nregistry key:\n\n- `HKEY_CURRENT_USER\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon\\Shell`\n\nTo point that value at `myshell-bootstrap.exe` for the currently logged-in\nuser:\n\n1. Sign in as your **test** user (not your main daily account).\n2. Open **PowerShell as administrator**.\n3. Run the following, replacing the path with your actual bootstrap path:\n\n   ```powershell\n   $shellKey = 'HKCU:\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon'\n   $exePath  = 'C:\\full\\path\\to\\myshell-bootstrap.exe'\n\n   if (-not (Test-Path $shellKey)) {\n     New-Item -Path $shellKey -Force | Out-Null\n   }\n\n   Set-ItemProperty -Path $shellKey -Name Shell -Value $exePath\n   ```\n\n4. Sign out and sign back in as the same user. Windows should now start\n   Shelled instead of Explorer.\n\n\u003e Note: In *normal shell mode* you should **not** set `SHELL_DEV_MODE` or\n\u003e `SHELL_TEST_MODE`. Those modes are only for safe testing and deliberately\n\u003e prevent permanent shell changes.\n\n#### 3. Getting back to Explorer\n\nIf you want to go back to the default Windows desktop, you have several\noptions:\n\n- **Fast way (panic command)**  \n  1. Press `Ctrl+Shift+Esc` to open **Task Manager**.  \n  2. Use **File → Run new task** and browse to `myshell-bootstrap.exe`.  \n  3. Run it with the panic switch:\n     ```powershell\n     myshell-bootstrap.exe --panic\n     ```\n     This tries to restore the Winlogon `Shell` registry value to\n     `explorer.exe` and then launches Explorer.\n\n- **Manual way (registry)**  \n  1. From Task Manager, run `regedit`.  \n  2. Go to `HKEY_CURRENT_USER\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon`.  \n  3. Set `Shell` to `explorer.exe` (or delete the value).  \n  4. Sign out and sign back in.\n\n---\n\n## Overview\n\nConceptually Shelled has four layers, implemented by several projects:\n\n- **Shell Core (`Shell.Core`)**  \n  Pure domain logic with no Win32 calls. Tracks windows, workspaces, tray icons,\n  hotkeys, and overall shell state.\n\n- **OS Adapters (`Shell.Adapters.Win32`)**  \n  The only place that talks to the Windows API. Implements:\n  - `IWindowSystem` – window enumeration, visibility, focus\n  - `IProcessLauncher` – launching apps\n  - `ITrayHost` – system tray hosting\n  - `IHotkeyRegistry` – global hotkeys\n  - `ISystemEventHandler` – shutdown / logoff events\n\n- **Core Hosting \u0026 Bootstrap (`Shell.Service`, `Shell.Bootstrap`, `Shell.Bootstrap.Infrastructure`)**  \n  Long-running core service, shell entrypoint executable, and shell-registration utilities.\n\n- **UI Host \u0026 Web Desktop (`Shell.Bridge.WebView`, `Shell.UI.Web`)**  \n  Borderless WebView2 host plus an HTML/CSS/JS desktop environment.\n\nEverything above the adapters is cross-platform in principle; Windows 11 is\nthe primary runtime because of WebView2 and the Win32 shell APIs.\n\n### Solution layout\n\nCurrent top-level projects:\n\n- `src/Shell.Core` – core models, events, configuration, and `ShellCore` state machine.\n- `src/Shell.Adapters.Win32` – Win32 implementations of shell interfaces.\n- `src/Shell.Service` – `ShellCoreService` hosting core + adapters + UI host.\n- `src/Shell.Bridge.WebView` – `ShellUiHost` WebView2 app and JS bridge.\n- `src/Shell.Bootstrap` – `myshell-bootstrap.exe` entrypoint used as the Winlogon shell.\n- `src/Shell.Bootstrap.Infrastructure` – shared bootstrap utilities (for example `ShellRegistration`).\n- `src/Shell.UI.Web` – web desktop (HTML/CSS/JS) and its tests.\n- `tests/Shell.Tests` – core + adapter + UI host unit/integration tests.\n- `tests/Shell.Bootstrap.Tests` – bootstrap / shell registration tests.\n- `tests/Shell.Service.Tests` – service lifecycle tests.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Windows 11 (WebView2 and shell APIs).\n- .NET 8 SDK.\n- Node.js (for UI tests).\n- Visual Studio 2022 or VS Code.\n\n### Build \u0026 Test (Native)\n\n```powershell\ndotnet restore\ndotnet build\ndotnet test\n```\n\nThe test suite includes:\n\n- Core unit tests (pure domain logic).\n- Adapter integration tests (Win32, but safe-mode aware).\n- Service / bootstrap tests.\n\n### UI Development \u0026 Tests\n\nFrom `src/Shell.UI.Web`:\n\n```bash\nnpm install\nnpm test\n```\n\nThe UI tests include:\n\n- State/store unit tests.\n- DOM-level integration tests with a fake core.\n- E2E-style tests using `node:test` + `jsdom` for:\n  - Launcher behavior and app launch wiring.\n  - Workspace switching UI (`TEST-E2E-02`).\n  - Tray icon rendering and click routing (`TEST-E2E-03`).\n\n---\n\nIf you’re interested in running a modern, web-powered desktop environment\non Windows 11, Shelled is the experimental playground to do it. Contributions,\nissues, and ideas are welcome.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrosschainer%2Fshelled","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrosschainer%2Fshelled","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrosschainer%2Fshelled/lists"}